Skip to content

docs(argo-cd): publish HelmReplacementPath OCL property + clarify valueFiles handling for Update Image Tags step#3141

Open
vlussenburg wants to merge 1 commit into
OctopusDeploy:mainfrom
vlussenburg:docs/argocd-update-image-tags-helm-replacement-path
Open

docs(argo-cd): publish HelmReplacementPath OCL property + clarify valueFiles handling for Update Image Tags step#3141
vlussenburg wants to merge 1 commit into
OctopusDeploy:mainfrom
vlussenburg:docs/argocd-update-image-tags-helm-replacement-path

Conversation

@vlussenburg
Copy link
Copy Markdown

Two related gaps in the Update Argo CD Application Image Tags doc that trip up Config-as-Code users:

1. The OCL property name behind the "Helm image tag path" field 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 discover that:

  • the package-level property name is HelmReplacementPath
  • the resolved deployment-time variable is Octopus.Action.Package[<ref>].HelmReplacementPath

Octopus's OCL save silently strips unrecognised property names from package references, so guessing names like HelmImageTagPath or Octopus.Action.ArgoCD.HelmImageTagPath yields no error — the step just stays a no-op at runtime, which is genuinely hard to diagnose without reading source code. Added an OCL-focused info block with a complete `packages` example.

2. The "For Helm charts" section understates what the step writes to

The current text reads:

Image fields are extracted from the Helm Annotations. Matching image tags in the `values.yaml` are replaced with container image versions from the release.

This reads as if only the chart's default `values.yaml` is ever touched, which would make the step useless for the common per-env values-file pattern. In practice, when `HelmReplacementPath` is set, the step also writes to every file listed in the Application's `spec.source.helm.valueFiles` — confirmed against HelmUpdater.ProcessHelmSourceUsingStepVariables.

Conversely, inline `spec.source.helm.valuesObject` is not written by the step (the step only edits committed values files). Also worth calling out so users with valuesObject-based Applications don't go chasing missing tag bumps.

Rewrote the bullet list to spell out both code paths (step-configured vs annotation-driven) and the `valuesObject` limitation explicitly.

Why

Both items came up debugging a working Octopus + Argo CD lab where the step ran "Success" for every deployment but reported `Nothing to update for Application` for several days. Root cause was a guessed OCL property name (which Octopus accepted on save but ignored at runtime) plus an architecture using inline `valuesObject`. The doc as it stands doesn't put a CaC user in a position to spot either.

Out of scope

  • Same OCL-property gap likely applies to other Argo CD steps with package-level configuration; haven't audited those.
  • Could also benefit from a paragraph on the `argo-cd-helm-replace-path-from-container-reference` feature toggle, but that's a feature-flag concern and probably belongs in a separate doc once the toggle is removed.

…behaviour

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[<ref>].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.
@CLAassistant
Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants