n8n

Overview

n8n is a workflow automation platform (fair-code, distributed under the Sustainable Use License). This template deploys an n8n instance backed by a highly available PostgreSQL cluster by default. The editor, REST API, and webhook endpoints are served on one public HTTPS endpoint, and the instance owner account is pre-provisioned at install — there is never an unauthenticated setup page.

Architecture

n8n — A single-replica stateful workload serving the editor, REST API, and webhooks on port 5678. Public URLs are derived from the canonical endpoint at start, so webhook URLs work out of the box.
PostgreSQL (HA, default) — The postgres-highly-available template as a subchart: 3× Patroni PostgreSQL, 3× etcd, and a HAProxy leader-routing endpoint n8n connects through.
PostgreSQL (dev/lightweight, optional) — The single-instance postgres template instead, for lighter non-HA deployments.

What Gets Created

Stateful n8n Workload — Single replica serving the editor, API, and webhooks on port 5678.
Database Workloads — HA mode: a stateful Patroni PostgreSQL workload, a stateful etcd workload, and a standard HAProxy leader-routing workload. Single mode: one stateful PostgreSQL workload.
Volume Sets — 10 GiB persistent storage for n8n instance config and binary execution data (/home/node/.n8n), plus the database subchart’s own volume sets.
Secrets — Owner bootstrap credentials (bcrypt-hashed), a start script that derives public URLs at runtime, and the database credentials from the subchart.
Identity & Policy — A least-privilege policy granting the n8n identity reveal on exactly the secrets it uses, including your pre-created encryption-key secret.
Cron Backup Workload (optional) — When database backups are enabled.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

n8n encrypts every credential it stores with a key it reads from an opaque secret that you create before installing. The key is never passed through values.

Generate an encryption key

Generate a long random string, for example:

openssl rand -hex 24

Create an opaque secret

Create an opaque secret in your org with encoding plain whose payload is the generated key. Set its name in encryptionKey.secretName.

Back up the key

Store a copy of the key somewhere safe, outside Control Plane.

Losing the encryption key makes every credential n8n has stored permanently undecryptable, and the key must never change after first boot — n8n fails to start on a key mismatch. Back it up before installing.

For optional database backups, you also need a bucket and access setup for one of the supported providers — see Backing Up. Once your encryption-key secret exists, install the template using your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Choosing a Database Mode

Exactly one of the two database modes must be enabled — the chart enforces this at render and fails the install with a clear message otherwise.

	`postgresHA` (default)	`postgres`
What runs	3× Patroni PostgreSQL, 3× etcd, HAProxy leader endpoint	One single-replica PostgreSQL workload
Database failover	Automatic (Patroni leader election)	None
Footprint	8 replicas across 3 workloads (3× Patroni, 3× etcd, 2× HAProxy)	1 workload
Best for	Production	Development and lightweight installs

Configuration

The default values.yaml for this template:

image: n8nio/n8n:2.29.8

resources:
  cpu: 1000m
  memory: 1Gi
  minCpu: 250m
  minMemory: 512Mi

encryptionKey:
  secretName: my-n8n-encryption-key # name of your pre-created opaque secret (see Prerequisites)

owner: # instance owner, created automatically on first boot
  email: admin@example.com # owner login email
  firstName: Instance
  lastName: Owner
  password: change-me-n8n-owner # change before installing

timezone: UTC # IANA timezone for Schedule triggers and $now

volumeset:
  capacity: 10 # GiB (minimum 10) — instance config and binary execution data

publicAccess:
  enabled: true # editor + webhooks on the canonical *.cpln.app HTTPS endpoint

internalAccess: # internal firewall scope (in-GVC webhook callers)
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME

postgresHA: # default: highly available PostgreSQL
  enabled: true
  postgres:
    username: n8n
    password: change-me-n8n-db-password # change before installing
    database: n8n
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)
  backup:
    enabled: false # optional — see Backing Up
    mode: logical # logical or wal-g
    resources:
      cpu: 100m
      memory: 128Mi
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      schedule: "0 2 * * *"
    walg:
      intervalSeconds: 21600
    provider: aws # options: aws, gcp, minio
    aws:
      bucket: n8n-pg-backup-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: n8n-pg-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: n8n-pg-backup-bucket
      cloudAccountName: my-gcs-cloud-account
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: n8n-pg-backup-bucket
      accessKey: my-minio-username
      secretKey: my-minio-password
      prefix: postgres/backups

postgres: # dev/lightweight: single-instance PostgreSQL (disable postgresHA first)
  enabled: false
  config:
    username: n8n
    password: change-me-n8n-db-password # change before installing
    database: n8n
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  backup:
    enabled: false # optional — see Backing Up
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    schedule: "0 2 * * *"
    resources:
      cpu: 100m
      memory: 128Mi
    provider: aws # options: aws, gcp, minio
    aws:
      bucket: n8n-pg-backup-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: n8n-pg-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: n8n-pg-backup-bucket
      cloudAccountName: my-gcs-cloud-account
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: n8n-pg-backup-bucket
      accessKey: my-minio-username
      secretKey: my-minio-password
      prefix: postgres/backups

n8n Instance

image — The n8n container image.
resources — CPU and memory for the n8n container.
encryptionKey.secretName — Name of your pre-created opaque secret holding the credential-encryption key. See Prerequisites.
owner.* — The instance owner account, created automatically on first boot. Because the owner is managed through the environment, there is no unauthenticated setup page at any point. Change owner.password before installing. To rotate it later, change the value and run a Helm upgrade — the new password takes effect on the restart.
timezone — IANA timezone applied to Schedule triggers and $now expressions (e.g. America/Chicago).
volumeset.capacity — Volume size in GiB (minimum 10) for instance config and binary execution data.

Access

publicAccess.enabled — Serve the editor, API, and webhooks on the canonical *.cpln.app HTTPS endpoint. Set to false for an internal-only instance (external requests are blocked at the edge; in-GVC callers still reach it per internalAccess).
internalAccess.type — Internal firewall scope of the n8n workload:

Type	Description
`none`	No internal access.
`same-gvc`	Allow access from all workloads in the same GVC (default).
`same-org`	Allow access from all workloads in the same organization.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`.

Database

Enable exactly one of postgresHA (production, default) or postgres (dev/lightweight) — see Choosing a Database Mode. In both modes, change the database password before installing (postgresHA.postgres.password / postgres.config.password). n8n is wired to the active database automatically — the HAProxy leader endpoint in HA mode, or the single instance directly in dev mode.

Connecting

What	Value
Editor / API (public)	`https://<canonical>.cpln.app` — `status.canonicalEndpoint` of `{release}-n8n`
Production webhooks	`https://<canonical>.cpln.app/webhook/<path>`
Test webhooks	`https://<canonical>.cpln.app/webhook-test/<path>`
Internal (same GVC)	`http://{release}-n8n.{gvc}.cpln.local:5678`
Login	`owner.email` / `owner.password`
PostgreSQL (internal, HA mode)	`{release}-postgres-ha-proxy.{gvc}.cpln.local:5432`, credentials in the `{release}-postgres-config` secret
PostgreSQL (internal, single mode)	`{release}-postgres.{gvc}.cpln.local:5432`, credentials in the `{release}-pg-config` secret

Webhooks

Webhook URLs are derived from the canonical endpoint at startup, so the URLs shown in the editor are the ones external callers use — no extra configuration needed.

Synchronous webhook responses must finish within 30 seconds — the platform edge times out longer responses with a 504, although the workflow itself still runs to completion. For long-running workflows, set the Webhook node to respond immediately (or add a Respond to Webhook node early) so the caller gets its response right away while the workflow keeps running.

Backing Up

Database backups are optional and disabled by default. Enable them with postgresHA.backup.enabled or postgres.backup.enabled (matching your database mode), and complete the storage setup for your provider before installing. The values below are shown under backup.* — set them within the enabled database block.

AWS S3
Google Cloud Storage
S3-compatible (MinIO, R2, Wasabi)

Create a bucket

Create an S3 bucket. Set backup.aws.bucket and backup.aws.region to match.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your AWS account. Set backup.aws.cloudAccountName to its name.

Create a bucket-scoped IAM policy

Create an AWS IAM policy with the JSON below (replace YOUR_BUCKET), then set backup.aws.policyName to the policy’s name:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "s3:ListBucket",
      "s3:GetBucketLocation",
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject",
      "s3:AbortMultipartUpload"
    ],
    "Resource": [
      "arn:aws:s3:::YOUR_BUCKET",
      "arn:aws:s3:::YOUR_BUCKET/*"
    ]
  }]
}

Create a bucket

Create a GCS bucket. Set backup.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your GCP project. Set backup.gcp.cloudAccountName to its name — the backup identity is granted access to the bucket keylessly (no stored credentials).

Create a bucket

Create your bucket on the server. Set backup.minio.bucket to its name.

Set the endpoint

Set backup.minio.endpoint to the S3 API address including port. For the minio marketplace template deployed in the same GVC, this is http://WORKLOAD_NAME:9000.

Set credentials

Set backup.minio.accessKey and backup.minio.secretKey to credentials with access to the bucket.

In HA mode, backup.mode selects logical (scheduled pg_dump via a cron workload) or wal-g (continuous WAL archiving). The single-instance mode takes scheduled logical dumps.

Important Notes

Back up the encryption-key secret — losing it permanently bricks every credential n8n has stored; never change it after first boot (n8n fails to start on a key mismatch).
Change owner.password and the database password (postgresHA.postgres.password / postgres.config.password) before installing.
The n8n main instance is single-replica by upstream design — the default HA PostgreSQL backend removes the database as a failure point.
Upgrades restart the single replica — expect roughly a minute of editor/webhook downtime per Helm upgrade.
Synchronous webhook responses must finish within 30 seconds — see Webhooks.
Uninstall deletes the database and n8n volume sets — all workflows, credentials, and execution data. Enable backups if the data matters.
n8n is fair-code under the Sustainable Use License — free to self-host, but not OSI open source.

External References

n8n Documentation

Official n8n documentation

Environment Variables

n8n deployment environment variables reference

Webhook Endpoints

Webhook and endpoint configuration reference

User Management

Owner account and user management guide

Sustainable Use License

The fair-code license n8n is distributed under

n8n Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

Architecture

What Gets Created

Prerequisites

UI

CLI

Terraform

Pulumi

Choosing a Database Mode

Configuration

n8n Instance

Access

Database

Connecting

Webhooks

Backing Up

Important Notes

External References

n8n Documentation

Environment Variables

Webhook Endpoints

User Management

Sustainable Use License

n8n Template

​Overview

​Architecture

​What Gets Created

​Prerequisites

UI

CLI

Terraform

Pulumi

​Choosing a Database Mode

​Configuration

​n8n Instance

​Access

​Database

​Connecting

​Webhooks

​Backing Up

​Important Notes

​External References

n8n Documentation

Environment Variables

Webhook Endpoints

User Management

Sustainable Use License

n8n Template

Overview

Architecture

What Gets Created

Prerequisites

Choosing a Database Mode

Configuration

n8n Instance

Access

Database

Connecting

Webhooks

Backing Up

Important Notes

External References