feat: Add support for custom runner images (n8n v2 support)#289
feat: Add support for custom runner images (n8n v2 support)#289joshuabaird wants to merge 1 commit into8gears:mainfrom
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review infoConfiguration used: Repository UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (5)
🚧 Files skipped from review as they are similar to previous changes (5)
WalkthroughAdds explicit per-worker image configuration and docs to support n8n v2.0+ separate task-runner image, updates worker command/args resolution to avoid overriding runners image entrypoint, and bumps the Helm chart to 2.1.0. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
joshuabaird
force-pushed
the
chore/v2/separate-worker-image
branch
from
f992c86 to
78e33b5
Compare
|
Howdy, would this support sidecars acting as task runners for workers? |
As is, no. That would need to be a separate effort. |
|
Thanks :) this new task runner setup has become a **** show on k8s |
|
@Vad1mo Could you review this? This is needed before a 2.x upgrade. |
|
I am actively testing this today and Monday on our dev clusters and I can report back |
|
This isn't working as it is:
|
| command: | ||
| {{- toYaml .Values.worker.command | nindent 12 }} | ||
| {{- else }} | ||
| command: ["n8n"] |
There was a problem hiding this comment.
This command won't work with the runner image. So either set it in the values or change it here.
| args: | ||
| {{- toYaml .Values.worker.commandArgs | nindent 12 }} | ||
| {{- else }} | ||
| args: |
This PR wasn't meant to solve all things needed for v2 compatibility -- it was only meant to provide the ability to configure custom runner images. I'll take a closer look at the command-related comments, thanks. |
|
@RoseSecurity Just pushed a possible fix for the CMD/ARGS on v2 runners. Can you test and let me know the results, please? |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README.md`:
- Around line 817-851: The migration docs for "n8n v2.0+ Support and Task Runner
Image" are incomplete: update the README section (the "n8n v2.0+ Support and
Task Runner Image" header and the worker image guidance mentioning worker.image
and worker.command/commandArgs) to include a clear "Known limitations" or
"Additional configuration may be required" note that instructs users to (1)
create a Service exposing port 5679 so the runners can reach the task broker,
and (2) configure the environment variables N8N_RUNNERS_TASK_BROKER_URI and
N8N_RUNNERS_BROKER_LISTEN_ADDRESS for Kubernetes deployments (explain that
defaults won’t work), plus a short pointer that these settings are required in
addition to swapping worker.image to n8nio/runners.
| ## n8n v2.0+ Support and Task Runner Image | ||
|
|
||
| Starting with n8n v2.0, the task runner (worker) functionality has been moved to a separate Docker image (`n8nio/runners`). This chart now supports configuring a custom image for workers while maintaining full backwards compatibility with n8n v1.x. | ||
|
|
||
| ### For n8n v1.x Users (Current Default) | ||
|
|
||
| No changes needed! Workers will continue using the main n8n image (`n8nio/n8n`). | ||
|
|
||
| ### For n8n v2.0+ Users | ||
|
|
||
| When upgrading to n8n v2.0 or later, you **must** configure the worker to use the separate task runner image: | ||
|
|
||
| ```yaml | ||
| image: | ||
| repository: n8nio/n8n | ||
| tag: "2.0.0" | ||
|
|
||
| worker: | ||
| enabled: true | ||
| image: | ||
| repository: n8nio/runners | ||
| tag: "2.0.0" | ||
| # IMPORTANT: Do NOT set command or commandArgs when using n8nio/runners | ||
| # The runners image has its own launcher and doesn't use "n8n worker" commands | ||
| ``` | ||
|
|
||
| **Key points:** | ||
| - The main n8n application continues to use `n8nio/n8n` | ||
| - Workers/task runners must use `n8nio/runners` for n8n v2.0+ | ||
| - **Do not set `worker.command` or `worker.commandArgs`** when using the runners image - it has its own entrypoint/launcher | ||
| - The chart automatically omits command/args when a custom worker image is specified | ||
| - If `worker.image.*` is not specified, it defaults to the global `image.*` configuration (backwards compatible) | ||
| - You can specify different tags for main and worker if needed | ||
|
|
||
| For more details, see the [n8n v2.0 breaking changes documentation](https://docs.n8n.io/2-0-breaking-changes/#remove-task-runner-from-n8nion8n-docker-image). |
There was a problem hiding this comment.
Migration guide may be incomplete for a successful v2.0+ deployment.
Based on PR discussion, users upgrading to v2.0+ also need:
- A Service exposing port 5679 for the task broker (runners need to reach it).
- Environment variables
N8N_RUNNERS_TASK_BROKER_URIandN8N_RUNNERS_BROKER_LISTEN_ADDRESSconfigured, since defaults don't work in Kubernetes.
While the PR author has noted that these concerns are outside the current PR scope, the migration guide as written may mislead users into thinking the image swap alone is sufficient. Consider adding a "Known limitations" or "Additional configuration may be required" note to set expectations and prevent failed deployments.
🤖 Prompt for AI Agents
In `@README.md` around lines 817 - 851, The migration docs for "n8n v2.0+ Support
and Task Runner Image" are incomplete: update the README section (the "n8n v2.0+
Support and Task Runner Image" header and the worker image guidance mentioning
worker.image and worker.command/commandArgs) to include a clear "Known
limitations" or "Additional configuration may be required" note that instructs
users to (1) create a Service exposing port 5679 so the runners can reach the
task broker, and (2) configure the environment variables
N8N_RUNNERS_TASK_BROKER_URI and N8N_RUNNERS_BROKER_LISTEN_ADDRESS for Kubernetes
deployments (explain that defaults won’t work), plus a short pointer that these
settings are required in addition to swapping worker.image to n8nio/runners.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 5 files
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="charts/n8n/templates/deployment.worker.yaml">
<violation number="1" location="charts/n8n/templates/deployment.worker.yaml:88">
P2: Using the presence of `worker.image.repository` as a proxy for "this is a runner image that doesn't need command/args" is fragile. If a user explicitly sets `worker.image.repository` to the same value as the global image (e.g., `n8nio/n8n` for clarity or pinning), the worker will silently start without `command: ["n8n"]` and `args: ["worker"]`, breaking the deployment.
Consider comparing `worker.image.repository` against `image.repository` instead, or introducing an explicit boolean flag (e.g., `worker.useRunnerImage: false`) to control this behavior.</violation>
</file>
Since this is your first cubic review, here's how it works:
- cubic automatically reviews your code and comments on bugs and improvements
- Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
- Add one-off context when rerunning by tagging
@cubic-dev-aiwith guidance or docs links (includingllms.txt) - Ask questions if you need clarification on any suggestion
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| {{- /* User has specified a custom command, use it */ -}} | ||
| command: | ||
| {{- toYaml .Values.worker.command | nindent 12 }} | ||
| {{- else if .Values.worker.image.repository }} |
There was a problem hiding this comment.
P2: Using the presence of worker.image.repository as a proxy for "this is a runner image that doesn't need command/args" is fragile. If a user explicitly sets worker.image.repository to the same value as the global image (e.g., n8nio/n8n for clarity or pinning), the worker will silently start without command: ["n8n"] and args: ["worker"], breaking the deployment.
Consider comparing worker.image.repository against image.repository instead, or introducing an explicit boolean flag (e.g., worker.useRunnerImage: false) to control this behavior.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At charts/n8n/templates/deployment.worker.yaml, line 88:
<comment>Using the presence of `worker.image.repository` as a proxy for "this is a runner image that doesn't need command/args" is fragile. If a user explicitly sets `worker.image.repository` to the same value as the global image (e.g., `n8nio/n8n` for clarity or pinning), the worker will silently start without `command: ["n8n"]` and `args: ["worker"]`, breaking the deployment.
Consider comparing `worker.image.repository` against `image.repository` instead, or introducing an explicit boolean flag (e.g., `worker.useRunnerImage: false`) to control this behavior.</comment>
<file context>
@@ -82,15 +82,21 @@ spec:
+ {{- /* User has specified a custom command, use it */ -}}
command:
{{- toYaml .Values.worker.command | nindent 12 }}
+ {{- else if .Values.worker.image.repository }}
+ {{- /* Worker is using a custom image (likely n8nio/runners for v2) - don't set command, let image entrypoint run */ -}}
{{- else }}
</file context>
Add worker.image configuration to allow specifying a separate Docker image
for workers/task runners, enabling compatibility with n8n v2.0+ which moved
task runner functionality to the separate n8nio/runners image.
Changes:
- Add worker.image.{repository,tag,pullPolicy} configuration in values.yaml
- Update deployment.worker.yaml to use worker-specific image with fallback
- Bump chart version to 2.1.0 (backwards-compatible feature)
- Add migration documentation and examples for n8n v2.0+
Maintains full backwards compatibility - existing deployments continue using
the main n8n image for workers when worker.image is not specified.
Ref: https://docs.n8n.io/2-0-breaking-changes/#remove-task-runner-from-n8nion8n-docker-image
Do not supply CMD or ARGS for v2 runners.
Signed-off-by: Josh Baird <jbaird@galileo.io>
joshuabaird
force-pushed
the
chore/v2/separate-worker-image
branch
from
e0d5e59 to
e035d6c
Compare
|
For supporting sidecars acting as task runners for workers, take a look at this workaround #252 (review) |
|
I will work on this since we are now using workers and n8n 2.11 |
7 participants
What this PR does / why we need it
This PR adds support for configuring a separate Docker image for n8n workers/task runners, enabling compatibility with n8n v2.0+ while maintaining full backwards compatibility with v1.x deployments.
Background
Starting with n8n v2.0, the task runner functionality has been removed from the main n8nio/n8n Docker image and moved to a separate n8nio/runners image. This is a breaking change that requires users to configure workers to use the new image.
See: https://docs.n8n.io/2-0-breaking-changes/#remove-task-runner-from-n8nion8n-docker-image
Which issue this PR fixes
Fixes #281.
Checklist
Please place an 'x' in all applicable fields and remove unrelated items.
Version and Documentation
Chart.yamlfollowing semantic versioningChart.yamlif applicableartifacthub.io/changessection updated inChart.yaml(see ArtifactHub annotation reference)README.mdTesting and Validation
ah lintlocally without errorsct lint --chart-dirs charts/n8n --charts charts/n8n --validate-maintainers=false/examplesdirectorySummary by CodeRabbit
New Features
Chores
Documentation