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 all commits
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
53 changes: 53 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,59 @@

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

Check warning on line 117 in docs/hosting/configuration/task-runners.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[from-write-good.TooWordy] 'additional' is too wordy.

Raw Output:
{"message": "[from-write-good.TooWordy] 'additional' is too wordy.", "location": {"path": "docs/hosting/configuration/task-runners.md", "range": {"start": {"line": 117, "column": 57}}}, "severity": "WARNING"}

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:

Check warning on line 119 in docs/hosting/configuration/task-runners.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[from-write-good.Passive] 'is created' may be passive voice. Use active voice if you can.

Raw Output:
{"message": "[from-write-good.Passive] 'is created' may be passive voice. Use active voice if you can.", "location": {"path": "docs/hosting/configuration/task-runners.md", "range": {"start": {"line": 119, "column": 230}}}, "severity": "WARNING"}

Check failure on line 119 in docs/hosting/configuration/task-runners.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[from-microsoft.Contractions] Use 'it's' instead of 'it is'.

Raw Output:
{"message": "[from-microsoft.Contractions] Use 'it's' instead of 'it is'.", "location": {"path": "docs/hosting/configuration/task-runners.md", "range": {"start": {"line": 119, "column": 60}}}, "severity": "ERROR"}

Check warning on line 119 in docs/hosting/configuration/task-runners.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[from-write-good.TooWordy] 'it is' is too wordy.

Raw Output:
{"message": "[from-write-good.TooWordy] 'it is' is too wordy.", "location": {"path": "docs/hosting/configuration/task-runners.md", "range": {"start": {"line": 119, "column": 60}}}, "severity": "WARNING"}

```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
valueFrom:
secretKeyRef:
name: n8n-test-auth-token
key: auth-token
- 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
Loading