From 5aa8b0fec3980e16b004c0a630a23831163d3f6f Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Sun, 26 Oct 2025 21:19:26 +1000 Subject: [PATCH 1/9] Remove Helm aliases and use name instead --- .../argo-cd/annotations/helm-annotations.md | 176 +++++------------- 1 file changed, 45 insertions(+), 131 deletions(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index e3bb03801a..a964cda2e4 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -37,12 +37,13 @@ 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. -The annotations are: +The annotation is as follows: -| Annotation | Alias required | Required | Value description | -|------------------------------------------------|----------------|----------|-----------------------------------------------------------------------------------------------| -| `argo.octopus.com/image-replace-paths.{alias}` | false | true | A comma-delimited Helm-template style string that builds a list of full qualified image names | -| `argo.octopus.com/image-replace-alias.{alias}` | true | false | The path of a ValueFiles entry in the `spec.destinations.helm.valuesFiles` field | +| Annotation | Value description | +|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------| +| `argo.octopus.com/image-replace-paths[.]` | A comma-delimited Helm-template style string that builds a list of full qualified image names | + +Note that while the scoping annotation for the project/environment is against the source to be updated, the path annotation is against the chart/helm source. All value files for a given chart are assumed to contain the same structure. ## Details @@ -57,7 +58,7 @@ Octopus can then use this to match on containers being updated and can then use ### Image path templates -The following is some examples of how to format the Helm-templated string to put into the `argo.octopus.com/image-replace-paths.{alias}` annotation based on different values file structures. +The following is some examples of how to format the Helm-templated string to put into the `argo.octopus.com/image-replace-paths[.]` annotation based on different values file structures. #### Example 1 @@ -105,13 +106,13 @@ metadata: argo.octopus.com/image-replace-paths: "{{ .Values.global.image.registry }}/{{ .Values.global.image.repositoryAndTag }}" ``` -### Ref sources and alias examples +### Ref source examples The following is a list of example Argo CD Application structures, the required annotations and sample values files. #### Example 1 -With a single values file and a single Helm source, we don't need the `alias` in the paths. +With a single Helm source, the Helm source can be unnamed and the paths annotation is unscoped. The same path is applied to all value files belonging to the chart/Helm source. **application manifest** ```yaml @@ -132,6 +133,7 @@ spec: helm: valueFiles: - values.yaml + - app-files/values-overlay.yaml ``` **values.yaml** @@ -146,16 +148,16 @@ another-image: #### Example 2 -A single Ref source used to source the values.yaml for the Helm source. In this scenario, the `alias` is the same as the `ref` value. +A single Ref source used to source the values.yaml for the Helm source. In this scenario, both sources need to be named and the paths annotation is source-scoped. Note that the scoping annotation for the project/environment is against the ref-source while the path annotation is against the chart/helm source. ```yaml ... metadata: annotations: - argo.octopus.com/project: "proj-1" - argo.octopus.com/environment: "development" + argo.octopus.com/project.ref-source: "proj-1" + argo.octopus.com/environment.ref-source: "development" - argo.octopus.com/image-replace-paths.remote-values: "{{ .Values.image.name}}:{{ .Values.image.version}}, {{ .Values.another-image.name }}" + argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.image.name}}:{{ .Values.image.version}}, {{ .Values.another-image.name }}" ... spec: sources: @@ -165,10 +167,11 @@ spec: helm: valueFiles: - $remote-values/values.yaml - + name: helm-source - repoURL: https://github.com/another-repo/values-files-here targetRevision: main ref: remote-values + name: ref-source ``` **values.yaml** @@ -189,14 +192,12 @@ A Helm source that references both a ref sourced values file and also an in-repo ... metadata: annotations: - argo.octopus.com/project: "proj-1" - argo.octopus.com/environment: "development" - - argo.octopus.com/image-replace-alias.core: "app-files/values.yaml" - argo.octopus.com/image-replace-alias.remote: "$remote-values/values.yaml" - - argo.octopus.com/image-replace-paths.core: "{{ .Values.image.name}}:{{ .Values.image.version}}" - argo.octopus.com/image-replace-paths.remote: "{{ .Values.different.structure.here.image }}" + argo.octopus.com/project.helm-source: "proj-1" + argo.octopus.com/environment.helm-source: "development" + argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.image.name}}:{{ .Values.image.version}}" + argo.octopus.com/project.ref-source: "proj-1" + argo.octopus.com/environment.ref-source: "development" + argo.octopus.com/image-replace-paths.ref-source: "{{ .Values.different.structure.here.image }}" ... spec: sources: @@ -207,10 +208,11 @@ spec: valueFiles: - app-files/values.yaml - $remote-values/values.yaml - + name: helm-source - repoURL: https://github.com/another-repo/values-files-here targetRevision: main ref: remote-values + name: ref-source ``` **app-files/values.yaml** @@ -227,62 +229,21 @@ different: image: busybox:1 ``` + #### Example 4 -A Helm source that references multiple values files from the source repo. +A Helm source that has multiple ref sourced values files. Each ref source can be updated by a different project if required. ```yaml ... metadata: annotations: - argo.octopus.com/project: "proj-1" - argo.octopus.com/environment: "development" - - # When there are multiple sources, we need an annotation to tell us which file path annotations belong to (Note: the actual name of the alias can be arbitrary) - # if an alias is not provided for a path, that values file will be ignored - argo.octopus.com/image-replace-alias.core: "app-files/values.yaml" - argo.octopus.com/image-replace-alias.overlay: "app-files/values-overlay.yaml" + argo.octopus.com/project.remote-source: "proj-1" + argo.octopus.com/environmen.remote-source: "development" + argo.octopus.com/project.other-source: "proj-2" + argo.octopus.com/environmen.other-source: "development" - argo.octopus.com/image-replace-paths.core: "{{ .Values.image.name}}:{{ .Values.image.version}}" - argo.octopus.com/image-replace-paths.overlay: "{{ .Values.different.structure.here.image }}" -... -spec: - sources: - - repoURL: https://github.com/my-org/my-argo-helm-app - path: "chart" - targetRevision: main - helm: - valueFiles: - - app-files/values.yaml - - app-files/values-overlay.yaml -``` - -**app-files/values.yaml** -```yaml -image: - name: nginx/nginx - version: 1.19.0 -``` -**$remote-values/values-overlay.yaml** -```yaml -different: - structure: - here: - image: busybox:1 -``` - -#### Example 5 - -A Helm source that has multiple ref sourced values files. - -```yaml -... -metadata: - annotations: - argo.octopus.com/project: "proj-1" - argo.octopus.com/environment: "development" - - argo.octopus.com/image-replace-paths.other-values: "{{ .Values.another-image.name }}" + argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.another-image.name }}" argo.octopus.com/image-replace-paths.remote-values: "{{ .Values.image.name}}:{{ .Values.image.version}}" ... spec: @@ -290,10 +251,12 @@ spec: - repoURL: https://github.com/main-repo/values-files-here targetRevision: main ref: other-values + name: other-source - - repoURL: https://github.com/another-repo/values-files-here +- repoURL: https://github.com/another-repo/values-files-here targetRevision: main ref: remote-values + name: remote-source - repoURL: https://github.com/my-repo/my-argo-app path: "./" @@ -302,6 +265,7 @@ spec: valueFiles: - $other-values/values.yaml - $remote-values/values.yaml + name: helm-source ``` **$remote-values/values.yaml** @@ -316,57 +280,7 @@ another-image: name: busybox:1 ``` -#### Example 6 - -Multiple Helm sources with a same values file path in both sources. - -Note: The alias requires a fully qualified repo path in the format: `{repoUrl}/{targetRevision}/{path}/{valuesFile}`. - -```yaml -... -metadata: - annotations: - argo.octopus.com/project: "proj-1" - argo.octopus.com/environment: "development" - - argo.octopus.com/image-replace-alias.app1: "https://github.com/my-repo/my-argo-app/main/values.yaml" - argo.octopus.com/image-replace-alias.app2: "https://github.com/my-repo/my-other-argo-app/main/cool/values.yaml" - - argo.octopus.com/image-replace-paths.app1: "{{ .Values.image.name}}:{{ .Values.image.version}}" - argo.octopus.com/image-replace-paths.app2: "{{ .Values.different.structure.here.image }}" -... -spec: - sources: - - repoURL: https://github.com/my-repo/my-argo-app - path: "./" - targetRevision: main - helm: - valueFiles: - - values.yaml - - - repoURL: https://github.com/my-repo/my-other-argo-app - path: "cool" - targetRevision: main - helm: - valueFiles: - - values.yaml -``` - -**https://github.com/my-repo/my-argo-app/main/values.yaml** -```yaml -image: - name: nginx/nginx - version: 1.19.0 -``` -**https://github.com/my-repo/my-other-argo-app/main/cool/values.yaml** -```yaml -different: - structure: - here: - image: busybox:1 -``` - -#### Example 7 +#### Example 5 Multiple Helm sources that reference different values files from the same ref source. @@ -374,34 +288,34 @@ Multiple Helm sources that reference different values files from the same ref so ... metadata: annotations: - argo.octopus.com/project: "proj-1" - argo.octopus.com/environment: "development" - - argo.octopus.com/image-replace-alias.shared1: "$shared-values/some-path/values.yaml" - argo.octopus.com/image-replace-alias.shared2: "$shared-values/another-path/values.yaml" + argo.octopus.com/project.values-source: "proj-1" + argo.octopus.com/environment.values-source: "development" - argo.octopus.com/image-replace-paths.shared1: "{{ .Values.image.name}}:{{ .Values.image.version}}" - argo.octopus.com/image-replace-paths.shared2: "{{ .Values.different.structure.here.image }}" + argo.octopus.com/image-replace-paths.service-1-source: "{{ .Values.image.name}}:{{ .Values.image.version}}" + argo.octopus.com/image-replace-paths.service-2-source: "{{ .Values.different.structure.here.image }}" ... spec: sources: - repoURL: https://github.com/another-repo/shared-values-files-here targetRevision: main ref: shared-values + name: values-source - repoURL: https://github.com/my-repo/my-argo-app-be - path: "app-files" + path: "service-1-files" targetRevision: main helm: valueFiles: - $shared-values/some-path/values.yaml + name: service-1-source - repoURL: https://github.com/my-repo/my-argo-app-fe - path: "app-files" + path: "service-2-files" targetRevision: main helm: valueFiles: - $shared-values/another-path/values.yaml + name: service-2-source ``` **$shared-values/some-path/values.yaml** From 7b62eab5aa4fed4b7422797aca904510f858cc6d Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Sun, 26 Oct 2025 21:37:55 +1000 Subject: [PATCH 2/9] Typo --- src/pages/docs/argo-cd/annotations/helm-annotations.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index a964cda2e4..04b1ce3fba 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -106,7 +106,7 @@ metadata: argo.octopus.com/image-replace-paths: "{{ .Values.global.image.registry }}/{{ .Values.global.image.repositoryAndTag }}" ``` -### Ref source examples +### Application examples The following is a list of example Argo CD Application structures, the required annotations and sample values files. @@ -148,7 +148,9 @@ another-image: #### Example 2 -A single Ref source used to source the values.yaml for the Helm source. In this scenario, both sources need to be named and the paths annotation is source-scoped. Note that the scoping annotation for the project/environment is against the ref-source while the path annotation is against the chart/helm source. +A single Ref source used to source the values.yaml for the Helm source. In this scenario, both sources need to be named and the paths annotation is source-scoped. + +Note that the scoping annotation for the project/environment is against the ref-source while the path annotation is against the chart/helm source. ```yaml ... @@ -239,9 +241,9 @@ A Helm source that has multiple ref sourced values files. Each ref source can be metadata: annotations: argo.octopus.com/project.remote-source: "proj-1" - argo.octopus.com/environmen.remote-source: "development" + argo.octopus.com/environment.remote-source: "development" argo.octopus.com/project.other-source: "proj-2" - argo.octopus.com/environmen.other-source: "development" + argo.octopus.com/environment.other-source: "development" argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.another-image.name }}" argo.octopus.com/image-replace-paths.remote-values: "{{ .Values.image.name}}:{{ .Values.image.version}}" From 3075721c6cf6079ff54ea3284e2f063552ebdfb6 Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Mon, 27 Oct 2025 11:17:53 +1000 Subject: [PATCH 3/9] Review comments --- src/pages/docs/argo-cd/annotations/helm-annotations.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index 04b1ce3fba..056a1a9202 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -196,10 +196,10 @@ metadata: annotations: argo.octopus.com/project.helm-source: "proj-1" argo.octopus.com/environment.helm-source: "development" - argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.image.name}}:{{ .Values.image.version}}" argo.octopus.com/project.ref-source: "proj-1" argo.octopus.com/environment.ref-source: "development" - argo.octopus.com/image-replace-paths.ref-source: "{{ .Values.different.structure.here.image }}" + + argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.image.name}}:{{ .Values.image.version}}" ... spec: sources: @@ -246,7 +246,6 @@ metadata: argo.octopus.com/environment.other-source: "development" argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.another-image.name }}" - argo.octopus.com/image-replace-paths.remote-values: "{{ .Values.image.name}}:{{ .Values.image.version}}" ... spec: sources: @@ -284,7 +283,7 @@ another-image: #### Example 5 -Multiple Helm sources that reference different values files from the same ref source. +Multiple Helm sources that reference different values files from the same ref source. If you need to update your value files independently, then we recommend letting the Helm sources reference different ref sources. ```yaml ... From d05612207b8d96631bbd4a384205839e18a40554 Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Mon, 27 Oct 2025 13:51:43 +1000 Subject: [PATCH 4/9] Update src/pages/docs/argo-cd/annotations/helm-annotations.md Co-authored-by: Trent Mohay --- src/pages/docs/argo-cd/annotations/helm-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index 056a1a9202..1e5566ce1f 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -41,7 +41,7 @@ The annotation is as follows: | Annotation | Value description | |-------------------------------------------------------------|-----------------------------------------------------------------------------------------------| -| `argo.octopus.com/image-replace-paths[.]` | A comma-delimited Helm-template style string that builds a list of full qualified image names | +| `argo.octopus.com/image-replace-paths[.]` | A comma-delimited Helm-template style string that builds a list of fully qualified image names | Note that while the scoping annotation for the project/environment is against the source to be updated, the path annotation is against the chart/helm source. All value files for a given chart are assumed to contain the same structure. From bf509f1e8471af815e5d8820f48cbf10c3e05206 Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Mon, 27 Oct 2025 13:51:52 +1000 Subject: [PATCH 5/9] Update src/pages/docs/argo-cd/annotations/helm-annotations.md Co-authored-by: Trent Mohay --- src/pages/docs/argo-cd/annotations/helm-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index 1e5566ce1f..c577489a1d 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -43,7 +43,7 @@ The annotation is as follows: |-------------------------------------------------------------|-----------------------------------------------------------------------------------------------| | `argo.octopus.com/image-replace-paths[.]` | A comma-delimited Helm-template style string that builds a list of fully qualified image names | -Note that while the scoping annotation for the project/environment is against the source to be updated, the path annotation is against the chart/helm source. All value files for a given chart are assumed to contain the same structure. +Note that while the scoping annotation for the project/environment is defined for the source to be *updated*, the path annotation is defined for the chart/helm source. All value files for a given chart are assumed to have the same structure. ## Details From f3e3a081776b4de870ee8629f83583d70dde47ec Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Mon, 27 Oct 2025 13:57:43 +1000 Subject: [PATCH 6/9] remove file --- src/pages/docs/argo-cd/annotations/helm-annotations.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index c577489a1d..4e927dd875 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -133,7 +133,6 @@ spec: helm: valueFiles: - values.yaml - - app-files/values-overlay.yaml ``` **values.yaml** From 93797561c2c9e66ed5ba7fba6e708fa97d064d3e Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Mon, 27 Oct 2025 13:57:56 +1000 Subject: [PATCH 7/9] Update src/pages/docs/argo-cd/annotations/helm-annotations.md Co-authored-by: Trent Mohay --- src/pages/docs/argo-cd/annotations/helm-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index c577489a1d..8d1535b5ee 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -148,7 +148,7 @@ another-image: #### Example 2 -A single Ref source used to source the values.yaml for the Helm source. In this scenario, both sources need to be named and the paths annotation is source-scoped. +A single Ref source used to source the values.yaml for the Helm source. In this scenario, both sources need to be named and the paths annotation must explicitly specify the helm source. Note that the scoping annotation for the project/environment is against the ref-source while the path annotation is against the chart/helm source. From e1d80aa67a2fb5439f3b9fad6695cdea7744691c Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Mon, 27 Oct 2025 13:58:04 +1000 Subject: [PATCH 8/9] Update src/pages/docs/argo-cd/annotations/helm-annotations.md Co-authored-by: Trent Mohay --- src/pages/docs/argo-cd/annotations/helm-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index 8d1535b5ee..7cb52b0505 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -150,7 +150,7 @@ another-image: A single Ref source used to source the values.yaml for the Helm source. In this scenario, both sources need to be named and the paths annotation must explicitly specify the helm source. -Note that the scoping annotation for the project/environment is against the ref-source while the path annotation is against the chart/helm source. +Note that the scoping annotation for the project/environment specifies the ref-source while the path annotation is specified for the chart/helm source. ```yaml ... From 73527d2a1cd26b50701d67f9d00f57b705805706 Mon Sep 17 00:00:00 2001 From: Frank Lin Date: Mon, 27 Oct 2025 14:03:24 +1000 Subject: [PATCH 9/9] fix annotation --- src/pages/docs/argo-cd/annotations/helm-annotations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/argo-cd/annotations/helm-annotations.md b/src/pages/docs/argo-cd/annotations/helm-annotations.md index a9e3cdb021..26536b500f 100644 --- a/src/pages/docs/argo-cd/annotations/helm-annotations.md +++ b/src/pages/docs/argo-cd/annotations/helm-annotations.md @@ -198,7 +198,7 @@ metadata: argo.octopus.com/project.ref-source: "proj-1" argo.octopus.com/environment.ref-source: "development" - argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.image.name}}:{{ .Values.image.version}}" + argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.image.name}}:{{ .Values.image.version}}, {{ .Values.different.structure.here.image }}" ... spec: sources: @@ -244,7 +244,7 @@ metadata: argo.octopus.com/project.other-source: "proj-2" argo.octopus.com/environment.other-source: "development" - argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.another-image.name }}" + argo.octopus.com/image-replace-paths.helm-source: "{{ .Values.image.name}}:{{ .Values.image.version}}, {{ .Values.another-image.name }}" ... spec: sources: