Por que escalar o n8n com Kubernetes e Helm?

Rodar o n8n sem orquestração limita você a uma única máquina, o que quebra em dois cenários: pico de carga (workflows HTTP/webhook lotam a CPU) ou falha de hardware (container cai e ninguém conserta). Um workflow simples que envia 100 e-mails por segundo trava o n8n em Docker puro, enquanto no Kubernetes ele escala automaticamente para 3 réplicas sem perder requisições. Sem persistência configurada, você perde todos os workflows ao reiniciar o container — já viu perder 50 automações porque o Docker atualizou sem aviso?

O Helm resolve o problema de configuração repetitiva: ao invés de escrever 10 arquivos YAML manualmente, você ajusta 5 parâmetros no values.yaml e aplica tudo de uma vez. Para quem já tentou orquestrar n8n com Docker Compose em produção, a diferença é clara: o Helm padroniza o deploy, enquanto o Kubernetes garante alta disponibilidade e escalabilidade horizontal nativa.

Dica de quem usa na prática: Se você começou com n8n no Docker, o primeiro sinal de que precisa migrar é quando os logs mostram Error: connect ECONNREFUSED localhost:5432 — porque o banco de dados não sobreviveu ao reboot. No Kubernetes, o erro desaparece quando você usa PersistentVolumeClaims para o PostgreSQL.

Pré-requisitos: o que você precisa antes de começar

Você só precisa de 4 coisas para rodar n8n em produção no Kubernetes:

