Back · Hosting

kubernetes

Run n8n at scale on any Kubernetes cluster using the community Helm chart, with main/webhook/worker deployments split for true horizontal scaling in queue mode.

Difficulty
Monthly cost from: Varies — cluster-dependent

Run n8n at scale on any Kubernetes cluster using the community Helm chart, with main/webhook/worker deployments split for true horizontal scaling in queue mode.

Prerequisites

  • A running Kubernetes cluster (EKS, GKE, AKS, or self-managed)
  • Helm 3 installed
  • kubectl access with appropriate RBAC
  • An external Postgres and Redis (or in-cluster operators)
  • An ingress controller (nginx/Traefik) + cert-manager for TLS

Step-by-step guide

  1. Step 1

    Add the community Helm repo

    Add the n8n-io/n8n-helm-chart (or community 8gears chart) repository.

    helm repo add n8n https://8gears.container-registry.com/chartrepo/library
helm repo update

  2. Step 2

    Configure values.yaml

    Set the external Postgres connection, N8N_ENCRYPTION_KEY secret, ingress host, and enable queue mode with worker replica count.

  3. Step 3

    Install the release

    Deploy main, webhook, and worker deployments together.

    helm install n8n n8n/n8n -f values.yaml -n n8n --create-namespace

  4. Step 4

    Verify ingress & TLS

    Confirm cert-manager issued a certificate and the ingress routes to the main n8n service.

Scaling & queue mode

Kubernetes is the best option for real horizontal scale: run separate Deployments for `main` (editor/API), `webhook` (dedicated webhook receivers), and `worker` (queue consumers), each with its own HPA. Point all of them at shared Postgres and Redis.

Backup & upgrade

Use Velero or your cloud provider's volume snapshot mechanism for PVCs, plus scheduled Postgres dumps via a CronJob. Upgrade with `helm upgrade n8n n8n/n8n -f values.yaml` after bumping the chart/image version; use `--atomic` for automatic rollback on failure.

Security checklist

  • Use NetworkPolicies to restrict pod-to-pod traffic
  • Store secrets in a secret manager (Sealed Secrets, External Secrets Operator) rather than plain values.yaml
  • Run containers as non-root with a read-only root filesystem where possible
  • Keep the Helm chart and n8n image versions pinned and reviewed before upgrading

Cost breakdown

  • Managed K8s control plane$0–75/mo (provider-dependent)
  • Worker nodesFrom ~$30/mo per node

Troubleshooting & FAQ

+Can I use SQLite instead of Postgres?

n8n defaults to SQLite, which works for testing but isn't recommended for production: no concurrent writers, harder backups, and risk of corruption under load. Use Postgres for anything real.

+My webhooks return 404 / don't trigger — why?

WEBHOOK_URL must match the public HTTPS URL exactly (including trailing slash), and the workflow must be activated (not just saved) for production webhook URLs to work.

+How do I move from Kubernetes / Helm to another host later?

Export workflows/credentials with the n8n CLI (`n8n export:workflow --all` / `export:credentials --all`) or the REST API, restore the Postgres dump on the new host, then import.

+Do I lose data if the container restarts?

No, as long as n8n_data and the Postgres volume are mounted as named Docker volumes (not ephemeral container storage), your data persists across restarts and image updates.

Official documentation