8gears/n8n-helm-chart: A Thin Translation Layer From values.yaml to n8n Environment Variables
A Kubernetes Helm chart for n8n - a workflow automation tool. Easily automate tasks across different services on self hosted onKubernetes
At a glance
- What is it?
- The chart does one thing deliberately: it forwards your YAML keys into n8n environment variables and wraps the result in Kubernetes objects. The design is simple enough to audit, and the parts it does not manage are worth knowing before you install it.
- Who is it for?
- Adopt this chart if you want n8n on Kubernetes with a values.yaml that maps directly onto n8n's documented environment variables, and if you accept that you supply the database, the ingress controller and the encryption key yourself. Do not adopt it if you expect a bundled Postgres, a tested upgrade path across every n8n release, or an operational runbook.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go Template, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap this chart fills between n8n and a Kubernetes cluster
n8n ships as a Node application and documents its behaviour through environment variables. Kubernetes expects manifests. The 8gears chart sits between those two worlds and converts the first into the second. It is aimed at teams who already run workloads on Kubernetes and want n8n to look like every other workload: a Deployment, a Service, an optional Ingress, an optional PersistentVolumeClaim, and a values.yaml checked into a repository. The README frames the scope plainly when it says the chart "just forwards everything down to the n8n pods". That sentence is the whole design. If you want a chart that makes decisions about your database, your backups or your upgrade order, this is not it. If you want a chart that gets out of the way and lets n8n's own documentation remain the source of truth, the fit is closer.
How config and secret keys become environment variables
The mechanism is the most interesting part of the project and the easiest to get wrong. The README states that the YAML nodes config and secret in values.yaml are transformed 1:1 into Kubernetes environment variables. Nesting becomes underscore separation and the top level of the n8n key becomes an N8N_ prefix. The README gives this example: n8n.encryption_key under main.config turns into N8N_ENCRYPTION_KEY, db.type turns into DB_TYPE, and db.postgresdb.host turns into DB_POSTGRESDB_HOST. The same rule applies under main.secret, except the values land in a Secret object rather than a ConfigMap. The README notes there is no restriction on what goes where and that you can mix and match. That freedom is also the sharp edge. Nothing validates your key names. A typo such as db.postgresdb.hostt produces an environment variable that n8n silently ignores, and you discover the mistake when the pod fails to reach the database. The chart is a translator, not a schema. Treat the n8n environment variable documentation as the contract, and diff your rendered ConfigMap against it before you apply anything to a cluster that matters.
Queue mode, workers, webhooks and Redis in the values layout
The values file is organised into sections the README enumerates: global and chart wide values such as image repository and tag, Ingress settings, main n8n application configuration with Kubernetes specific settings, worker settings, webhook settings, raw resources for pass-through manifests such as GatewayAPI or ServiceMonitor, and Redis settings. The presence of separate worker, webhook and Redis sections tells you the chart anticipates n8n's queue mode rather than only single-process deployments. That matters because queue mode is what makes n8n horizontally scalable, and it changes your infrastructure requirements: you need Redis reachable from the worker pods and a Postgres instance that all of them share. The chart provisions the Kubernetes side of that arrangement. It does not provision Redis or Postgres themselves, and the README lists an external Postgres database or embedded SQLite as a requirement rather than something the chart creates. SQLite is bundled with n8n, and the persistence section of the values file decides whether the data survives a pod restart.
Persistence defaults that will lose your data if you ignore them
The persistence block defaults to enabled: false with type: emptyDir. The README describes the alternatives: existing for a pre-existing claim, emptyDir for a scratch volume, and dynamic for dynamic volume provisioning. An emptyDir volume is tied to the pod lifecycle. In a single-replica deployment using SQLite, that means workflow definitions and credentials live in a directory that disappears when the pod is rescheduled. The chart is doing what it was told, and the default is defensible for a throwaway test, but it is not a safe default for anything you care about. The README also documents accessModes defaulting to ReadWriteOnce and notes that PVC annotations are not maintained at Helm v3 anymore, pointing to an open issue. If you need a retention annotation such as helm.sh/resource-policy: keep, the README says to add it under values.yml and the pvc.yml template will apply it, while flagging that this path is not maintained. Two reasonable configurations exist: run stateless with an external Postgres and no PVC at all, or run with persistence.enabled: true and type: dynamic. Choosing neither is how people lose encryption keys.
Installing it and the commands the README actually gives
The chart is distributed as an OCI artifact. The README's install command is helm install my-n8n oci://8gears.container-registry.com/library/n8n --version 1.0.0, and the requirements section asks for Helm 3.8 or newer, with Helmfile listed as optional. Note the mismatch: the install example pins 1.0.0 while the repository's recent releases are tagged 2.1.1, 2.1.0 and 2.0.1. Pin whatever version you have verified exists rather than copying the README literally. A minimal values.yaml from the examples directory sets main.config.n8n.hide_usage_page to true, puts an encryption key under main.secret.n8n.encryption_key, sets memory requests and limits, and exposes the service as NodePort on port 5678. The README warns in capitals that you should provide an encryption key if you run n8n stateless, because n8n uses it to encrypt stored credentials. Losing that key makes existing credentials unreadable. Ingress is disabled by default, with a commented example using className and a host such as workflow.example.com plus a TLS secret name. The chart also supports extraEnv for pulling values from other ConfigMaps and Secrets via valueFrom.secretKeyRef, which is how you avoid pasting database passwords into values.yaml.
Where the chart stops being the right tool
Three limitations are visible in the material. First, the chart does not manage the database. The README requires an external Postgres or embedded SQLite and offers no bundled Postgres subchart, so a team expecting one helm install to produce a complete stack will be disappointed. Second, the maintainer situation is stated openly: the README carries a note that the chart is growing in popularity and that additional conscientious and accurate maintainers are wanted for governance, development, documentation and CI/CD. That is an honest signal about review capacity, and it means you should read the values.yaml and templates for the version you pin rather than assuming every n8n release is covered. Third, the pass-through design means the chart cannot protect you from n8n configuration mistakes. If you set an invalid value or a key that no longer exists upstream, the chart will faithfully render it. The chart is also the wrong tool if you are not on Kubernetes at all. Running n8n with Docker Compose or a single VM is simpler, and adding a cluster to get one automation service is a large amount of operational surface for the benefit.
What a direct Kubernetes deployment costs compared with this chart
The alternative is to write your own manifests or a small internal chart. The difference is not capability, it is maintenance. A hand-written Deployment needs you to author the ConfigMap and Secret plumbing, the worker and webhook Deployments, the Redis wiring, the Service, the Ingress and the PVC yourself. That is perhaps an afternoon of work, and you own every line. The 8gears chart encodes the same objects and keeps the values surface close to n8n's own environment variable names, so the mapping stays legible when n8n adds a setting. The trade is that you inherit someone else's defaults, including the emptyDir persistence default and the README's version pinning drift. A middle path exists: use the chart as a reference for what objects n8n needs, then template only the parts you run. Teams that already have a chart library and strict conventions will likely prefer that route, because the chart's raw resources section exists precisely to let you inject your own manifests alongside it. If your platform already standardises on a different deployment tool, adopting a standalone Helm chart adds a second release mechanism to your cluster for one application.
Licence, upgrade cost and what to check before you commit
The chart is Apache-2.0, which permits commercial use and modification, and it is not archived, with the last push in September 2026 and releases at 2.1.1, 2.1.0 and 2.0.1. The gap between 2.0.1 in December 2025 and 2.1.0 in August 2026 is roughly eight months, which tells you releases follow n8n and contributor availability rather than a fixed cadence. Apache-2.0 covers the chart templates and values, not n8n itself, which is a separate project with its own licence; check that separately if licence compatibility matters to you. This is a description of the licence identifier, not legal advice. Upgrade cost concentrates in two places: the n8n image tag, since the chart's tag field defaults to the chart appVersion and you may override it, and the values schema, which can change between major chart versions. Because config and secret are free-form dictionaries, a chart upgrade that renames a section will not be caught by your editor. Render the templates with helm template against your values before and after a version bump and compare the resulting ConfigMap and Secret keys. If the diff is empty apart from the image tag, the upgrade is mechanical.
Editorial conclusion
Adopt this chart if you want n8n on Kubernetes with a values.yaml that maps directly onto n8n's documented environment variables, and if you accept that you supply the database, the ingress controller and the encryption key yourself. Do not adopt it if you expect a bundled Postgres, a tested upgrade path across every n8n release, or an operational runbook. Before installing, verify three things: that the chart version you pin exists in the OCI registry, that main.config and main.secret produce the environment variables you expect, and that persistence.enabled is set to true with type dynamic or existing if you are not running fully stateless.
Community notes