workshop/aula-09

Aula 09 - n8n via Helm (Cluster Hetzner Cloud)

Deploy do n8n workflow automation em cluster Kubernetes na Hetzner Cloud com volumes persistentes, LoadBalancer e TLS configurável.

Arquitetura

                         Internet
                            │
                            ▼
                  ┌─────────────────┐
                  │  LoadBalancer   │
                  │  (Hetzner LB)   │
                  └────────┬────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │     NGINX Ingress      │
              │  n8n.{domain}:443      │
              └───────────┬────────────┘
                          │
┌─────────────────────────┼─────────────────────────┐
│             Namespace: n8n                         │
│                         │                          │
│    ┌────────────────────┼────────────────────┐    │
│    │                    ▼                    │    │
│    │              ┌──────────┐               │    │
│    │              │   Main   │               │    │
│    │              │  (n8n)   │               │    │
│    │              └────┬─────┘               │    │
│    │                   │                     │    │
│    │     ┌─────────────┼─────────────┐      │    │
│    │     ▼             ▼             ▼      │    │
│    │ ┌───────┐   ┌──────────┐   ┌────────┐ │    │
│    │ │Workers│   │ Webhooks │   │  MCP   │ │    │
│    │ │ (2-5) │   │  (1-3)   │   │Webhook │ │    │
│    │ └───────┘   └──────────┘   └────────┘ │    │
│    │                                        │    │
│    │              Queue Mode                │    │
│    └────────────────────────────────────────┘    │
│                         │                         │
│         ┌───────────────┼───────────────┐        │
│         ▼                               ▼        │
│    ┌──────────┐                   ┌──────────┐   │
│    │PostgreSQL│                   │  Redis   │   │
│    │  (10Gi)  │                   │  (10Gi)  │   │
│    │ hcloud   │                   │ hcloud   │   │
│    └──────────┘                   └──────────┘   │
└───────────────────────────────────────────────────┘
                    Hetzner Cloud

Pré-requisitos

1. Cluster Talos na Hetzner (aula-08) com:
   • Hetzner CSI Driver (StorageClass: hcloud-volumes)
   • NGINX Ingress Controller com LoadBalancer
2. kubectl instalado
3. Helm 3.x instalado

Contexto do Cluster

Esta aula usa o cluster Kubernetes provisionado na aula-08. O kubeconfig foi gerado automaticamente pelo OpenTofu e está em aula-08/kubeconfig.

# Verificar se o cluster está acessível
export KUBECONFIG=$(pwd)/../aula-08/kubeconfig
kubectl cluster-info

# Esperado:
# Kubernetes control plane is running at https://<floating-ip>:6443

Instalação

cd aula-09

# Configurar acesso ao cluster (kubeconfig da aula-08)
export KUBECONFIG=$(pwd)/../aula-08/kubeconfig

# Executar setup interativo
chmod +x setup.sh
./setup.sh

O script é interativo e pergunta:

1. Hostname do n8n (ex: n8n.kube.quest) - FQDN completo
2. Usa CloudFlare? (com proxy/CDN)
3. Ativar Let's Encrypt? (se não usar CloudFlare)

Opções de TLS

Cenário	TLS Provider	Configuração
CloudFlare (proxy)	CloudFlare Edge	Sem cert-manager, TLS na borda
Outro DNS + Let's Encrypt	cert-manager	HTTP-01 challenge automático
Outro DNS + HTTP	Nenhum	Apenas HTTP (dev/workshop)

Exemplo de Instalação

═══════════════════════════════════════════════════
  n8n no Kubernetes (Hetzner Cloud)
═══════════════════════════════════════════════════

Digite o hostname do n8n (ex: n8n.kube.quest): n8n.kube.quest

Você usa CloudFlare para DNS?
  1) Sim (com proxy/CDN ativado - ícone laranja)
  2) Não
Escolha [1/2]: 1

[INFO] CloudFlare irá gerenciar TLS automaticamente na edge
[OK] Configuração salva em .env

...instalação...

═══════════════════════════════════════════════════
  Configure o DNS
═══════════════════════════════════════════════════

