infra-n8n/README.md

infra-n8n

A reusable n8n deployment: Postgres, the workload, TLS and an ingress, with every environment value left as a ${VAR} for the caller to substitute.

Nothing here is specific to a deployment. No hostname, no issuer, no Vault path, no image tag. A consumer supplies those through its own Flux Kustomization and its postBuild.substitute block — the same shape used for any templated estate. This repo is the template; it is not itself deployed.

Using it

Create, in the repo that owns the deployment:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata: { name: infra-n8n, namespace: <ns> }
spec:
  interval: 5m
  url: <this repo>
  ref: { branch: main }
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata: { name: n8n, namespace: <ns> }
spec:
  interval: 10m
  sourceRef: { kind: GitRepository, name: infra-n8n }
  path: ./k8s
  prune: true
  wait: true
  postBuild:
    substitute:
      NAMESPACE: <ns>
      # … every variable in the table below

The namespace must exist first, and so must the AppRole Secret the store reads.

Variables

Variable	What it is
NAMESPACE	where everything lands
N8N_HOSTNAME	the public host. It goes into WEBHOOK_URL and the editor's links, so it must be what callers outside the cluster use — an in-cluster name here produces webhooks nothing can call
N8N_IMAGE, POSTGRES_IMAGE	pinned images, tag included
N8N_STORAGE, POSTGRES_STORAGE	claim sizes, e.g. 2Gi, 5Gi
TIMEZONE	e.g. Europe/Paris; drives cron triggers
INGRESS_CLASS, INGRESS_BODY_SIZE	e.g. nginx, "50m"
TLS_ISSUER_NAME, TLS_ISSUER_KIND	a cert-manager issuer, e.g. ClusterIssuer
VAULT_SERVER, VAULT_MOUNT, VAULT_SECRET_PATH	where the two secrets live
VAULT_STORE_NAME, VAULT_APPROLE_SECRET	the ClusterSecretStore this creates, and the AppRole Secret in external-secrets it authenticates with
EXTRA_ENV_SECRET, EXTRA_ENV_SECRET_2	Secrets whose keys become environment variables for workflows. Two slots, because a deployment's environment usually comes from more than one owner. Both optional, so an unused slot needs no placeholder
EXTRA_CA_CONFIGMAP	a ConfigMap with ca.crt, mounted and set as NODE_EXTRA_CA_CERTS, so workflows can call internal TLS endpoints without verification being disabled. Marked optional, so an absent one is not an error
BLOCK_ENV_ACCESS	"true" blocks $env in workflow expressions. n8n's default, and the right one wherever more than one team writes workflows: any workflow can otherwise read any variable in the pod. "false" is how a secret reaches a workflow without being committed in its JSON
EXECUTIONS_MAX_AGE_HOURS	how long executions are kept. n8n keeps them for ever by default, which turns the database into a log

Two secrets, both of which must outlive any pod

Read from VAULT_SECRET_PATH as a whole, so the entry must hold exactly:

• DB_PASSWORD
• N8N_ENCRYPTION_KEY — encrypts the credentials n8n stores in its database. Never regenerate it. A new key does not re-encrypt what is stored; it orphans it. The workflows survive, every credential in them does not.

The AppRole's policy should reach VAULT_SECRET_PATH and nothing else, so a workload here cannot read another deployment's secrets. The commands are in k8s/secrets/clustersecretstore.yaml.

Choices worth knowing

One replica, and strategy: Recreate. n8n separates editor from workers only in queue mode, which needs Redis; without it a second replica is two schedulers racing over the same cron triggers. And the data volume is ReadWriteOnce, so a rolling update deadlocks — the new pod waiting for a volume the old one has not released.

Postgres is a StatefulSet with a volumeClaimTemplate. The claim is not deleted with the workload, so losing the database to a kubectl delete takes more than one mistake.

The certificate is issued, never committed. The private key is generated in the cluster and rotated by cert-manager.

What this repo deliberately does not do

Authentication. n8n's own user management is left at its defaults. A fresh instance is unclaimed: anyone who can reach it can create the owner account. Claim it immediately, and put it behind an identity-aware proxy or n8n's SSO before it holds anything that matters.

Backups. The Postgres claim survives a delete of the workload; it does not survive the cluster.