Skip to content

docs: include example for separate runner pod in K8s #3799

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: include example for separate runner pod in K8s #3799

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37419f8
docs: include example for separate runner pod in K8s
lindner-tj Oct 24, 2025
ae849a5
fix: remove plain text secret
lindner-tj Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/hosting/configuration/task-runners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,56 @@ path/to/n8n-task-runners.json:/etc/n8n-task-runners.json

For further information about the launcher config file, see [here](https://github.com/n8n-io/task-runner-launcher/blob/main/docs/setup.md#config-file).

## Setting up external task runners in Kubernetes as an additional deployment

While you can configure a task runner to run as a sidecar, it is also possible to have a dedicated task runner pod talk to the broker using a service. In the following example the worker is the sole task broker and a new service is created to expose the broker's port inside the cluster:

```yaml
apiVersion: v1
kind: Service
metadata:
name: n8n-task-broker
namespace: n8n-test
spec:
type: ClusterIP
selector:
app.kubernetes.io/instance: n8n-test
app.kubernetes.io/type: worker
ports:
- name: broker
port: 5679
targetPort: 5679
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: n8n-runners
namespace: n8n-test
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: n8n-runners
app.kubernetes.io/instance: n8n-test
template:
metadata:
labels:
app.kubernetes.io/name: n8n-runners
app.kubernetes.io/instance: n8n-test
spec:
containers:
- name: task-runners
image: n8nio/runners:1.112.0
imagePullPolicy: IfNotPresent
env:
- name: N8N_RUNNERS_TASK_BROKER_URI
value: http://n8n-task-broker.n8n-test.svc.cluster.local:5679
- name: N8N_RUNNERS_AUTH_TOKEN
value: "mysecr3t"
Copy link

@cursor cursor bot Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Kubernetes Example Exposes Sensitive Auth Token

The Kubernetes example for external task runners hardcodes the N8N_RUNNERS_AUTH_TOKEN as a plaintext secret. This violates security best practices for handling sensitive data and could lead users to deploy insecure configurations.

Fix in Cursor Fix in Web

- name: N8N_NATIVE_PYTHON_RUNNER
value: "true"
```

## Adding extra dependencies

You can customize the `n8nio/runners` image. To do so, you will find the runners Dockerfile at [this directory](https://github.com/n8n-io/n8n/tree/master/docker/images/runners) in the n8n repository. The manifests referred to below are also found in this directory.
Expand Down