• Conta em provedor de cloud: AWS (EKS), GCP (GKE), Azure (AKS) ou DigitalOcean (DOKS).
• Ferramentas CLI: kubectl (v1.27+) e Helm (v3.12+).
• Domínio e SSL: um domínio apontando para seu cluster e certificado TLS (usaremos Let's Encrypt).
• n8n Helm Chart: o repositório oficial mantido pela comunidade.

Instale as ferramentas:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Documentação oficial do n8n lista variáveis de ambiente essenciais para produção.

Instalando o cluster Kubernetes: escolha do provedor e configuração inicial

A escolha do provedor define custo, complexidade e tempo de setup. Comparação rápida:

Para este guia, usaremos o DigitalOcean DOKS (mais barato e simples). Siga o passo a passo:

1. Crie um cluster via painel ou CLI:

   doctl kubernetes cluster create n8n-prod \
     --region nyc1 \
     --node-pool "name=worker-pool;size=s-2vcpu-4gb;count=3"

2. Configure o kubectl:

   doctl kubernetes cluster kubeconfig save n8n-prod

3. Verifique os nós:

   kubectl get nodes
   # Saída esperada:
   NAME                STATUS   ROLES    AGE   VERSION
   pool-abc123-xyz     Ready       5m    v1.27.4

Curiosidade técnica: O DOKS usa containerd como runtime padrão, enquanto EKS ainda permite Docker. Se seus workflows dependem de Docker-in-Docker, ajuste o values.yaml para usar dind: true no deployment do n8n.

Instalando o Helm e adicionando o repositório oficial do n8n

O Helm é o "gerenciador de pacotes" do Kubernetes. Instale e configure:

1. Instale o Helm:

   helm version --client
   # Deve mostrar: version.BuildInfo{Version:"v3.12.0"}

2. Adicione o repositório oficial do n8n (mantido pela comunidade):

   helm repo add n8n https://n8nio.github.io/helm-charts/
   helm repo update

3. Verifique as versões disponíveis:

   helm search repo n8n/n8n --versions
   # Saída esperada:
   n8n/n8n    0.25.0    1.33.0    Self-host n8n in Kubernetes

Link útil: Repositório oficial do Helm Chart do n8n no GitHub.

Dica de quem usa na prática: Sempre verifique a versão do chart antes de instalar. O n8n 1.33.0 requer chart 0.25.0 ou superior — versões antigas não suportam Redis nativo.

Configurando o Helm Chart do n8n para produção: values.yaml explicado

O values.yaml é onde você define tudo: réplicas, banco de dados, autenticação e persistência. Abaixo, a tabela com parâmetros essenciais e valores recomendados para produção:

Crie um arquivo values-prod.yaml com o conteúdo acima. Para ajustar a senha automaticamente, use:

export N8N_PASSWORD=$(openssl rand -base64 16)
echo "auth.password: $N8N_PASSWORD" >> values-prod.yaml

Curiosidade técnica: O Helm Chart do n8n não usa StatefulSet para o n8n em si (apenas para o PostgreSQL). Isso porque o n8n é stateless por design — os dados ficam no banco externo ou no PersistentVolume.

Deploy do n8n com PostgreSQL e Redis: garantindo persistência e performance

O n8n precisa de dois componentes externos para funcionar bem em produção: um banco de dados relacional (PostgreSQL) e um cache/queue (Redis). Vamos configurar ambos via Helm Chart:

1. Instale o PostgreSQL (usaremos o Bitnami Chart):

   helm repo add bitnami https://charts.bitnami.com/bitnami
   helm install postgres bitnami/postgresql \
     --set auth.postgresPassword=SENHA_POSTGRES \
     --set primary.persistence.size=20Gi

2. Instale o Redis (também Bitnami):

   helm install redis bitnami/redis \
     --set auth.enabled=true \
     --set auth.password=SENHA_REDIS

3. Configure as credenciais no values-prod.yaml:

   database:
     type: postgres
     host: postgres-primary
     port: 5432
     database: n8n
     user: postgres
     password: SENHA_POSTGRES
   redis:
   enabled: true
   host: redis-master
   port: 6379
   password: SENHA_REDIS

4. Faça o deploy do n8n:

   helm upgrade --install n8n-prod n8n/n8n \
     -f values-prod.yaml \
     --namespace n8n --create-namespace

Snippet útil: Para verificar se o PostgreSQL está pronto:

kubectl get pods -n n8n
# Saída esperada:
NAME                            READY   STATUS    RESTARTS   AGE
n8n-prod-n8n-abc123-xyz         1/1     Running   0          2m
postgres-primary-0              1/1     Running   0          5m
redis-master-0                  1/1     Running   0          3m

Dica de quem usa na prática: Sempre use PersistentVolumeClaims com storageClassName: do-block-storage no DigitalOcean (ou equivalente no seu provedor). Sem isso, seus dados somem ao reiniciar o pod.

Configurando Ingress Controller e SSL/TLS para acesso seguro

Sem Ingress, você acessa o n8n apenas via NodePort ou LoadBalancer — lento e inseguro. Vamos usar o ingress-nginx + cert-manager para HTTPS automático:

1. Instale o ingress-nginx:

   helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
   helm install ingress-nginx ingress-nginx/ingress-nginx \
     --set controller.service.type=LoadBalancer

2. Instale o cert-manager (para Let's Encrypt):

   helm repo add jetstack https://charts.jetstack.io
   helm install cert-manager jetstack/cert-manager \
     --set installCRDs=true

3. Crie um ClusterIssuer (substitua your-email@dominio.com):

   cat <

4. Configure o Ingress no values-prod.yaml:

   ingress:
     enabled: true
     className: nginx
     hosts:
       - host: n8n.seudominio.com
         paths:
           - path: /
             pathType: Prefix
     tls:
       - secretName: n8n-tls
         hosts:
           - n8n.seudominio.com

5. Aplique as mudanças:

   helm upgrade --install n8n-prod n8n/n8n \
     -f values-prod.yaml \
     --namespace n8n

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: n8n-ingress
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - n8n.seudominio.com
    secretName: n8n-tls
  rules:
  - host: n8n.seudominio.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: n8n-prod-n8n
            port:
              number: 5678

kubectl autoscale deployment n8n-prod-n8n \
  --cpu-percent=70 \
  --min=3 \
  --max=10 \
  --namespace n8n

kubectl get hpa -n n8n
# Saída esperada:
NAME            REFERENCE                  TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
n8n-prod-n8n    Deployment/n8n-prod-n8n     50%/70%   3         10        5          10m

kubectl exec -it postgres-primary-0 -n n8n -- bash -c \
  "pg_dump -U postgres -d n8n" > n8n_backup_$(date +%Y%m%d).sql

# Restaurar PostgreSQL
kubectl cp ./n8n_backup_20240101.dump n8n/postgres-primary-0:/tmp/n8n_backup.dump
kubectl exec -it postgres-primary-0 -n n8n -- bash -c \
  "pg_restore -U postgres -d n8n /tmp/n8n_backup.dump --clean --if-exists"
Restaurar PV do n8n
kubectl cp ./n8n_data_backup_20240101.tar.gz n8n/n8n-prod-n8n-new-xyz:/tmp/n8n_data.tar.gz
kubectl exec -it n8n-prod-n8n-new-xyz -n n8n — bash -c 

“tar xzvf /tmp/n8n_data.tar.gz -C /home/node/.n8n”

velero install \
  --provider aws \
  --plugins velero/velero-plugin-for-aws:v1.0.0 \
  --bucket n8n-backups \
  --secret-file ./credentials-velero

cat <

docker stack deploy -c docker-compose.yml n8n

version: '3.8'
services:
  n8n:
    image: n8nio/n8n:1.33.0
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    environment:
      - DB_TYPE=postgres
      - DB_POSTGRES_DB=n8n
      - DB_POSTGRES_HOST=postgres
      - DB_POSTGRES_USER=postgres
      - DB_POSTGRES_PASSWORD=SENHA_POSTGRES
postgres:
image: postgres:15
volumes:
- postgres_data:/var/lib/postgresql/data
environment:
- POSTGRES_PASSWORD=SENHA_POSTGRES
volumes:
n8n_data:
postgres_data:

Quer mais sobre o assunto? Veja todos os artigos de APIs & Dev ou a lista completa de artigos.