Workflow Automation

n8n Helm Chart Setup: Kubernetes Deployment Guide

J
James Eriksson
··12 min read

The n8n Helm chart lets you deploy your automation platform on any Kubernetes cluster. It's maintained by the n8n team and distributed as an OCI artifact at oci://ghcr.io/n8n-io/n8n-helm-chart/n8n. This guide walks through installation, database setup, queue mode with Redis workers, and when managed hosting makes more sense than self-hosted complexity.

What Is the n8n Helm Chart and Why Use It?

The n8n Helm chart is a Kubernetes manifest template that automates deployment of n8n's distributed workflow engine. Helm simplifies repetitive YAML, letting you define configuration once in a values file and deploy to any cluster without rewriting manifests.

The official chart is maintained by the n8n team. Two community alternatives exist with active development: community-charts/n8n for basic setups, and 8gears/n8n-helm-chart with 709 GitHub stars, supporting queue mode, Redis scaling, Postgres, webhooks, and task runners.

You should use Helm instead of Docker Compose when you need multi-node scaling (multiple n8n instances handling workflows in parallel), automatic restarts and self-healing through Kubernetes StatefulSets, persistent storage that survives pod restarts, load balancing across worker nodes, and rolling updates without downtime.

If your team runs fewer than three automation workflows or you're prototyping, Docker Compose or a single managed container service may be simpler. But if you're building a production platform that handles hundreds of workflows daily, Helm on Kubernetes is the right foundation.

The official chart requires Helm 3.8 or later, a Kubernetes cluster (EKS, GKE, AKS, or on-premises), and kubectl access.

Prerequisites: Tools, Cluster, and Databases

Before you deploy, install these tools on your machine:

  1. Helm 3.8+: Download from the Helm project website. Verify with helm version.
  2. kubectl: Install from the Kubernetes documentation. Test with kubectl cluster-info.
  3. A Kubernetes cluster: Any managed service (AWS EKS, Google GKE, Azure AKS) or self-hosted cluster works. Minimum: 2 CPU cores, 4GB RAM available.

You'll also need a PostgreSQL database. The chart can spawn one as a Helm dependency, but for production you should use a managed database instead. PostgreSQL 17 or 18 are n8n's recommended versions; PostgreSQL 16 is compatible. Allocate minimum 1 CPU and 2GB RAM for a small deployment. Encryption at rest is essential if handling sensitive workflows.

Alternatively, the chart defaults to SQLite for single-node setups, but it cannot handle queue mode (multiple n8n instances) because SQLite locks on writes, causing job failures. Never use SQLite in production.

For production workloads, enable Redis 7+ (or Valkey, a Redis fork, as a drop-in replacement). Redis is optional for single-node, but required for queue mode. If you have no existing Redis, deploy it via Helm dependency or use a managed service like AWS ElastiCache or Azure Cache for Redis.

