From b4b489d7f2fb22fc88305a26e1c6e6077b497216 Mon Sep 17 00:00:00 2001 From: Bas Cancrinus <7222814+bascan@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:28:40 +0100 Subject: [PATCH] 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 * 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 * 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 --------- Co-authored-by: Claude Opus 5.5 --- backend/tests/test_helm_image_tags.py | 100 +++++++++++++++++++ deploy/helm/deer-flow/README.md | 7 ++ deploy/helm/deer-flow/templates/_helpers.tpl | 37 +++++-- deploy/helm/deer-flow/values.yaml | 7 ++ 4 files changed, 144 insertions(+), 7 deletions(-) create mode 100644 backend/tests/test_helm_image_tags.py diff --git a/backend/tests/test_helm_image_tags.py b/backend/tests/test_helm_image_tags.py new file mode 100644 index 0000000000..384aa2ab69 --- /dev/null +++ b/backend/tests/test_helm_image_tags.py @@ -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") diff --git a/deploy/helm/deer-flow/README.md b/deploy/helm/deer-flow/README.md index a91d57a94a..e06f6d8093 100644 --- a/deploy/helm/deer-flow/README.md +++ b/deploy/helm/deer-flow/README.md @@ -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 diff --git a/deploy/helm/deer-flow/templates/_helpers.tpl b/deploy/helm/deer-flow/templates/_helpers.tpl index 660526afd1..fc7d8bbb91 100644 --- a/deploy/helm/deer-flow/templates/_helpers.tpl +++ b/deploy/helm/deer-flow/templates/_helpers.tpl @@ -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.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.` 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" -}} diff --git a/deploy/helm/deer-flow/values.yaml b/deploy/helm/deer-flow/values.yaml index 4fb328c02f..fa625e15ba 100644 --- a/deploy/helm/deer-flow/values.yaml +++ b/deploy/helm/deer-flow/values.yaml @@ -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: