n8n

Overview

n8n is a workflow automation platform (fair-code, distributed under n8n’s Sustainable Use License). This template deploys a single n8n instance serving the editor, REST API, and webhooks on one HTTPS endpoint, backed by a bundled PostgreSQL database — the postgres-highly-available template by default, or the single-instance postgres template for lighter installs. The instance owner account is pre-provisioned from a secret at install, so there is never an unauthenticated setup page. The owner login, the credential-encryption key and the database credentials come from secrets you create before installing; none passes through Helm values.

This template does not create a GVC. It deploys into an existing GVC that you already have.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-n8n`	n8n editor, API, and webhooks (stateful, 1 replica, port `5678`)	—
Volume set	`RELEASE_NAME-n8n-vs`	`/home/node/.n8n` — instance config and binary execution data	—
Secret	`RELEASE_NAME-n8n-start`	Start script that derives the public URLs from the canonical endpoint	—
Identity	`RELEASE_NAME-n8n-identity`	Workload identity	—
Policy	`RELEASE_NAME-n8n-policy`	`reveal` on exactly the four secrets n8n reads, including your three prerequisite secrets	—
Workload	`RELEASE_NAME-postgres-ha`	Patroni PostgreSQL cluster (stateful, 3 replicas)	`postgresHA.enabled: true` (default)
Workload	`RELEASE_NAME-etcd`	etcd for Patroni leader election (stateful, 3 replicas)	`postgresHA.enabled: true` (default)
Workload	`RELEASE_NAME-postgres-ha-proxy`	HAProxy leader endpoint n8n connects through (standard)	`postgresHA.enabled: true` (default)
Volume sets	`RELEASE_NAME-postgres-ha-vs`, `RELEASE_NAME-etcd-vs`	PostgreSQL and etcd data	`postgresHA.enabled: true` (default)
Workload	`RELEASE_NAME-postgres-ha-backup`	Scheduled logical backup (cron)	`postgresHA.backup.enabled: true` with `mode: logical`
Workload	`RELEASE_NAME-postgres`	Single-instance PostgreSQL (stateful)	`postgres.enabled: true`
Volume set	`RELEASE_NAME-pg-vs`	Single-instance PostgreSQL data	`postgres.enabled: true`
Workload	`RELEASE_NAME-postgres-backup`	Scheduled logical backup (cron)	`postgres.backup.enabled: true`

The highly available database also creates its own identities, policies, and start-script secrets (RELEASE_NAME-postgres-ha-*, RELEASE_NAME-etcd-*, RELEASE_NAME-patroni-startup, RELEASE_NAME-wal-g-backup-script); the single-instance database creates RELEASE_NAME-pg-identity and RELEASE_NAME-pg-policy.

Prerequisites

Three secrets must exist before you install. Secrets are org-level, so no GVC flag is involved.

Create the encryption key secret

An opaque secret with encoding plain whose payload is a long random key. n8n encrypts every credential it stores with it:

printf '%s' "$(openssl rand -hex 24)" | cpln secret create-opaque --name ENCRYPTION_KEY_SECRET_NAME --encoding plain -f -

Set encryptionKey.secretName to this name. Back the key up outside Control Plane before installing — it can never be rotated. Everything n8n encrypts is bound to it: a changed key makes every stored credential undecryptable and n8n refuses to start on a key mismatch. Read it back any time with:

cpln secret reveal ENCRYPTION_KEY_SECRET_NAME -o yaml

Hash the owner password

n8n accepts only a bcrypt hash for the owner password, never plaintext, so hash it first. htpasswd -B emits the $2y$ form, which n8n accepts:

OWNER_HASH=$(htpasswd -bnBC 10 "" 'YOUR-OWNER-PASSWORD' | tr -d ':\n')

Create the owner secret

A dictionary secret holding exactly the keys email and passwordHash:

cpln secret create-dictionary --name OWNER_SECRET_NAME \
  --entry email=admin@example.com \
  --entry passwordHash="$OWNER_HASH"

Set owner.secretName to this name.

Key	What it is
`email`	The instance owner’s login email.
`passwordHash`	A bcrypt hash of the owner password.

Create the database credentials secret

A dictionary secret with the keys username, password and database. The bundled PostgreSQL initializes with it and n8n connects with it:

cpln secret create-dictionary --name DB_CREDENTIALS_SECRET_NAME \
  --entry username=n8n \
  --entry password="$(openssl rand -hex 24)" \
  --entry database=n8n

Set the credentialsSecretName of the database mode you use to this name — postgresHA.config.credentialsSecretName (default, HA) or postgres.config.credentialsSecretName (single-instance). PostgreSQL applies it only when its data directory is first initialized, so editing the secret later does not change the database password — see Rotating the Database Password. Secret names are org-wide, so give each n8n release its own.

The owner secret is the login, at every restart. n8n re-applies the owner from this secret on every start (N8N_INSTANCE_OWNER_MANAGED_BY_ENV), so whatever hash it holds becomes the password the moment the workload restarts — it is not a one-time bootstrap. The account cannot be changed from inside n8n; to change the password, change the secret (see Rotating the Owner Password).

A missing prerequisite secret wedges the deployment silently. cpln helm install still succeeds, the resources are created, and the n8n workload never starts. cpln logs returns nothing at all, because the container never ran. The only place the reason appears is status.versions[].message, which names the missing secret:

cpln workload get-deployments RELEASE_NAME-n8n --gvc GVC_NAME -o yaml

Note this is get-deployments — plain cpln workload get has no versions key. Create the missing secret and the deployment recovers on its own, or force a redeployment to skip the wait:

cpln workload force-redeployment RELEASE_NAME-n8n --gvc GVC_NAME

Optional database backups need a bucket and access setup for one provider, and backups to MinIO need one more dictionary secret — see Backing Up.

Installation

Once all three secrets exist, install from the marketplace registry with the three secret names:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/n8n \
  --version 1.5.0 --gvc GVC_NAME \
  --set encryptionKey.secretName=ENCRYPTION_KEY_SECRET_NAME \
  --set owner.secretName=OWNER_SECRET_NAME \
  --set postgresHA.config.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME

In single-instance mode set postgres.config.credentialsSecretName instead. Or follow the instructions for 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

Configuration

n8n Instance

image: n8nio/n8n:2.45.4   # versions before 2.45.4 are refused (Critical CVEs)

resources:
  minCpu: 250m
  minMemory: 512Mi
  maxCpu: 1000m
  maxMemory: 1Gi

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

owner:
  secretName: my-n8n-owner # name of your pre-created dictionary secret (email + passwordHash)
  firstName: Instance
  lastName: Owner

timezone: UTC # IANA timezone for Schedule triggers and $now (GENERIC_TIMEZONE)

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

owner.firstName and owner.lastName are the owner’s display name and stay ordinary values; only the email and password hash live in the secret. The n8n image runs as a non-root user, and the chart makes the volume writable for it on first boot — nothing for you to do.

Access

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
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

`internalAccess.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 org.
`workload-list`	Allow access only from the workloads listed in `internalAccess.workloads`.

With publicAccess.enabled: false, the editor and webhooks are reachable only from inside the GVC (per internalAccess) or through a port-forward — see Connecting.

Database

Exactly one of the two database modes must be enabled; the chart refuses to render otherwise. The database credentials come from the prerequisite secret named by the enabled mode’s credentialsSecretName (see Prerequisites).

	`postgresHA` (default)	`postgres`
What runs	3 Patroni PostgreSQL replicas, 3 etcd replicas, an HAProxy leader endpoint	One single-replica PostgreSQL workload
Database failover	Automatic	None
Best for	Production	Development and lightweight installs

postgresHA: # set postgresHA.enabled: false and postgres.enabled: true for a lighter single-instance database
  enabled: true
  config:
    credentialsSecretName: my-n8n-db-credentials # PREREQUISITE dictionary secret (username, password, database) — must exist BEFORE install
  replicas: 3
  image: controlplanecorporation/patroni-postgres:0.8 # pgvector 0.8.7 (CVE-2026-103484); tags 0.1-0.7 are refused
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)

postgres:
  enabled: false
  config:
    credentialsSecretName: my-n8n-db-credentials # PREREQUISITE dictionary secret (username, password, database) — must exist BEFORE install
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

Secret names are org-wide, so if you run more than one n8n release in the same org, give each its own database credentials secret; two releases pointed at one secret share a password.

Database Backups

Backups are provided by the bundled database and are off by default. Set the block that matches your database mode and complete the storage setup first — see Backing Up.

