feat(helm): optional per-image tags for gateway, frontend and provisioner (#8337)

* feat(helm): optional per-image tags for gateway, frontend and provisioner

All three DeerFlow images take `image.tag`. A backend rebuilt on top of a
release (extra packages such as an optional sandbox SDK, a local fix) needs
its own tag, so the frontend and provisioner then need re-tagged copies of
the release under that tag.

Add `image.gatewayTag`, `image.frontendTag` and `image.provisionerTag`,
empty by default; an empty one falls back to `image.tag`, so existing
values render unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(helm): fail the render on a non-string per-image tag

`--set image.gatewayTag=20261118` passes an integer: printf rendered the
image as `deer-flow-backend:%!s(int64=20261118)`, and `default` silently
replaced an integer 0 with `image.tag`. A shared `deer-flow.imageTag`
helper now fails the render on any non-string override and names
--set-string; README and values.yaml say to quote numeric tags.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(helm): check the per-image tag's type, not its kind

Helm 3.18.0 passes an unquoted number from a parent chart's values to the
subchart as a json.Number, whose kind is "string", so kindIs let 7.0 and
0123 through and they rendered as 7 and 83. typeIs rejects them; quoted
tags still render as written. The error now names the Go type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Bas Cancrinus 2026-11-19 14:28:40 +01:00 committed by GitHub
parent 5991ab936e
commit b4b489d7f2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 144 additions and 7 deletions

View File

@ -0,0 +1,100 @@
"""Each DeerFlow image can take its own tag; ``image.tag`` stays the default.
All three images shared ``image.tag``, so a backend rebuilt on top of a release
(extra packages, a local fix) forced a matching tag for the frontend and
provisioner images, which then had to be re-tagged copies of the release.
"""
from __future__ import annotations
import shutil
import subprocess
from pathlib import Path
import pytest
import yaml
REPO_ROOT = Path(__file__).resolve().parents[2]
CHART = REPO_ROOT / "deploy" / "helm" / "deer-flow"
def _render(*settings: str, set_flag: str = "--set") -> subprocess.CompletedProcess[str]:
helm = shutil.which("helm")
if helm is None:
pytest.skip("helm is unavailable")
command = [helm, "template", "deer-flow", str(CHART), "--set", "image.registry=registry.example.com/team", "--set", "image.tag=v1.0.0"]
for setting in settings:
command.extend([set_flag, setting])
return subprocess.run(command, check=False, capture_output=True, text=True, encoding="utf-8")
def _images(*settings: str, set_flag: str = "--set") -> dict[str, str]:
result = _render(*settings, set_flag=set_flag)
assert result.returncode == 0, result.stderr
rendered = result.stdout
deployments = [document for document in yaml.safe_load_all(rendered) if isinstance(document, dict) and document.get("kind") == "Deployment"]
images = {}
for deployment in deployments:
for name in ("gateway", "frontend", "provisioner"):
if deployment["metadata"]["name"].endswith(f"-{name}"):
images[name] = deployment["spec"]["template"]["spec"]["containers"][0]["image"]
assert set(images) == {"gateway", "frontend", "provisioner"}
return images
def test_images_share_image_tag_by_default() -> None:
assert _images() == {
"gateway": "registry.example.com/team/deer-flow-backend:v1.0.0",
"frontend": "registry.example.com/team/deer-flow-frontend:v1.0.0",
"provisioner": "registry.example.com/team/deer-flow-provisioner:v1.0.0",
}
@pytest.mark.parametrize(("name", "image"), [("gateway", "deer-flow-backend"), ("frontend", "deer-flow-frontend"), ("provisioner", "deer-flow-provisioner")])
def test_per_image_tag_overrides_only_that_image(name: str, image: str) -> None:
images = _images(f"image.{name}Tag=v1.0.0-custom.1")
assert images.pop(name) == f"registry.example.com/team/{image}:v1.0.0-custom.1"
assert all(ref.endswith(":v1.0.0") for ref in images.values())
@pytest.mark.parametrize("name", ["gateway", "frontend", "provisioner"])
@pytest.mark.parametrize("value", ["20261118", "0"])
def test_numeric_per_image_tag_fails_the_render(name: str, value: str) -> None:
# --set turns a digit string into an integer: printf would render
# `%!s(int64=20261118)`, and `default` would silently drop 0.
result = _render(f"image.{name}Tag={value}")
assert result.returncode != 0
assert f"image.{name}Tag must be a string" in result.stderr
assert "--set-string" in result.stderr
def _render_as_subchart(tmp_path: Path, tag: str) -> subprocess.CompletedProcess[str]:
helm = shutil.which("helm")
if helm is None:
pytest.skip("helm is unavailable")
parent = tmp_path / "parent"
shutil.copytree(CHART, parent / "charts" / "deer-flow")
(parent / "Chart.yaml").write_text("apiVersion: v2\nname: parent\nversion: 0.1.0\n", encoding="utf-8")
(parent / "values.yaml").write_text(f"deer-flow:\n image:\n gatewayTag: {tag}\n", encoding="utf-8")
return subprocess.run([helm, "template", "parent", str(parent)], check=False, capture_output=True, text=True, encoding="utf-8")
@pytest.mark.parametrize("value", ["7.0", "0123"])
def test_numeric_per_image_tag_from_parent_chart_fails_the_render(tmp_path: Path, value: str) -> None:
# Helm 3.18.0 passes an unquoted number from a parent chart's values to the
# subchart as a json.Number (kind "string"): 7.0 and 0123 rendered as 7 and 83.
result = _render_as_subchart(tmp_path, value)
assert result.returncode != 0
assert "image.gatewayTag must be a string" in result.stderr
def test_quoted_per_image_tag_from_parent_chart_renders(tmp_path: Path) -> None:
result = _render_as_subchart(tmp_path, '"0123"')
assert result.returncode == 0, result.stderr
assert "deer-flow-backend:0123" in result.stdout
def test_numeric_per_image_tag_as_string_renders() -> None:
images = _images("image.gatewayTag=20261118", set_flag="--set-string")
assert images["gateway"] == "registry.example.com/team/deer-flow-backend:20261118"
assert images["frontend"].endswith(":v1.0.0")

View File

@ -59,6 +59,13 @@ pull secret (step 1) and reference it via `image.pullSecrets`.
> `appVersion`; always set `image.tag` to the release that matches your chart
> `--version` unless you have a reason to pin differently.
`image.gatewayTag`, `image.frontendTag` and `image.provisionerTag` override
`image.tag` for one image, e.g. a backend you rebuild on top of a release
(`v2.2.0-custom.1`) while the frontend stays on the published `v2.2.0`.
They must be strings: `--set image.gatewayTag=20261118` passes an integer and
fails the render, so quote a numeric tag in YAML (`gatewayTag: "20261118"`) or
use `--set-string image.gatewayTag=20261118`.
## 1. Build & push images (custom builds only)
Skip this section if you're using the published chart above. To build the

View File

@ -37,22 +37,45 @@ imagePullSecrets:
{{- end }}
{{- end -}}
{{/* Fully-qualified image refs for the three DeerFlow images.
{{/* Fully-qualified image refs for the three DeerFlow images. Each takes its
own tag (`image.<name>Tag`) when set, otherwise `image.tag`.
When `image.registry` is empty, omit the prefix so the ref is
`deer-flow-gateway:latest` (local-image mode, imagePullPolicy: Never). */}}
{{- define "deer-flow.gatewayImage" -}}
{{- if .Values.image.registry -}}{{- printf "%s/%s:%s" .Values.image.registry .Values.image.gatewayImage .Values.image.tag -}}
{{- else -}}{{- printf "%s:%s" .Values.image.gatewayImage .Values.image.tag -}}{{- end -}}
{{- $tag := include "deer-flow.imageTag" (dict "Values" .Values "key" "gatewayTag") -}}
{{- if .Values.image.registry -}}{{- printf "%s/%s:%s" .Values.image.registry .Values.image.gatewayImage $tag -}}
{{- else -}}{{- printf "%s:%s" .Values.image.gatewayImage $tag -}}{{- end -}}
{{- end -}}
{{- define "deer-flow.frontendImage" -}}
{{- if .Values.image.registry -}}{{- printf "%s/%s:%s" .Values.image.registry .Values.image.frontendImage .Values.image.tag -}}
{{- else -}}{{- printf "%s:%s" .Values.image.frontendImage .Values.image.tag -}}{{- end -}}
{{- $tag := include "deer-flow.imageTag" (dict "Values" .Values "key" "frontendTag") -}}
{{- if .Values.image.registry -}}{{- printf "%s/%s:%s" .Values.image.registry .Values.image.frontendImage $tag -}}
{{- else -}}{{- printf "%s:%s" .Values.image.frontendImage $tag -}}{{- end -}}
{{- end -}}
{{- define "deer-flow.provisionerImage" -}}
{{- if .Values.image.registry -}}{{- printf "%s/%s:%s" .Values.image.registry .Values.image.provisionerImage .Values.image.tag -}}
{{- else -}}{{- printf "%s:%s" .Values.image.provisionerImage .Values.image.tag -}}{{- end -}}
{{- $tag := include "deer-flow.imageTag" (dict "Values" .Values "key" "provisionerTag") -}}
{{- if .Values.image.registry -}}{{- printf "%s/%s:%s" .Values.image.registry .Values.image.provisionerImage $tag -}}
{{- else -}}{{- printf "%s:%s" .Values.image.provisionerImage $tag -}}{{- end -}}
{{- end -}}
{{/* Tag of one DeerFlow image: `image.<key>` when it is a non-empty string,
otherwise `image.tag`. Takes a dict with `Values` and `key` (gatewayTag,
frontendTag or provisionerTag). A tag that is not a string fails the
render: `--set image.gatewayTag=20261118` arrives as an integer, which
printf renders as `%!s(int64=20261118)`, and `default` would silently
replace an integer 0 with `image.tag`. The check is on the type, not the
kind: Helm 3.18.0 hands an unquoted number from a parent chart's values
to the subchart as a json.Number, whose kind is "string", so `7.0` and
`0123` would render as 7 and 83. */}}
{{- define "deer-flow.imageTag" -}}
{{- $value := get .Values.image .key -}}
{{- if kindIs "invalid" $value -}}{{- .Values.image.tag -}}
{{- else if not (typeIs "string" $value) -}}
{{- fail (printf "image.%s must be a string (got %s %v); quote it in YAML or set it with --set-string image.%s=..." .key (typeOf $value) $value .key) -}}
{{- else if eq (toString $value) "" -}}{{- .Values.image.tag -}}
{{- else -}}{{- toString $value -}}
{{- end -}}
{{- end -}}
{{- define "deer-flow.nginxImage" -}}

View File

@ -22,6 +22,13 @@ image:
gatewayImage: deer-flow-backend
frontendImage: deer-flow-frontend
provisionerImage: deer-flow-provisioner
# Optional per-image tags; empty uses `tag`. For an image you rebuild on top
# of a release (e.g. a backend with extra packages) while the others stay on
# the published release tag. Tags must be strings: quote a numeric tag in
# YAML ("20261118") or set it with --set-string.
gatewayTag: ""
frontendTag: ""
provisionerTag: ""
# -- Gateway (backend) deployment.
gateway: