Deploy and Operate n8n
n8n is a workflow automation platform with a visual editor, native AI nodes, and queue-based execution. Edka deploys the official n8n Helm chart as a managed app in your Kubernetes cluster, runs it in queue mode with separate worker pods from the start, and connects it to the PostgreSQL and Valkey installations you already run.
Architecture
Section titled “Architecture”| Component | Purpose | How Edka connects it |
|---|---|---|
| n8n main pod | Editor UI, REST API, webhook intake, and workflow scheduling | Installed from the official n8n Helm chart via Edka’s app template |
| n8n worker pods | Pull queued jobs from Valkey and execute workflows | Same chart release, replica count set on the Queue tab |
| Task runner sidecars | Run Code node JavaScript and Python outside the worker process | Enabled by default, authenticated with a generated shared token |
| PostgreSQL | Execution history, credentials, and workflow definitions | Select an installation, database, and user from the Databases workspace |
| Valkey | Queue broker between the main pod and workers | Select an existing Valkey installation |
| Envoy Gateway | Optional HTTPS access to the editor and webhooks | Select a traffic class and hostname |
| Metrics Server | Pod CPU and memory metrics for the app view | Installed automatically as n8n’s required add-on |
Prerequisites
Section titled “Prerequisites”Before installing n8n, prepare:
- an Edka cluster with a managed PostgreSQL installation, a dedicated database, and a user that can connect to it
- a managed Valkey installation for n8n’s queue broker
- if you want external access: an Envoy Gateway traffic class with managed TLS and a DNS hostname for the editor and webhooks
n8n always runs in queue mode against an external PostgreSQL and Valkey installation. There is no SQLite or single-instance fallback in the Edka template. See Databases and Gateway API if these are not ready yet.
Install n8n
Section titled “Install n8n”- Open your cluster and select Apps.
- Find n8n and select Install.
- In General, choose the Namespace, set the n8n Chart Version and n8n Image Tag, and decide whether to enable Auto-update Image. Edka generates the Encryption Key.
- In Database, select the PostgreSQL Installation, Database, and User prepared for n8n. Edka resolves the host, port, schema, and SSL settings from that selection.
- In Queue, select the Valkey Installation and set Worker Replicas and Worker Concurrency.
- In Storage, set the home volume size and storage class.
- In Task Runners, keep Enable Task Runners on to run Code node scripts in an isolated sidecar, or turn it off. Edka generates the Task Runner Token.
- Review Resources, Placement, and Access as described below.
- Select Install App and follow the operation progress until n8n is ready.
Leave n8n Image Tag as stable to track the same default the official
chart uses, or pin a specific n8n release tag.
Secrets Handling
Section titled “Secrets Handling”n8n uses two generated secrets, stored in Kubernetes Secrets in the app namespace and preserved automatically on every configuration update.
| Secret | Purpose | Handling |
|---|---|---|
| Encryption Key | Encrypts n8n’s stored credentials (N8N_ENCRYPTION_KEY) | Generated at install in the release’s core Secret; not editable after installation |
| Task Runner Token | Shared authentication token between n8n and task runner sidecars | Generated at install in the release’s runner-token Secret; not editable after installation |
| Database Password | PostgreSQL connection password | Resolved by Edka from the selected user’s password Secret |
| Valkey Password | Valkey connection password, when Valkey authentication is enabled | Resolved by Edka from the selected Valkey installation’s password Secret |
Neither the Encryption Key nor the Task Runner Token can be revealed through
the app configuration form. Edka reads their current value directly from the
runtime Secret only to keep them stable across updates. Recovering either
value for another purpose means reading the Secret in the app namespace with
kubectl.
Queue Mode and Workers
Section titled “Queue Mode and Workers”n8n installs in queue mode. The main pod serves the editor, webhooks, and scheduling; it does not execute workflows itself. Worker pods pull jobs from Valkey and run them.
- Worker Replicas: default
2, range1to20. - Worker Concurrency: default
10, range1to50, the number of jobs each worker processes at once.
Task Runners
Section titled “Task Runners”Enable Task Runners is on by default. Code node JavaScript and Python run
in a separate task runner process from the worker pod, with the native
Python runner enabled. The worker connects to a broker on port 5679, and
idle task runners shut down automatically after 15 seconds. Authentication
between the worker and its task runners uses the generated Task Runner
Token.
Gateway Access
Section titled “Gateway Access”Expose n8n via Gateway is off by default. When enabled, select a
Traffic Class and enter a Hostname for the editor and webhooks. Edka
creates an HTTPRoute on the selected Gateway and sets n8n’s webhook base URL
to https://<hostname>. n8n listens internally on port 5678.
After installation, Edka shows the internal n8n UI endpoint, the PostgreSQL and Valkey endpoints n8n connects to, and, when Gateway access is enabled, the external HTTPS URL.
Storage, Resources, and Placement
Section titled “Storage, Resources, and Placement”| Option | Default | Notes |
|---|---|---|
| n8n Storage | 10Gi, minimum 10Gi | Persistent volume for the n8n home directory |
| n8n Storage Class | hcloud-volumes | Fixed at install time |
| Main pod | 200m/512Mi requested, 1000m/1Gi limited | Editor, API, and scheduling |
| Worker pod, each | 200m/512Mi requested, 1000m/1Gi limited | Multiplied by Worker Replicas |
| Task runner sidecar, each | 100m/256Mi requested, 500m/512Mi limited | Applies only when Task Runners are enabled |
You can also place n8n on a selected node pool and automatically tolerate that pool’s taints.
Metrics
Section titled “Metrics”n8n publishes Prometheus metrics at :5678/metrics. Edka enables
N8N_METRICS and N8N_METRICS_INCLUDE_QUEUE_METRICS, and disables n8n’s
built-in diagnostics and version-check telemetry. When the cluster metrics
backend is available, Edka’s app view can surface:
- waiting and active queue jobs
- p95 workflow execution duration
- total active workflows
- completed and failed queue job rates
- p99 Node.js event loop lag
- Node.js heap memory used
See Cluster Metrics for the metrics backend setup.
Updates
Section titled “Updates”Auto-updates target only the n8n container image tag
(docker.io/n8nio/n8n), not the Helm chart version, which you set manually
with n8n Chart Version. Auto-update Image is off by default. When
enabled, choose an Auto-update Policy of patch, minor, major, all, or a
custom glob or regexp pattern, and an Auto-update Check frequency of 5
minutes, 30 minutes, 1 hour, 6 hours, or daily.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| Namespace is rejected | Namespace must be a valid Kubernetes name |
| Hostname is rejected | Hostname must be a valid domain name |
| External URL endpoint is missing after install | Expose n8n via Gateway was left off; enable it and set a Traffic Class and Hostname |
| n8n main pod stays unready | Verify PostgreSQL and Valkey connectivity: host, port, database or logical database number, and credentials |
| Worker pods process no jobs | Confirm Worker Replicas is at least 1 and workers can reach the selected Valkey installation |
| Metrics are empty | Confirm the cluster metrics backend is installed and scraping the n8n pod on port 5678 at /metrics |