Tech vortex

How to Deploy or Run n8n on Kubernetes

Introduction

Automation is a game-changer in today’s digital landscape. It saves time, reduces errors, and frees up teams to focus on what truly matters. One popular open-source tool making automation accessible is n8n. Pronounced “n-eight-n,” n8n is a powerful workflow automation platform that lets you connect your favorite apps, APIs, and services into seamless automated processes.

What makes n8n stand out is its open-source nature and self-hosting ability. Unlike cloud-only services, you control your data, customize workflows to your exact needs, and avoid vendor lock-in. This flexibility is essential for developers and businesses with complex automation requirements or stringent security policies.

Deploying n8n on Kubernetes — the industry-leading container orchestration platform — elevates your setup by enabling:

  • Scalability: Easily handle growing loads by adding or removing instances.
  • Reliability: Keep your workflows running even if some parts fail.
  • Orchestration: Automate deployment, updates, and recovery.

In this comprehensive guide, we’ll cover everything you need to deploy n8n on Kubernetes: from setting up your cluster, containerizing n8n, configuring storage and secrets, to scaling and monitoring. Whether you’re experimenting locally or building a production system, this walkthrough will give you practical insights to succeed.

Prerequisites

Before jumping into Kubernetes manifests and Helm charts, it’s important to have the right tools and background. Here’s what you need:

Kubernetes Cluster

You’ll need access to a Kubernetes cluster. For local testing, tools like Minikube or kind (Kubernetes in Docker) let you spin up a single-node cluster on your laptop. This is great for experimentation.

For production or serious testing, use managed services like:

  • Google Kubernetes Engine (GKE)
  • Amazon Elastic Kubernetes Service (EKS)
  • Azure Kubernetes Service (AKS)

These services handle cluster management, updates, and scaling for you, so you can focus on your applications.

kubectl

This is the command-line tool to interact with Kubernetes clusters. Ensure it’s installed and configured to talk to your cluster.

Bash
kubectl version --client
kubectl get nodes

The above commands verify your setup.

Helm (Optional but Recommended)

Helm is the package manager for Kubernetes. It lets you deploy complex applications with a single command by using charts — predefined Kubernetes configurations that can be customized.

Helm makes it easier to manage versions, upgrade your deployment, and customize parameters through values.yaml files.

Install Helm following the instructions at https://helm.sh/docs/intro/install/

Docker Knowledge

You don’t need to be a Docker expert, but understanding how container images work will help if you want to customize n8n’s Docker image or troubleshoot deployment issues.

Kubernetes Basics

Familiarize yourself with key concepts:

  • Pods: The smallest deployable units, which host containers.
  • Deployments: Manage pods and ensure the desired number are running.
  • Services: Expose pods internally or externally.
  • Volumes and PVCs: Persistent storage for data.
  • Secrets and ConfigMaps: Configuration and sensitive data management.

If you’re new, Kubernetes official docs (https://kubernetes.io/docs/
tutorials/) provide great beginner tutorials.

Containerizing n8n (Optional)

n8n maintains an official Docker image hosted on Docker Hub: n8nio/n8n. This image is well-maintained and updated regularly.

Using the Official Image

For most users, simply referencing this image in your Kubernetes manifests is enough.

YAML
containers:
  - name: n8n
    image: n8nio/n8n:latest

This saves time and ensures you get the latest stable release with security patches.

When to Customize the Image?

You might want to build your own image if:

  • You want to preload specific workflows so they’re available on startup.
  • You need to include custom credentials or environment variables baked into the image.
  • You plan to add extra tools or plugins alongside n8n, such as specific node packages.
  • You want to optimize startup time or size for your environment.

Building a Custom Image

A simple Dockerfile extending the official image might look like:

Dockerfile
FROM n8nio/n8n:latest

# Copy preconfigured workflows into the container
COPY workflows /home/node/.n8n/workflows

# Optionally install extra npm packages
RUN npm install some-custom-node

After building:

Bash
docker build -t yourregistry/n8n-custom:latest .
docker push yourregistry/n8n-custom:latest

Your Kubernetes manifests would then reference yourregistry/n8n-custom:latest.