postgresHA:
  backup: # optional database backups — see Backing Up
    enabled: false
    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
      credentialsSecretName: my-n8n-minio-credentials # REQUIRED prerequisite dictionary secret (accessKey + secretKey) when provider is minio
      prefix: postgres/backups

postgres:
  backup: # optional database backups (Postgres 17+) — see Backing Up
    enabled: false
    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
      credentialsSecretName: my-n8n-minio-credentials # REQUIRED prerequisite dictionary secret (accessKey + secretKey) when provider is minio
      prefix: postgres/backups

Connecting

The editor, REST API, and webhooks are all served on the n8n workload’s canonical endpoint, which is public by default (publicAccess.enabled: true). Read it from status.canonicalEndpoint:

cpln workload get RELEASE_NAME-n8n --gvc GVC_NAME -o yaml

What	Address	Notes
Editor and REST API	`https://CANONICAL_ENDPOINT`	`status.canonicalEndpoint` of `RELEASE_NAME-n8n`
Production webhooks	`https://CANONICAL_ENDPOINT/webhook/PATH`	The URL shown in the Webhook node
Test webhooks	`https://CANONICAL_ENDPOINT/webhook-test/PATH`	Active only while listening in the editor
Internal (same GVC)	`http://RELEASE_NAME-n8n.GVC_NAME.cpln.local:5678`	Subject to `internalAccess`
Login	`email` and the password behind `passwordHash` in your owner secret	`cpln secret reveal OWNER_SECRET_NAME -o yaml` shows the hash, not the password
PostgreSQL (HA mode)	`RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local:5432`	Credentials from your `postgresHA.config.credentialsSecretName` secret
PostgreSQL (single mode)	`RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432`	Credentials from your `postgres.config.credentialsSecretName` secret

Verify the instance is serving before you sign in:

curl -s https://CANONICAL_ENDPOINT/healthz

Webhook URLs match the public address automatically. The canonical hostname is only known once the workload runs, so the chart boots n8n through a start script that reads CPLN_GLOBAL_ENDPOINT and sets N8N_HOST, N8N_WEBHOOK_URL, and N8N_EDITOR_BASE_URL to https://CANONICAL_ENDPOINT/. The URLs n8n shows in the editor are therefore the ones external callers use, with no extra configuration. With publicAccess.enabled: false those URLs still point at the canonical endpoint, which external callers cannot reach — in that mode, in-GVC callers use the internal address above, and you reach the editor through a port-forward:

cpln port-forward RELEASE_NAME-n8n 5678:5678 --gvc GVC_NAME

Then open http://localhost:5678. The port-forward path has not been exercised against an n8n install.

Requests to the n8n workload time out after 30 seconds (timeoutSeconds on the workload), so a synchronous webhook response must finish within that window or the caller receives a 504 — 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 while the workflow keeps running.

First Run

There is no setup wizard: the owner account already exists when n8n first starts. Open https://CANONICAL_ENDPOINT and sign in with the email from your owner secret and the password you hashed into passwordHash. The owner’s email and password cannot be changed from inside n8n — the secret is authoritative at every start — so change them through the secret instead (Rotating the Owner Password).

Operations

Backing Up

There are three things worth protecting, and they are protected differently. The encryption key. Without it, a restored database is full of credentials nobody can decrypt. Keep a copy outside Control Plane:

cpln secret reveal ENCRYPTION_KEY_SECRET_NAME -o yaml

The database holds your workflows, stored credentials (encrypted with the key), and execution history. Scheduled backups are provided by the bundled database — enable postgresHA.backup or postgres.backup to match your database mode (see Database Backups) and complete the storage setup for your provider before installing. The bucket, cloud account, and IAM policy steps are the bundled database’s own, documented on its page: postgres-highly-available Backup Prerequisites for HA mode, postgres Backup Prerequisites for single mode. Set the values under the n8n keys shown above (postgresHA.backup.aws.bucket, not backup.aws.bucket). In HA mode, postgresHA.backup.mode selects logical (scheduled pg_dump from a cron workload) or wal-g (continuous WAL archiving from a sidecar). Single mode takes scheduled logical dumps. Backups to MinIO or another S3-compatible endpoint need one more prerequisite — a dictionary secret holding the keys accessKey and secretKey, created before install and named by postgresHA.backup.minio.credentialsSecretName or postgres.backup.minio.credentialsSecretName:

cpln secret create-dictionary --name MINIO_CREDENTIALS_SECRET_NAME \
  --entry accessKey=YOUR_ACCESS_KEY \
  --entry secretKey=YOUR_SECRET_KEY

The n8n volume (RELEASE_NAME-n8n-vs, mounted at /home/node/.n8n) holds instance config and binary execution data. The chart configures a final snapshot when the volume set is deleted, with snapshots retained for 7 days. Take one on demand with:

cpln volumeset snapshot create RELEASE_NAME-n8n-vs --gvc GVC_NAME --snapshot-name NAME

Restoring a Backup

Restoring the database follows the bundled database’s own procedure, run from a client with access to the backup bucket: postgres-highly-available Restoring a Backup in HA mode (connect through RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local so the restore targets the current leader), or postgres Restoring a Backup in single mode (host RELEASE_NAME-postgres.GVC_NAME.cpln.local). The username and password are in your database credentials secret. Two n8n-specific points:

The restored database only yields usable credentials if the instance runs with the same encryption key the backup was taken under. Create the encryption key secret with the saved key before pointing a new install at restored data.
Workflows, credentials, and execution records live in the database; files under /home/node/.n8n (binary execution data) are on the volume set and are not part of a database dump.

These restore paths have not been exercised against an n8n install. Restoring the n8n volume set from a snapshot (cpln volumeset snapshot restore) is likewise unverified for this template — check cpln volumeset snapshot --help and test on a throwaway release before relying on it.

Rotating the Owner Password

Because n8n re-applies the owner from the secret on every start, the owner password is rotated by changing the secret and restarting the workload — not from inside n8n. Hash the new password, apply the whole secret with the new hash, then force a redeployment (a changed secret is only picked up when the replica restarts):

OWNER_HASH=$(htpasswd -bnBC 10 "" 'YOUR-NEW-PASSWORD' | tr -d ':\n')

# owner-secret.yaml
kind: secret
name: OWNER_SECRET_NAME
type: dictionary
data:
  email: admin@example.com
  passwordHash: 'PASTE_OWNER_HASH_HERE'

cpln apply -f owner-secret.yaml
cpln workload force-redeployment RELEASE_NAME-n8n --gvc GVC_NAME

The encryption key has no rotation path: changing ENCRYPTION_KEY_SECRET_NAME’s payload after first boot makes every stored credential undecryptable and n8n refuses to start.

Upgrading From 1.0.x

Version 1.1.0 moved the instance owner out of Helm values. 1.0.0 and 1.0.1 took owner.email and owner.password as values, used exactly as written, guarding a login form that is public by default.

	`1.0.0` / `1.0.1`	`1.1.0` and later
Owner login	`owner.email` and `owner.password` values	`owner.secretName` — a dictionary secret you create with `email` and `passwordHash`
Password format	Plaintext	Bcrypt hash — n8n rejects plaintext
Encryption key	`encryptionKey.secretName` prerequisite secret	Unchanged
`owner.firstName` / `owner.lastName`	Values	Unchanged; still values

This upgrade can change the password you log in with. n8n re-applies the owner from the secret at every start, so the hash you put in the secret becomes the login the moment the workload restarts. Hash the password you are using today, not a new one — unless changing it is what you intend.

A helm upgrade that still carries either removed key is refused at render, before anything is applied, and the error names the replacement:

n8n: owner.password was removed in 1.1.0. Put a BCRYPT HASH of it in the prerequisite dictionary
secret named by owner.secretName (key: passwordHash) — see the README. n8n re-applies the owner
from those values on every start, so hash the password you are using today to keep the same login.

Create the owner secret

Follow Prerequisites, hashing the password you log in with today.

Drop the removed keys from your values

Remove owner.email and owner.password and set owner.secretName. Leave encryptionKey.secretName, owner.firstName, and owner.lastName as they are.

Continue with the later sections

Then apply Upgrading From 1.1.0, Upgrading From 1.2.0 or 1.3.0 and Upgrading From 1.3.1 as they apply to your database mode, and upgrade once.

Upgrading From 1.1.0

Version 1.2.0 changed how the single-instance database (postgres.enabled: true) gets its credentials. postgres.config.username, postgres.config.password, and postgres.config.database were removed; the same three values now live in the database credentials secret under Prerequisites, named by postgres.config.credentialsSecretName. Carrying the old keys fails at render with the bundled database’s own message:

config.username was REMOVED in postgres 3.4.0. Database credentials are no longer values: create a
`dictionary` secret holding the keys `username`, `password` and `database`, and set
config.credentialsSecretName to its name. ... If this chart is BUNDLED inside another template ...
do NOT create a secret yourself — that template creates it for you

Put the three values from postgres.config.* into that secret, keeping them identical to what the running database was initialised with — the message’s advice to create a secret is correct here. postgres.backup.minio.accessKey and secretKey were removed in the same version: backups to MinIO now need the prerequisite dictionary secret described in Backing Up, named by postgres.backup.minio.credentialsSecretName. Installs in HA mode have nothing to change in this step.

Upgrading From 1.2.0 or 1.3.0

Version 1.3.0 moved the highly available database (postgresHA.enabled: true, the default) to the same credentials model, and 1.3.1 completed it for MinIO backups. postgresHA.postgres.username, postgresHA.postgres.password, and postgresHA.postgres.database no longer exist; the HA database now reads the database credentials secret under Prerequisites, named by postgresHA.config.credentialsSecretName. Carrying the old block fails at render:

postgres-highly-available: the `postgres` block was REMOVED in 2.5.0. `postgres.username`,
`postgres.password` and `postgres.database` are now a `dictionary` secret you create, named by
`config.credentialsSecretName`, holding the keys `username`, `password` and `database`.

Use the credentials your cluster already has. They were applied when the database was first initialised and are what PostgreSQL still enforces. Putting new values in the credentials secret does not change the running database — it gives n8n a password that no longer works.

Move the credentials

Delete postgresHA.postgres.* from your values and put the same three values into the database credentials secret as the keys username, password and database.

Name the secret

Set postgresHA.config.credentialsSecretName to the secret’s name. Secret names are org-wide, so give each n8n release in the org its own.

MinIO backups only

postgresHA.backup.minio.accessKey and secretKey were removed. Create the prerequisite dictionary secret described in Backing Up and set postgresHA.backup.minio.credentialsSecretName to its name. 1.3.0 still listed the two removed keys in its values while the bundled database already refused them, which is why MinIO backups in HA mode need 1.3.1.

Upgrade

Run cpln helm upgrade with the updated values. The single n8n replica restarts, and the first upgrade after an install can also restart the bundled database — expect the editor and webhooks to be briefly unavailable. Workflows, credentials, and execution data are untouched.

If your database password is the shipped default change-me-n8n-db-password, treat it as compromised and change it after the upgrade — see Rotating the Database Password.

Upgrading From 1.3.1

Version 1.4.0 removed postgres.credentials: the database credentials are now a prerequisite secret, the same one the bundled database template requires on its own. Carrying the old key forward fails the render. 1.3.1 created the database secret itself, so this upgrade deletes it. Before upgrading, create a secret under a new name holding the values your database was initialized with — not new ones, or n8n loses its database connection:

cpln secret create-dictionary --name RELEASE_NAME-n8n-db \
  --entry username=n8n --entry password='YOUR_CURRENT_PASSWORD' --entry database=n8n

Then upgrade with the credentialsSecretName of your database mode (postgresHA.config. or postgres.config.) set to that name and postgres.credentials removed. Your current values are in postgres.credentials of the 1.3.1 release, and also in the old secret (cpln secret reveal SECRET_NAME -o yaml, where SECRET_NAME is the credentialsSecretName your release used, my-n8n-db-credentials by default) until the upgrade deletes it. The upgrade restarts the bundled PostgreSQL too (it now reads the new secret), so n8n can briefly lose its database; it reconnects by itself. While access to the new secret propagates, the new version of a workload can wait in get-deployments reporting that it is not allowed to reveal the secret; the previous version keeps serving meanwhile, and it clears by itself.

Upgrading From 1.4.0

n8n moves from 2.29.8 to 2.45.4 and migrates its database on the first start. Rolling back to 1.4.0 is not supported, so back up the database first. The chart refuses any n8nio/n8n tag below 2.45.4, so if your values pin image, set it to n8nio/n8n:2.45.4 or remove it. Schedule Triggers set to “every N seconds/minutes” now run N apart from when the workflow was activated, instead of on clock boundaries. In HA mode the database moves to controlplanecorporation/patroni-postgres:0.8, which carries pgvector 0.8.7. The database members restart and nothing limits that rollout, so expect a brief interruption of writes while the leader changes; n8n itself restarts as on any upgrade, which is the longer interruption, because its single replica stops before the new one serves. Upgrade in a quiet window. If your values set postgresHA.image, set it to the 0.8 tag: tags 0.1 to 0.7 are refused at render. n8n’s own tables do not use the vector extension, but a PGVector Vector Store node pointed at this database creates it. If it exists, run this in that database after the upgrade:

ALTER EXTENSION vector UPDATE;

Rotating the Database Password

A running workload keeps the credential values it started with, and PostgreSQL reads the secret only when its data directory is first initialized, so editing the secret alone does not change the database password. Change one key and keep the others with export, edit, apply:

cpln secret reveal SECRET_NAME -o yaml > secret.yaml
# edit only the key you are rotating in secret.yaml
cpln apply -f secret.yaml
cpln secret reveal SECRET_NAME -o yaml

Single-instance mode: run ALTER ROLE for the secret’s username in the database first, then update the secret, then right away force a redeployment of RELEASE_NAME-n8n. Do not redeploy the database; restarting it only adds downtime.

cpln workload force-redeployment RELEASE_NAME-n8n --gvc GVC_NAME

HA mode (the default) needs its own order. The replication role repl shares the password, and a member that restarts with the old password can be promoted to leader, which splits the cluster. Move the leader to member -0 first, so it restarts last, after every other member already has the new password. pgx runs a command in one member (LOCATION is your GVC’s location, DB_USERNAME the secret’s username):

pgx() { cpln workload exec RELEASE_NAME-postgres-ha --gvc GVC_NAME --location LOCATION \
  --container patroni-postgres --replica "RELEASE_NAME-postgres-ha-$1" -- "${@:2}"; }
# 1. Find the leader ("role": "leader"); the other two must be "streaming" on the same "timeline"
pgx 0 curl -s localhost:8008/cluster
# 2. If the leader is not RELEASE_NAME-postgres-ha-0, move it there (N = current leader), then repeat step 1
pgx 0 curl -s -XPOST -d '{"leader":"RELEASE_NAME-postgres-ha-N","candidate":"RELEASE_NAME-postgres-ha-0"}' localhost:8008/switchover
# 3. Back to back: change BOTH roles on -0, put the same password in the secret (export, edit, apply above), restart the members
pgx 0 psql -h 127.0.0.1 -d postgres -c "ALTER ROLE DB_USERNAME PASSWORD 'NEW_PASSWORD'; ALTER ROLE repl PASSWORD 'NEW_PASSWORD';"
cpln workload force-redeployment RELEASE_NAME-postgres-ha --gvc GVC_NAME
# 4. Once the members are back, confirm one leader and two "streaming" replicas on one timeline (repeat step 1)
# 5. Optional: remove the install-time password Patroni keeps in its cluster config
pgx 0 curl -s -XPATCH -d '{"postgresql":{"authentication":null}}' localhost:8008/config

Then force-redeploy RELEASE_NAME-n8n, which keeps the old password until it restarts. The app cannot open new database connections from the ALTER ROLE until its own redeploy finishes, so rotate in a quiet window. If a member stays starting, or running without streaming, re-copy it from the leader. This copies the whole database, so it costs network traffic in proportion to its size:

pgx N curl -s -XPOST -d '{"force": true}' localhost:8008/reinitialize

Scaling and Availability

n8n runs as a single replica (maxScale: 1) by upstream design for the standard mode this template ships; the knob to grow is resources, not a replica count.
The database is highly available by default — postgresHA.replicas: 3 Patroni replicas with automatic failover behind an HAProxy leader endpoint, so a database node loss does not take n8n down. Set postgresHA.enabled: false and postgres.enabled: true for a single-instance database when availability matters less than footprint.
Every helm upgrade restarts the single n8n replica, so the editor and webhooks are briefly unavailable; the first upgrade after an install can also restart the bundled database.
Volume capacity: grow volumeset.capacity (n8n) or postgresHA.volumeset.capacity / postgres.volumeset.capacity (database) in GiB; the minimum is 10.

Troubleshooting

The n8n workload never starts and cpln logs returns nothing

Cause: a prerequisite secret named in your values does not exist, so the container never ran. Fix: read the message that names the missing secret, then create it:

cpln workload get-deployments RELEASE_NAME-n8n --gvc GVC_NAME -o yaml

The secret OWNER_SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

The deployment recovers on its own once the secret exists, or run cpln workload force-redeployment RELEASE_NAME-n8n --gvc GVC_NAME to skip the wait.