No painel do CloudFlare (https://dash.cloudflare.com):

  Tipo:     A
  Nome:     n8n
  Conteúdo: 123.45.67.89
  Proxy:    ✓ (ícone laranja)

O CloudFlare cuida do TLS automaticamente!

Acesse: https://n8n.kube.quest

Gerenciamento com Helm

Comandos Básicos

# Listar releases instalados
helm list -n n8n

# Ver histórico de revisões
helm history n8n -n n8n

# Ver valores atuais
helm get values n8n -n n8n

# Ver status do release
helm status n8n -n n8n

Rollback

Rollback não precisa de variáveis - o Helm guarda o estado de cada revisão:

# Ver histórico primeiro
helm history n8n -n n8n

# Rollback para revisão anterior
helm rollback n8n -n n8n

# Rollback para revisão específica
helm rollback n8n 2 -n n8n

Upgrade

O upgrade precisa das variáveis do .env porque o Helm constrói os --set dinamicamente:

# Carregar variáveis
source .env

# Construir comando de upgrade (ex: atualizar para 2.4.6)
helm upgrade n8n community-charts/n8n \
  -n n8n \
  -f custom-values.yaml \
  --set "ingress.hosts[0].host=${N8N_HOST}" \
  --set "ingress.hosts[0].paths[0].path=/" \
  --set "ingress.hosts[0].paths[0].pathType=Prefix" \
  --set "webhook.url=https://${N8N_HOST}" \
  --wait \
  --timeout 10m \
  --set "main.image.tag=2.4.6"

Dica: Para upgrades em produção, re-execute ./setup.sh - ele detecta a instalação existente e faz upgrade com todos os parâmetros corretos (TLS, secure cookies, etc.).

Acompanhar o upgrade:

kubectl get pods -n n8n -w

Componentes Instalados

Da aula-08 (infraestrutura):

• Hetzner CSI Driver (StorageClass: hcloud-volumes)
• NGINX Ingress Controller com LoadBalancer

Instalados por este script:

• cert-manager (se Let's Encrypt ativado)
• n8n com todos os componentes

Componente	Réplicas	Recursos	Volume
Main (n8n)	1	256Mi-1Gi RAM	10Gi
Workers	2-5 (HPA)	256Mi-512Mi RAM	-
Webhooks	1-3 (HPA)	256Mi-512Mi RAM	-
PostgreSQL	1	-	10Gi
Redis	1	-	10Gi

Total volumes: 30Gi (~$1.45/mês)

Multi-Tenant: Adicionar Clientes

Para provisionar n8n para múltiplos clientes em namespaces separados:

# Adicionar novo cliente
./add-client.sh acme

# Isso cria:
#   - Namespace: acme-n8n
#   - n8n em: https://acme-n8n.{domain}
#   - Organização Gitea: /acme/ (se Gitea instalado - aula-10)

O script add-client.sh herda a configuração do .env gerado pelo setup.sh.

Padrão de Domínio

Os clientes usam o padrão {cliente}-n8n.{domain}:

• acme-n8n.kube.quest
• empresa-n8n.kube.quest

Se você configurou um wildcard DNS (*.kube.quest), os novos clientes funcionam automaticamente.

Arquivo de Configuração

O setup.sh gera um arquivo .env com as configurações:

# aula-09/.env (gerado automaticamente)
N8N_HOST=n8n.kube.quest
DOMAIN=kube.quest
USE_CLOUDFLARE=true
USE_LETSENCRYPT=false
LETSENCRYPT_EMAIL=

Este arquivo é usado pelo add-client.sh e em re-execuções do setup.sh.

Comandos Úteis

# Ver pods
kubectl get pods -n n8n

# Ver logs do n8n
kubectl logs -f -n n8n deployment/n8n

# Ver autoscaling
kubectl get hpa -n n8n

# Ver volumes
kubectl get pvc -n n8n

# Ver certificado (se Let's Encrypt)
kubectl get certificate -n n8n

# Desinstalar (apenas n8n)
./cleanup.sh

# Ou manualmente:
helm uninstall n8n -n n8n
kubectl delete pvc --all -n n8n
kubectl delete ns n8n

Nota: O cleanup.sh remove apenas n8n, clientes e cert-manager. A infraestrutura (CSI Driver, NGINX Ingress, LoadBalancer) é mantida pois pertence à aula-08.

Custos Estimados

Recurso	Custo/mês
Volumes (3x 10Gi)	~$1.45
Worker (compartilhado)	~$0.80
Total por cliente	~$2.25

Para Ambiente Local

Se você quer testar em um cluster local (Docker Desktop, minikube), veja a aula-06.