Creating Kubernetes Manifests

Deployment.yaml

This is where you define the n8n pods.

Example snippet:

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: n8n-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: n8n
  template:
    metadata:
      labels:
        app: n8n
    spec:
      containers:
        - name: n8n
          image: n8nio/n8n:latest
          ports:
            - containerPort: 5678
          env:
            - name: DB_TYPE
              value: "postgresdb"
            - name: DB_POSTGRESDB_HOST
              valueFrom:
                secretKeyRef:
                  name: n8n-db-secret
                  key: host
            - name: DB_POSTGRESDB_DATABASE
              valueFrom:
                secretKeyRef:
                  name: n8n-db-secret
                  key: database
            - name: DB_POSTGRESDB_USER
              valueFrom:
                secretKeyRef:
                  name: n8n-db-secret
                  key: username
            - name: DB_POSTGRESDB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: n8n-db-secret
                  key: password
            - name: N8N_ENCRYPTION_KEY
              valueFrom:
                secretKeyRef:
                  name: n8n-encryption-key
                  key: key
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"
            limits:
              memory: "1Gi"
              cpu: "500m"

Key considerations:

  • Use environment variables to configure database connection and security keys.
  • Set resource requests and limits to ensure Kubernetes schedules pods properly.
  • Use Secrets to avoid exposing sensitive data.

Service.yaml

Expose your Deployment via a Service.

Example:

YAML
apiVersion: v1
kind: Service
metadata:
  name: n8n-service
spec:
  selector:
    app: n8n
  ports:
    - protocol: TCP
      port: 80
      targetPort: 5678
  type: LoadBalancer

Here, Kubernetes will provision a LoadBalancer (cloud-provider dependent) to expose n8n externally on port 80.

Ingress.yaml (Optional)

If you want to use domain names and HTTPS, an Ingress controller is ideal.

Example:

YAML
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: n8n-ingress
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  tls:
    - hosts:
        - n8n.example.com
      secretName: n8n-tls
  rules:
    - host: n8n.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: n8n-service
                port:
                  number: 80

The ingress routes traffic to your service and handles SSL termination with cert-manager issuing Let’s Encrypt certificates.

Using Helm to Simplify Deployment (Optional)

Helm charts are fantastic for managing complex deployments. The n8n community maintains a Helm chart you can use:

Bash
helm repo add n8n https://n8n-io.github.io/n8n-helm-chart/
helm repo update
helm install my-n8n n8n/n8n

Customizing Values

Create a values.yaml file to customize environment variables, replicas, persistence, and ingress:

YAML
replicaCount: 2

env:
  N8N_BASIC_AUTH_ACTIVE: "true"
  N8N_BASIC_AUTH_USER: "admin"
  N8N_BASIC_AUTH_PASSWORD: "supersecret"
  DB_TYPE: "postgresdb"
  DB_POSTGRESDB_HOST: "my-postgres"
  DB_POSTGRESDB_DATABASE: "n8n"
  DB_POSTGRESDB_USER: "n8nuser"
  DB_POSTGRESDB_PASSWORD: "mypassword"
  N8N_ENCRYPTION_KEY: "myencryptionkey"

persistence:
  enabled: true
  size: 5Gi

ingress:
  enabled: true
  hosts:
    - n8n.example.com
  tls:
    - secretName: n8n-tls
      hosts:
        - n8n.example.com

Deploy or upgrade with:

Bash
helm upgrade --install my-n8n n8n/n8n -f values.yaml

Helm charts handle complex template generation, so you avoid writing all the YAML by hand.

Configuring Persistence

By default, if you restart or update your n8n pod, any unsaved workflow data is lost because the container’s filesystem is ephemeral.

Persistent Volumes and PVCs

A Persistent Volume Claim (PVC) lets you allocate storage that survives pod restarts.

Example PVC:

YAML
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: n8n-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi

Mount it inside the pod:

YAML
volumeMounts:
  - name: n8n-storage
    mountPath: /home/node/.n8n
volumes:
  - name: n8n-storage
    persistentVolumeClaim:
      claimName: n8n-pvc