Network prerequisites include an Ingress controller (nginx, AWS ALB, etc.) if you want external access, a TLS certificate (self-signed or Let's Encrypt via cert-manager), and outbound HTTPS access for n8n to fetch public nodes and integrations.

Example cluster sizing: Dev deployments need 2 nodes with 2 CPU and 4GB RAM each. Production queue mode needs 3+ nodes with 4 CPU and 8GB RAM each, plus Redis cluster (3+ nodes).

Step 1: Install the Official n8n Helm Chart

Add the n8n OCI registry to Helm:

helm repo add n8n oci://ghcr.io/n8n-io/n8n-helm-chart
helm repo update

Pull the chart locally to review or customize:

helm pull n8n/n8n --version 1.0.0 --untar
cd n8n

Create a minimal values.yaml:


# values-minimal.yaml
replicaCount: 1

image:
  tag: "1.76.0"

persistence:
  enabled: true
  storageClassName: "standard"
  size: "5Gi"

postgresql:
  enabled: true
  auth:
    username: "n8n"
    password: "changeme"
    database: "n8n"

ingress:
  enabled: false

Dry-run the deployment to catch errors:

helm install n8n n8n/n8n -f values-minimal.yaml --dry-run --debug

If the dry-run succeeds, install:

helm install n8n n8n/n8n -f values-minimal.yaml --namespace default

Watch the deployment:

kubectl rollout status deployment/n8n -n default
kubectl logs -f deployment/n8n -n default

The n8n pod should reach Running state within 60-90 seconds. Access it via port-forward:

kubectl port-forward svc/n8n 5678:80 -n default

Open the application in your browser. You'll see n8n's setup wizard where you can create your first user and start building workflows. If you skip this wizard, the credentials step is marked incomplete until you return.

Step 2: Configure PostgreSQL and Persistence

By default, the chart deploys PostgreSQL as a pod. For production, use an external managed database to avoid data loss if the Postgres pod crashes. This is not optional for any production system.

Retrieve your managed database credentials (hostname, port, username, password) and update values.yaml:

postgresql:
  enabled: false

externalPostgresql:
  host: "my-db.c5ibgh67dshsk.us-east-1.rds.amazonaws.com"
  port: 5432
  username: "n8nadmin"
  password: "your-strong-password"
  database: "n8n_prod"
  ssl: true

If you're deploying to a development cluster and want simplicity, the default PostgreSQL is acceptable for testing only:

postgresql:
  enabled: true
  persistence:
    enabled: true
    storageClassName: "standard"
    size: "10Gi"
  auth:
    username: "n8n"
    password: "changeme"
    database: "n8n"

Both n8n and PostgreSQL need persistent storage. Set a StorageClass that exists in your cluster:

kubectl get storageclass

Common options: AWS uses gp3 or ebs-csi-driver; GCP uses standard or premium-rwo; Azure uses managed-premium or default; on-premises uses local or nfs.

Add to values.yaml:

persistence:
  enabled: true
  storageClassName: "gp3"
  size: "10Gi"

n8n encrypts sensitive data (credentials, API keys) at rest using an encryption key. Set it explicitly:

env:
  - name: DB_ENCRYPTION_KEY
    valueFrom:
      secretKeyRef:
        name: n8n-secrets
        key: encryption-key

Create the secret:

openssl rand -base64 32 > encryption-key.txt
kubectl create secret generic n8n-secrets --from-file=encryption-key.txt

Store the encryption key safely; losing it makes encrypted data unrecoverable.

Step 3: Set Up Queue Mode with Redis and Worker Scaling

Queue mode lets multiple n8n instances process workflows in parallel. The main instance handles UI and webhooks; worker instances execute workflows from a job queue. Redis coordinates the queue and prevents duplicate job execution.

Update values.yaml:

replicaCount: 1

n8n:
  mode: "queue"
  
  redis:
    host: "my-redis.hb5xup9d.ng.0001.use1.cache.amazonaws.com"
    port: 6379
    password: "your-redis-password"

  webhook:
    enabled: true
    path: "/webhook"

workers:
  enabled: true
  replicas: 3
  concurrency: 5

If you don't have Redis yet, deploy it via Helm by adding and updating the Bitnami Helm repository:

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

Extract the Redis hostname:

kubectl get svc redis-master -o jsonpath='{.spec.clusterIP}'

Workers execute n8n workflows. Each worker can handle multiple jobs in parallel based on concurrency. If your workflows are CPU-bound, set concurrency lower; if I/O-bound (API calls, database queries), set it higher.

Scaling formula: Total workflows per hour divided by average workflow duration in seconds divided by concurrency per worker equals workers needed. Example: 1000 workflows per hour, 120 seconds average, 5 concurrency = 1000 / 120 / 5 = 1.6, so deploy 2-3 workers.

Scale workers with:

kubectl scale deployment n8n-worker --replicas=5

Or update values.yaml and re-run helm upgrade:

helm upgrade n8n n8n/n8n -f values-queue.yaml --set workers.replicas=5

Check job queue status:

kubectl logs -f deployment/n8n-worker-0 -n default | grep "queue"

Watch worker scaling with HPA (Horizontal Pod Autoscaler). The chart can auto-scale workers based on queue depth:

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetQueueDepth: 50

Step 4: Configure Ingress and External Access

By default, n8n is only accessible inside the cluster. To expose it externally, set up an Ingress.

Add the Kubernetes community repository for nginx-ingress:

helm install nginx ingress-nginx/ingress-nginx

For automatic Let's Encrypt certificate renewal, add the Jetstack repository and install cert-manager:

helm install cert-manager jetstack/cert-manager --set installCRDs=true

Create a ClusterIssuer for Let's Encrypt by applying a manifest that configures cert-manager to use the Let's Encrypt production ACME v2 server endpoint. See the official cert-manager documentation for the current ACME server configuration:

kubectl apply -f - << 'EOF'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

Update values.yaml:

ingress:
  enabled: true
  ingressClassName: "nginx"
  hosts:
    - host: "n8n.yourcompany.com"
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: n8n-tls
      hosts:
        - n8n.yourcompany.com
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"

Apply:

helm upgrade n8n n8n/n8n -f values.yaml

Verify ingress status:

kubectl get ingress n8n -o wide

Once DNS propagates (1-5 minutes), access your n8n instance via the configured domain.

For workflows triggered by external systems, set the external webhook URL:

env:
  - name: WEBHOOK_URL
    value: "https://n8n.yourcompany.com"

This tells n8n to include the full external URL in webhook payloads, so external systems can reach it.

Common Configuration Pitfalls & Troubleshooting

IPv6 and IPv4 mixed environments can cause silent failures. If your cluster uses IPv6 and Redis connection fails, explicitly set Redis to IPv4:

redis:
  host: "127.0.0.1"
  port: 6379

Job queueing silently fails when mixed IPv6/IPv4 networks cannot communicate. The connection succeeds but commands hang.

Database connection timeouts mean n8n cannot reach PostgreSQL. Test from the n8n pod:

kubectl exec -it deployment/n8n -- psql -h postgresql.default -U n8n -d n8n -c "SELECT 1;"

If it times out, the database may be in a different namespace or security group. Verify the database hostname is reachable from the pod's network namespace, security groups or network policies allow traffic on port 5432, and database credentials are correct.

Workers not picking up jobs means the queue is not configured or Redis is unreachable:

kubectl logs deployment/n8n -n default | grep -i "queue"
kubectl logs deployment/n8n-worker-0 -n default | grep -i "queue"

Check Redis connectivity:

kubectl exec -it deployment/n8n -- redis-cli -h your-redis-host PING

If Redis returns PONG, the queue is working. If not, verify credentials and hostname.

Pod startup timeouts in CrashLoopBackOff state mean the pod is failing to start:

kubectl describe pod <pod-name>
kubectl logs <pod-name> --previous

Common causes: database migrations failing (n8n tries to initialize the database on startup; if it hangs, the DB is unreachable or permissions are wrong), insufficient memory (increase pod memory limits in values.yaml), or missing persistent volume (if PVC is pending, the pod cannot start).

n8n has readiness and liveness probes. If they fail:

kubectl get pod <pod-name> -o yaml | grep -A 5 "readinessProbe"
kubectl logs <pod-name> | grep -i "health"

Increase probe delay if startup is slow:

livenessProbe:
  initialDelaySeconds: 60
  periodSeconds: 10

When to Move to Managed n8n Hosting

Self-hosted n8n on Kubernetes works, but it carries operational overhead. Opsily provides managed n8n hosting, letting your team focus on workflows instead of infrastructure.

Cluster maintenance consumes time: Kubernetes upgrades, security patches, node health monitoring, and storage migration are ongoing. Scaling uncertainty is real: queue mode with Redis requires tuning workers, concurrency settings, and Pod Disruption Budgets; getting it wrong causes job losses or data corruption.

Backup and recovery are your responsibility: Postgres backups, encryption key rotation, disaster recovery, and verification testing fall on your ops team. Data loss is permanent. Monitoring and debugging becomes complex: n8n logs are spread across multiple pods; correlating worker failures with job execution requires distributed tracing.

Cost predictability suffers: reserved Kubernetes capacity (3+ nodes, 4CPU each) plus managed Postgres and Redis add up quickly, often exceeding a managed solution.

Opsily handles all of this. We manage Kubernetes infrastructure and updates, automatic scaling (workers and compute), daily encrypted backups with point-in-time recovery, TLS, CDN, and DDoS protection, and monitoring, alerting, and debugging dashboards.

For teams with 1-2 engineers, managed hosting reduces operational load and risk. For teams with dedicated DevOps, self-hosted may offer cost savings, but only if you amortize the engineering time. Compare what fits your team at the pricing page or by deploying on your Kubernetes cluster using the official n8n Helm chart.

Frequently Asked Questions

What is an n8n Helm chart?

A Helm chart is a template for deploying n8n on Kubernetes. It defines pod configuration, database setup, storage, and networking as reusable YAML, so you don't have to write everything from scratch.

How do I install n8n using Helm?

Add the OCI registry with helm repo add n8n oci://ghcr.io/n8n-io/n8n-helm-chart, create a values.yaml file with your database and ingress config, then run helm install n8n n8n/n8n -f values.yaml.

What is queue mode in n8n?

Queue mode runs the main n8n instance and separate worker instances. The main instance handles webhooks and UI; workers execute workflows from a Redis job queue, scaling n8n horizontally across multiple pods.

Do I need Redis for n8n?

Redis is optional for single-node deployments. For queue mode (multiple n8n instances), Redis is required to coordinate job queuing between workers and prevent duplicate execution.

Can I run n8n on Kubernetes without Helm?

Yes. You can write StatefulSet, ConfigMap, Service, and Ingress YAML directly. Helm automates this, reducing boilerplate and making upgrades easier, but it is not required.

What database should I use for n8n?

PostgreSQL 17 or 18 is recommended for production. SQLite works for single-node development but cannot scale to queue mode because it locks on writes. For managed PostgreSQL, use AWS RDS, Google Cloud SQL, or Azure Database.

How do I enable persistence in the n8n Helm chart?

Set persistence.enabled: true and specify a storageClassName that exists in your cluster. Run kubectl get storageclass to list options.

What is the difference between the official and community n8n Helm charts?

The official chart is maintained by n8n and updated with each release. Community charts like 8gears are maintained by volunteers and may lag behind official releases or lack features.

How do I scale n8n workers?

Set workers.replicas: N in values.yaml or use kubectl scale deployment n8n-worker --replicas=N. Workers automatically pull jobs from the Redis queue.

Can I run multiple n8n instances in queue mode?

Yes. Queue mode is designed for multiple instances. One main instance handles webhooks and UI; workers execute workflows. Scale both independently based on load.

The Bottom Line

Helm simplifies n8n deployment on Kubernetes by templating infrastructure as code. You handle PostgreSQL, Redis, Ingress, and storage configuration; the chart handles pod scheduling, networking, and scaling templates. This approach works well for teams with Kubernetes expertise and infrastructure budgets.

If your team is smaller or Kubernetes feels like overhead, Opsily's managed n8n hosting eliminates the complexity and cost of self-managed clusters. Start with the approach that matches your capacity today, and revisit as you scale. Ready to explore managed hosting, check out how to self-host n8n for your specific requirements.

Skip the operational overhead
Opsily manages your n8n infrastructure so your team focuses on building workflows, not maintaining Kubernetes clusters.
Get Started Free

Ready to self-host your own apps?

One server. Multiple apps. No per-app fees.

Get started →