8gears n8n Helm Chart

n8n supports a queue-mode where workloads are shared between multiple instances using BullMQ and a Redis server. This allows for shared load and improved availability, though the controller instance remains a single point of failure.

To enable queue-mode in this Helm chart, set scaling.enabled to true. By default, the chart is configured to spawn two worker instances.

scaling:
  enabled: true

The examples/ directory provides pre-configured values.yaml files tailored for specific environments. Use these as templates to jumpstart your configuration:

• values_local.yaml: Optimized for running n8n on local Kubernetes clusters like kind or k3s for testing on localhost.
• aws: Configured for running n8n on AWS using EKS and ingress-nginx.
• simple-prod: A simplified production-ready setup targeting AWS.

# Example usage pattern
# helm install n8n open-8gears/n8n -f examples/values_local.yaml

Version 1.0.0 introduced a complete redesign of the chart structure to better accommodate n8n configuration options. When upgrading from versions prior to 1.0.0, note the following breaking changes:

• Restructured Values: Configuration options are now organized under .Values.main, .Values.worker, and .Values.webhook.
• Deployment Updates: Deployment configurations have been updated.
• Redis Requirements: New Redis integration requirements are in place for certain modes.

Install the n8n chart using Helm from the OCI registry. You can specify a version to ensure deployment stability.

Requirements

• Helm >= 3.8
• An external Postgres DB or embedded SQLite (SQLite is bundled with n8n)
• Helmfile (Optional)

helm install my-n8n oci://8gears.container-registry.com/library/n8n --version 1.0.0

If you intend to use the full or small-prod examples which include a database instance, it is recommended to use cloudnative-pg.

You can install the CloudNativePG operator using the following commands to ensure the controller is running before proceeding with the n8n deployment:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.27/releases/cnpg-1.27.1.yaml
kubectl rollout status deployment \
  -n cnpg-system cnpg-controller-manager

The chart includes configuration for the official Valkey Helm Chart. This is used by n8n for scaling (Workers and Webhooks).

Enable it via valkey.enabled: true. Note that the available options are passed through to the Valkey chart.

The chart supports running n8n in worker mode to scale processing. To enable workers, set worker.enabled: true.

Workers have their own configuration block which includes:

• concurrency: The number of jobs a worker can run in parallel (default is 10).
• config and secret: Additional configuration and secrets specific to the worker.
• extraEnv: Extra environment variables for the worker.
• persistence: Independent persistence settings for the worker pods.
• replicaCount: The number of worker pods to run.
• command and commandArgs: Overrides for the worker container's startup command.

worker:
  enabled: true
  replicaCount: 2
  concurrency: 20
  extraEnv:
    MY_VAR: "value"

You can configure how n8n stores data using the persistence section in your values.yaml. This allows you to use Persistent Volume Claims (PVC) instead of ephemeral emptyDir storage.

Key options include:

• enabled: Set to true to use a PVC.
• type: Choose from existing (to use a pre-created Claim), emptyDir (ephemeral), or dynamic (for Dynamic Volume Provisioning).
• accessModes: Typically ReadWriteOnce.
• size: The requested storage capacity (e.g., 1Gi).
• storageClass: The name of the storage class. Setting this to "-" disables dynamic provisioning.

persistence:
  enabled: true
  type: dynamic
  accessModes:
    - ReadWriteOnce
  size: 1Gi
  # storageClass: "gp2"

If you need to deploy additional Kubernetes resources alongside the n8n chart, use extraManifests or extraTemplateManifests.

• extraManifests: Accepts a list of standard Kubernetes manifest objects (YAML). These are merged with default metadata labels.
• extraTemplateManifests: Accepts a list of strings containing YAML. These are processed as templates, allowing you to use variables from the values.yaml file (e.g., {{ .Values.image.repository }}).

extraManifests:
  - apiVersion: v1
    kind: ConfigMap
    metadata:
      name: example-config
    data:
      example.property.1: "value1"

extraTemplateManifests:
  - |
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: my-config
    stringData:
      image_name: {{ .Values.image.repository }}

You can offload webhook processing to a dedicated instance by enabling the webhook component. When webhook.enabled is set to true, webhooks are processed by a separate set of pods rather than the main n8n process.

Note: Webhook processes rely on Valkey/Redis.

Configuration options for the webhook component mirror the main deployment, including persistence, replicaCount, service, and resources. You can also use extraEnv to define the WEBHOOK_URL.

webhook:
  enabled: true
  extraEnv:
    WEBHOOK_URL:
      value: "http://webhook.domain.tld"

You can scale the number of workers and specify which Redis server to use for queue-mode.

• Increase Workers: Set scaling.worker.replicaCount to a higher number.
• External Redis: Provide the hostname and password for your existing Redis instance under scaling.redis.
• Internal Redis: To have the chart spawn its own Redis server, set redis.enable: true. Note that by default, no Redis server is spawned.

scaling:
  enabled: true
  worker:
    replicaCount: 3
  redis:
    host: "redis-hostname"
    password: "redis-password-if-set"
# To use internal redis:
redis:
  enable: true