This ensures your workflows, credentials, and executions are saved persistently.

External Databases

n8n supports various databases, but PostgreSQL is recommended for production.

You can:

  • Run PostgreSQL inside your Kubernetes cluster.
  • Use a managed PostgreSQL service (AWS RDS, GCP Cloud SQL, Azure Database).

Ensure your connection string is secure and referenced via Kubernetes Secrets.

Managing Secrets and Environment Variables

Keeping secrets out of source code and configuration files is critical.

Kubernetes Secrets

Create secrets for:

  • Database credentials.
  • Encryption keys.
  • API tokens.

Example:

Bash
kubectl create secret generic n8n-db-secret \
  --from-literal=host=postgres.example.com \
  --from-literal=database=n8n \
  --from-literal=username=n8nuser \
  --from-literal=password=supersecretpassword

Reference them in your Deployment as environment variables using valueFrom.secretKeyRef.

ConfigMaps for Non-Sensitive Info

For non-sensitive configuration, use ConfigMaps.

Example:

Bash
kubectl create configmap n8n-config --from-literal=WEBHOOK_URL=https://n8n.example.com/

Inject them as environment variables or mount as files.

Enabling Webhook and External Access

Many n8n workflows rely on webhooks to be triggered by external events.

Webhook URLs

Set the environment variable WEBHOOK_URL or WEBHOOK_TUNNEL_URL to the publicly accessible URL where n8n is reachable.

If you don’t configure this properly, webhooks will not work, or they may break after scaling or pod restarts.

SSL/TLS Termination

Secure your web interface and webhooks using HTTPS.

Using Ingress with cert-manager automates certificate issuance with Let’s Encrypt, providing trusted SSL certificates.

Example cert-manager ClusterIssuer for Let’s Encrypt:

YAML
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx

Scaling and High Availability (Advanced)

When running n8n at scale or in mission-critical environments, consider the following:

Horizontal Pod Autoscaler (HPA)

Automatically scale pods based on CPU or memory usage.

Example HPA:

YAML
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: n8n-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: n8n-deployment
  minReplicas: 1
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50

Sticky Sessions and Webhook Consistency

n8n’s webhooks require that the same instance handles incoming webhook requests to maintain session consistency. Use sticky sessions with your load balancer or Ingress controller to route requests from the same client to the same pod.

Database Replication and Backups

Ensure your PostgreSQL database is highly available and backed up regularly.

Use managed database services with built-in replication or configure your own standby replicas.

Regular backups and tested recovery procedures minimize data loss risks.

Monitoring and Logging

Proactive monitoring helps you detect and resolve issues before they impact users.

Metrics with Prometheus and Grafana

Expose n8n metrics and scrape them with Prometheus.

Set up dashboards in Grafana for visualizing:

  • Pod health and availability.
  • CPU, memory usage.
  • Workflow execution stats (success, failure rates).

Centralized Logging

Use Fluentd, Loki, or Elastic Stack to collect and aggregate logs from n8n pods.

Centralized logging allows searching through logs, correlating events, and troubleshooting faster.

CI/CD Automation (Optional)

Automating your n8n deployments ensures consistency and faster iteration.

GitOps with ArgoCD or Flux

  • Store your Kubernetes manifests or Helm charts in Git.
  • Use ArgoCD or Flux to continuously deploy changes to your cluster.
  • Rollbacks are easy — just revert a Git commit.

Version Control Workflows and Infrastructure

Treat your Helm charts and configuration files like code. Version control enables collaboration, audit trails, and traceability.

Conclusion

Deploying n8n on Kubernetes combines the power of flexible, open-source automation with the resilience and scalability of cloud-native orchestration.

You’ve learned how to:

  • Set up your Kubernetes environment and prerequisites.
  • Deploy n8n using manifests or Helm charts.
  • Configure persistent storage and secure secrets.
  • Enable webhooks with secure external access.
  • Scale and monitor your setup for production readiness.
  • Automate deployments for continuous delivery.

With these best practices, you’re equipped to run n8n workflows reliably and efficiently at scale.

Automation is the future — and with Kubernetes and n8n, you’re set to build workflows that drive innovation and success.