Install refused with enable exactly one database

n8n: enable exactly one database — set either postgresHA.enabled or postgres.enabled to true, not both

Cause: both database modes are enabled, or neither is. Fix: set exactly one of postgresHA.enabled and postgres.enabled to true. The HAProxy endpoint must stay on in HA mode (postgresHA.proxy.enabled is refused when false).

Install refused because a key was REMOVED

Cause: your values still carry a key an earlier version took — owner.email / owner.password (removed in 1.1.0), postgres.config.username / password / database (removed in 1.2.0), postgresHA.postgres.* and *.backup.minio.accessKey / secretKey (removed in 1.3.0 / 1.3.1), or postgres.credentials (removed in 1.4.0). The render fails before anything is applied, and the running release is untouched. Fix: follow the matching section under Operations, starting with Upgrading From 1.0.x.

My password stopped working after an upgrade or restart

Cause: the owner secret holds a different hash than the password you were using. n8n re-applies the owner from the secret on every start, so the secret’s hash is the login. Fix: sign in with the password that matches the hash in the secret, or put the hash of the password you want there and force a redeployment — see Rotating the Owner Password.

n8n fails to start after the encryption key secret changed

Cause: N8N_ENCRYPTION_KEY no longer matches the key the instance was first started with; n8n refuses to start on a mismatch. Fix: put the original key back in the encryption key secret and force a redeployment. If the original key is gone, the stored credentials cannot be recovered — start a fresh install and re-enter them.

Webhook callers receive a 504

Cause: the workflow took longer than 30 seconds to produce its synchronous response (timeoutSeconds on the workload). The workflow still completes. Fix: set the Webhook node to respond immediately or add a Respond to Webhook node early in the workflow.

n8n restarts a few times right after install

Cause: n8n starts before the bundled database is accepting connections and exits until it is; its retry is the database wait. Fix: nothing — it settles on its own once the database is up. Investigate only if cpln workload get-deployments RELEASE_NAME-n8n --gvc GVC_NAME -o yaml never reports ready.

Important Notes

Back up the encryption key secret before installing — it cannot be rotated; losing or changing it makes every stored credential undecryptable and n8n fails to start on a mismatch.
Create all three prerequisite secrets before installing — a missing one wedges the deployment with no log output; cpln workload get-deployments RELEASE_NAME-n8n --gvc GVC_NAME -o yaml is the one command that names it.
The owner secret is the login at every restart — change the password through the secret plus a forced redeployment, never from inside n8n, and when upgrading hash the password you use today.
Editing the database credentials secret does not change the database password — run ALTER ROLE first, then force-redeploy n8n; in HA mode move the leader first (Rotating the Database Password).
Give each n8n release its own database credentials secret — secret names are org-wide, so two releases pointed at one secret share a password.
Synchronous webhook responses must finish within 30 seconds — see Connecting.
Every upgrade restarts the single n8n replica — expect a brief editor and webhook outage; the first upgrade after an install can also restart the bundled database.
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, 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

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

n8n Instance

Access

Database

Database Backups

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Rotating the Owner Password

Upgrading From 1.0.x

Upgrading From 1.1.0

Upgrading From 1.2.0 or 1.3.0

Upgrading From 1.3.1

Upgrading From 1.4.0

Rotating the Database Password

Scaling and Availability

Troubleshooting

Important Notes

External References

n8n Documentation

Environment Variables

Webhook Endpoints

User Management

Sustainable Use License

n8n Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​n8n Instance

​Access

​Database

​Database Backups

​Connecting

​First Run

​Operations

​Backing Up

​Restoring a Backup

​Rotating the Owner Password

​Upgrading From 1.0.x

​Upgrading From 1.1.0

​Upgrading From 1.2.0 or 1.3.0

​Upgrading From 1.3.1

​Upgrading From 1.4.0

​Rotating the Database Password

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

n8n Documentation

Environment Variables

Webhook Endpoints

User Management

Sustainable Use License

n8n Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

n8n Instance

Access

Database

Database Backups

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Rotating the Owner Password

Upgrading From 1.0.x

Upgrading From 1.1.0

Upgrading From 1.2.0 or 1.3.0

Upgrading From 1.3.1

Upgrading From 1.4.0

Rotating the Database Password

Scaling and Availability

Troubleshooting

Important Notes

External References