diff --git a/public/docs/i/1000/argo-cd/update-application-image-tags-helm-values-tag.webp b/public/docs/i/1000/argo-cd/update-application-image-tags-helm-values-tag.webp new file mode 100644 index 0000000000..1bc4dbdcf5 Binary files /dev/null and b/public/docs/i/1000/argo-cd/update-application-image-tags-helm-values-tag.webp differ diff --git a/public/docs/i/2000/argo-cd/update-application-image-tags-helm-values-tag.webp b/public/docs/i/2000/argo-cd/update-application-image-tags-helm-values-tag.webp new file mode 100644 index 0000000000..77e841d0d4 Binary files /dev/null and b/public/docs/i/2000/argo-cd/update-application-image-tags-helm-values-tag.webp differ diff --git a/public/docs/i/600/argo-cd/update-application-image-tags-helm-values-tag.webp b/public/docs/i/600/argo-cd/update-application-image-tags-helm-values-tag.webp new file mode 100644 index 0000000000..10f8b48718 Binary files /dev/null and b/public/docs/i/600/argo-cd/update-application-image-tags-helm-values-tag.webp differ diff --git a/public/docs/i/x/argo-cd/update-application-image-tags-helm-values-tag.png b/public/docs/i/x/argo-cd/update-application-image-tags-helm-values-tag.png new file mode 100644 index 0000000000..fc7c41b9f4 Binary files /dev/null and b/public/docs/i/x/argo-cd/update-application-image-tags-helm-values-tag.png differ diff --git a/public/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png b/public/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png new file mode 100644 index 0000000000..e3ecb1b566 Binary files /dev/null and b/public/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png differ diff --git a/public/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png.json b/public/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png.json new file mode 100644 index 0000000000..ea02137273 --- /dev/null +++ b/public/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png.json @@ -0,0 +1 @@ +{"width":1588,"height":1214,"updated":"2026-03-11T00:40:11.726Z"} \ No newline at end of file diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index 59b67f7761..7ae689d421 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -1,15 +1,19 @@ --- layout: src/layouts/Default.astro pubDate: 2025-09-15 -modDate: 2025-09-15 +modDate: 2026-03-11 title: Helm Image Tags Annotations description: What annotations are required to navTitle: Helm Annotations hideInThisSectionHeader: true --- +:::div{.info} +**Advanced Feature:** Helm image path configuration via Argo CD Application annotations is an advanced feature, and should only be used if configuring Helm image paths directly in the [Update Argo CD Application Image Tags step](/docs/argo-cd/steps/update-application-image-tags) is insufficient for your requirements. +::: + When executing the [Update Argo CD Application Image Tags step](/docs/argo-cd/steps#update-application-image-tags) against an Argo CD Application that is deploying a Helm chart, -it is necessary to provide extra annotations to define which fields in the Helm values file represent an image to be updated. +it is necessary to provide extra information to allow Octopus to identify the appropriate fields in the Helm values file to update. This is because an image reference could be made up of multiple different values file entries. Consider the image fields in [values.yaml](https://github.com/OctopusDeploy/helm-charts/blob/main/charts/kubernetes-agent/values.yaml) for the Kubernetes agent Helm chart: @@ -37,7 +41,12 @@ global: In this case, the `global.image.repositoryAndTag` contains the tag to be updated. -As the structure of Helm values files can vary widely between charts, it's necessary to require you to specify custom annotations on the Argo CD Applications. +Typically the value path to update would be provided via the **helm image value** field on the package/container defined during step configuration. However, for more complex use cases, you can define the fields to update via custom annotations. + +:::div{.info} +Annotations will only be considered during step-execution if *none* of the packages/containers defined for a step have a helm image value configured. +Thus, if any package/container in your step requires annotations, then all packages must be updated using annotations. +::: The annotation is as follows: 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 f0618a716c..b6470d3d7f 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 @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2025-09-15 -modDate: 2026-03-04 +modDate: 2026-03-11 title: Update Argo CD Application Image Tags description: Deployment steps to modify your Argo CD Applications navOrder: 30 @@ -20,6 +20,12 @@ more information. Add package references for each container image you would like to update when you run your deployment. Unreferenced container images in your manifests will not be changed by Octopus. +When targeting a Helm-based application source, each referenced container image should have a populated **Helm image tag path** field. This is the YAML path to the specific field in your values file that contains the tag of the referenced container image (for example, `agent.image.tag`). This can be set in the **Reference a package** drawer when adding or editing a package reference. This is not required for directory or Kustomize sources. + +:::figure +![The Helm image tag path field in the Reference a package drawer](/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png) +::: + If the application cluster's default registry has been changed, see [cluster annotations](/docs/argo-cd/annotations/cluster-annotations) to ensure the correct default registry is shared with Octopus.