n8n Helm Chart Setup: Kubernetes Deployment Guide
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:
- Helm 3.8+: Download from the Helm project website. Verify with
helm version. - kubectl: Install from the Kubernetes documentation. Test with
kubectl cluster-info. - 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.