From 87244bf5a8fde5ccace1ad0be5a07cf87e560014 Mon Sep 17 00:00:00 2001 From: vlussenburg Date: Mon, 11 May 2026 16:39:16 -0700 Subject: [PATCH] docs(argo-cd): publish HelmReplacementPath OCL property + valueFiles behaviour MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two related gaps in the Update Argo CD Application Image Tags doc that trip up Config-as-Code users: 1. **OCL property name is undocumented.** The page describes the "Helm image tag path" UI field but never names the OCL/HCL key it serialises to. Users editing deployment_process.ocl directly have to read Calamari source (PackageVariables.HelmReplacementPath) to find that the field is `HelmReplacementPath` on the package reference and the resolved variable is `Octopus.Action.Package[].HelmReplacementPath`. Octopus silently strips unrecognised property names from saved OCL, so guessing (`HelmImageTagPath`, `Octopus.Action.ArgoCD.HelmImageTagPath`, etc.) yields no error — the step just stays a no-op at runtime, which is hard to diagnose. Added an OCL-focused info block with a complete package block example. 2. **"Helm charts" section understates what the step writes to.** The page says "matching image tags in the values.yaml are replaced", which reads as if only the chart's default values.yaml is touched. In practice, when `HelmReplacementPath` is set, the step ALSO writes to every file listed in the Application's spec.source.helm.valueFiles (verified against Calamari/source/Calamari/ArgoCD/Conventions/UpdateImageTag/HelmUpdater.cs `ProcessHelmSourceUsingStepVariables`). This is the behaviour any real per-env Helm-on-Argo setup depends on. Conversely, inline `spec.source.helm.valuesObject` is NOT written — also worth calling out so people don't go hunting. Rewrote the section to spell out both paths (step-configured vs annotation-driven) and the valuesObject limitation explicitly. --- .../steps/update-application-image-tags.md | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/argo-cd/steps/update-application-image-tags.md b/src/pages/docs/argo-cd/steps/update-application-image-tags.md index b8c3cf0a91..3a52a09f72 100644 --- a/src/pages/docs/argo-cd/steps/update-application-image-tags.md +++ b/src/pages/docs/argo-cd/steps/update-application-image-tags.md @@ -20,6 +20,26 @@ When targeting a Helm-based application source, each referenced container image ![The Helm image tag path field in the Reference a package drawer](/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png) ::: +:::div{.info} +**Config-as-Code / OCL:** the **Helm image tag path** field maps to the `HelmReplacementPath` property on the package reference. In an OCL deployment process the property lives inside the package block alongside `Purpose`, `Extract`, etc.: + +```ocl +packages "my-image" { + acquisition_location = "NotAcquired" + feed = "" + package_id = "" + properties = { + Extract = "False" + HelmReplacementPath = "image.tag" + Purpose = "DockerImageReference" + SelectionMode = "immediate" + } +} +``` + +The full variable name resolved at deployment time is `Octopus.Action.Package[].HelmReplacementPath`. Octopus silently ignores unrecognised property names on package references, so a typo (`HelmImageTagPath`, `Octopus.Action.ArgoCD.HelmImageTagPath`, etc.) will be saved as-is but never consulted at runtime, leaving the step unable to find a path and effectively a no-op. +::: + Depending on what the helm value contains: - Only the tag - it will be replaced with the package's version, with no further validation or checking. @@ -60,8 +80,9 @@ For Kubernetes YAML: For Helm charts: -- Image fields are extracted from the [Helm Annotations](/docs/argo-cd/annotations/helm-annotations) -- Matching image tags in the `values.yaml` are replaced with container image versions from the release +- When the step's package reference has a `HelmReplacementPath` (the **Helm image tag path** field) set, the path is read directly from the step configuration. Image tags are replaced in **every Helm values file referenced by the Application** — both the chart's default `values.yaml` and any files listed in the Application's `spec.source.helm.valueFiles` (per-env overrides, etc.). +- When no `HelmReplacementPath` is configured on any package, image paths are instead extracted from the Application's [Helm Annotations](/docs/argo-cd/annotations/helm-annotations) and the same set of values files is updated. (See the [annotation doc](/docs/argo-cd/annotations/helm-annotations) for the requirement that, if used, all package references must rely on annotations rather than step configuration.) +- Inline `spec.source.helm.valuesObject` values are **not** written by this step — the step only edits committed values files. Applications using inline values for image fields will need to either move the image fields into a referenced values file or use a separate mechanism to update them. For Kustomize applications (i.e. supplied path contains `kustomization.yaml`, `kustomization.yml` or `Kustomization`):