Deploying n8n on Kubernetes with Helm: the production guide

Docker Compose is enough for the vast majority of self-hosted n8n instances: an n8n service, a postgres service, optionally a redis in queue mode, and you're set. Kubernetes comes into play at a different point — when your team already runs a cluster for the rest of its infrastructure, when you need metrics-driven autoscaling, or when internal compliance mandates a standardized GitOps deployment. n8n now publishes an official Helm chart, which changes the picture compared to the ad-hoc setups from a couple of years ago. This guide covers installation, the queue-mode architecture on K8s, persisting the encryption key, ingress, and autoscaling — and, just as importantly, when not to bother with any of it.

The official Helm chart

n8n publishes and maintains an official Helm chart, distributed as an OCI artifact on GitHub Container Registry:

helm install n8n oci://ghcr.io/n8n-io/n8n-helm-chart/n8n \
  --version 1.0.0 \
  -f my-values.yaml

This is a recent development: until now, the community reference for hosting n8n on Kubernetes was the third-party 8gears/n8n-helm-chart, still actively maintained and perfectly viable if you already run it in production. For a new deployment, prefer the official chart: it tracks n8n releases directly and natively covers queue mode, multi-main, webhook processors, and task runners (see our Task Runners guide for exactly what that component isolates).

Standalone vs queue mode: what the chart actually deploys

The chart exposes two deployment modes, picked based on your real volume:

• Standalone: a single n8n instance with SQLite on a persistent volume. No external dependencies, but no horizontal scaling either — relevant only for low-volume internal use or a test environment.
• Queue mode (the default): main pods (UI, API, scheduling), worker pods (actual execution, stateless, horizontally scalable), and, optionally, dedicated webhook processor pods for absorbing incoming traffic under load — exactly the architecture described in our Redis queue mode guide, simply orchestrated by Kubernetes instead of docker compose --scale.

One thing worth planning for: queue mode ships neither PostgreSQL nor Redis. The chart expects you to point database.postgresdb.host at an existing PostgreSQL instance (managed, or deployed separately in the cluster) and queue.bull.redis.host at an external Redis. That's a deliberate choice: bundling stateful databases alongside stateless application workloads in the same chart complicates backing up and upgrading each independently — see our PostgreSQL backup guide for n8n for the same logic applied outside Kubernetes.

The encryption key: the one secret that doesn't forgive mistakes

N8N_ENCRYPTION_KEY encrypts every credential stored in the database — OpenAI API keys, Slack tokens, SMTP passwords. On Kubernetes, this value belongs in a Secret, never in plaintext inside a version-controlled values.yaml:

kubectl create secret generic n8n-encryption-key \
  --from-literal=N8N_ENCRYPTION_KEY="$(openssl rand -hex 32)"

Then reference that secret from values.yaml (extraEnvSecrets or the chart's equivalent, depending on version) rather than the raw value. The critical point — identical to a plain Docker deployment, but easier to lose track of across several Kubernetes environments — is that if this key is lost, every credential encrypted in the database becomes permanently unreadable, with no recovery path. Back up this secret separately from your Kubernetes manifests and your PostgreSQL dump: all three need to survive together. Our guide to securing n8n credentials covers key rotation and management practices beyond the deployment itself.

Persistence, ingress, and webhooks

Enable persistence.enabled on the main pods (temporary binary files, cache), even though most application state lives in PostgreSQL. For public exposure:

• ingress.enabled=true generates a standard Ingress — pair it with cert-manager for automatic TLS, the Kubernetes counterpart to what our HTTPS with Traefik or Caddy guide covers outside a cluster.
• If you enable dedicated webhook processors, route /webhook/* traffic specifically to that service rather than to the main pods, so external triggers (Stripe, Typeform, WhatsApp) never compete with editor load times.

Autoscaling: native HPA and KEDA

The chart exposes HorizontalPodAutoscaler resources for workers and webhook processors, defaulting to CPU utilization — a simple but imperfect signal for anticipating a spike. Thanh-Tung Nguyen and co-authors, in Horizontal Pod Autoscaling in Kubernetes for Elastic Container Orchestration (Sensors, 2020), show that a poorly calibrated CPU threshold produces either sluggish scaling (existing pods saturate before new ones start) or costly oscillation (repeated scale up/down on short spikes) — their measurements recommend tying the threshold to actual job latency rather than raw CPU alone. For n8n specifically, the more relevant signal isn't worker CPU but Redis queue length: that's exactly what the KEDA integration enables, scaling directly on the number of pending jobs instead of an indirect metric. Reserve KEDA for volumes that already justify queue mode itself — below 1,000 executions per day, a fixed workerReplicaCount of 2 or 3 is a one-line setting and avoids the operational overhead of an autoscaler to monitor.

High availability: what's Enterprise, what isn't

Multi-main — several active main pods running simultaneously with automatic anti-affinity — is an Enterprise feature of the chart, requiring a license. On the standard self-hosted edition, only one main pod runs at a time; real resilience instead comes from queue mode itself: workers are stateless and restart without data loss, and a standard Kubernetes Deployment automatically relaunches a crashed main pod, causing a brief interruption rather than data loss. For most teams, this baseline resilience is more than enough; multi-main is only worth it if a few seconds of downtime during a pod restart is genuinely unacceptable for your business.

Why Kubernetes over Docker Compose, concretely

Kubernetes isn't inherently more reliable than Docker Compose: it's a system that automates tasks (restarting, placement, scaling) you'd otherwise handle manually. Brendan Burns and co-authors, in Borg, Omega, and Kubernetes (ACM Queue, 2016), look back on a decade of orchestration systems at Google and note that their value comes precisely from that: offloading operators from repetitive placement and failure-recovery decisions so they can focus on declaring the desired system state instead. For n8n, that only becomes a real win if you're already running several services on Kubernetes elsewhere in your organization — otherwise, the learning and operating cost of a cluster dedicated to a single application outweighs what it buys you. Our real cost of self-hosting n8n comparison and our VPS selection guide remain the right starting point if Kubernetes isn't already a piece of your existing stack.

In short

The official n8n Helm chart cleanly covers queue mode, persistence, ingress, and autoscaling (native HPA or KEDA on the Redis queue), with multi-main high availability reserved for the Enterprise edition. Kubernetes is worth it when your organization already runs it, not as a first choice for hosting a standalone n8n instance — Docker Compose with queue mode covers the vast majority of production needs. Either way, FlowKit pack workflows import identically: the Compliance & Audit Pack (€149), built for teams that keep control of their infrastructure and audit trail, runs just as well on an existing Kubernetes cluster as on a plain VPS.