19d97159ce
- aula-08: adicionar key cluster-config no secret do autoscaler - aula-09,10,11,12,14,15: adicionar pausa DNS antes do helm install (Let's Encrypt precisa do DNS configurado para emitir certificado) - aula-09,10,11: corrigir anotação cert-manager.io/cluster-issuer (--set do Helm interpreta pontos como separadores de nested keys) - aula-10: corrigir load_config com set -e (exit silencioso) - aula-10: adicionar teste rápido do registry no README
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
- Cluster Talos na Hetzner (aula-08) com:
- Hetzner CSI Driver (StorageClass: hcloud-volumes)
- NGINX Ingress Controller com LoadBalancer
- kubectl instalado
- 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:
- Hostname do n8n (ex:
n8n.kube.quest) - FQDN completo - Usa CloudFlare? (com proxy/CDN)
- 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.questempresa-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.