From 0630e0f90e9aa8bbf5b589d674037089727bcb42 Mon Sep 17 00:00:00 2001 From: Ian Watts Date: Fri, 28 Aug 2026 10:37:44 -0700 Subject: [PATCH 1/4] Add new argo doc to left nav --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index cf09451e..d5657edc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,6 +23,7 @@ nav: - OpenShift project resource quotas: docs/automation-and-resiliency/openshift-project-resource-quotas.md - Request a quota adjustment for an OpenShift project set: docs/automation-and-resiliency/request-quota-adjustment-for-openshift-project-set.md - Argo CD usage: docs/automation-and-resiliency/argo-cd-usage.md + - Argo Image Updater: docs/automation-and-resiliency/argo-cd-image-updater.md - Restoring Backup Volumes on OpenShift: docs/automation-and-resiliency/netapp-backup-restore.md - Prepare to load test an application on OpenShift: docs/automation-and-resiliency/prepare-to-load-test-application-on-openshift.md - Product Team Recovery Best Practices and Responsibilities: docs/automation-and-resiliency/namespace-recovery-and-responsibilities.md From 1042e4eee2b6f5b23a805cc1a58fe6ba878404eb Mon Sep 17 00:00:00 2001 From: Ian Watts Date: Fri, 28 Aug 2026 10:47:19 -0700 Subject: [PATCH 2/4] Add argocd image updater doc --- .../argo-cd-image-updater.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 src/docs/automation-and-resiliency/argo-cd-image-updater.md diff --git a/src/docs/automation-and-resiliency/argo-cd-image-updater.md b/src/docs/automation-and-resiliency/argo-cd-image-updater.md new file mode 100644 index 00000000..39fb0577 --- /dev/null +++ b/src/docs/automation-and-resiliency/argo-cd-image-updater.md @@ -0,0 +1,174 @@ +# Argo CD Image Updater +The image updater automatically detects new versions of images used in your Argo CD-managed deployments and applies them according to your configuration. + +## Overview +Create an `ImageUpdater` custom resource in the same namespace as your Argo CD application and define the scope of acceptable image tags. Argo CD will monitor the container registry and when it finds a newer image that meets your criteria, it will automatically apply the new image to your deployment, saving you extra steps or manual intervention. + +If the app has auto-sync enabled, the change in image will be applied immediately; if not, the app will show as out of sync and may be updated by manually syncing it. + +## Requirements +* The deployment must be managed with either **Helm** or **Kustomize**. +* The Argo CD Application must be in your own namespace. +* The ImageUpdater CR must be in the same namespace. +* If the container repo is private, a pull secret must be configured in the ImageUpdater, as well as RBAC for the controller to read the pull secret. + +## Documentation +* [Argo CD Image Updater](https://argocd-image-updater.readthedocs.io/en/stable/) +* [Red Hat GitOps Operator: Using Argo CD Image Updater](https://docs.redhat.com/en/documentation/red_hat_openshift_gitops/1.21/html/argo_cd_instance/using-argo-cd-image-updater) + +## Setup +Firstly, the Argo CD Application must be in your namespace. The tools namespace would be a good choice. If you originally created the application via the Argo CD UI, you would need to recreate it in your own namespace before proceeding. + +Secondly, the application **must use Helm or Kustomize**, otherwise Argo CD won't be able to apply the image change automatically. + +You probably won't have to make any changes to the application configuration unless it's a Helm chart that does not parameterize the image tag. + +## Update methods +Argo CD keeps track of image updates using one of two methods: +* `argocd` - (default) Image status is written to the Argo CD application. +* `git` - Image status is written to a new file in the app's Git repository. + +For now, because the image updater controller has not been granted write access to your GitOps repo, **only the 'argocd' option is available**. + +## Update strategies +Update strategies determine how Argo CD will look for new versions of an image. +* `semver` - Use semantic versioning constraints +* `newest-build` - Use the most recent image +* `digest` - Use the most recent version of a given tag by using the SHA digest +* `alphabetical` - Sort tags alphabetically and use the "highest" one + +See the [Argo CD documentation](https://argocd-image-updater.readthedocs.io/en/stable/basics/update-strategies/) for more information. + +## Examples +The following examples do not represent all of the available options. They are meant to help you understand how the image updater can be used and to reduce the time it takes to set up your own app. Refer to the documentation links for complete details. + +### Example 1 - Helm +The Helm chart must have a parameter for the image tag. + +Suppose the Helm chart has a Deployment template that specifies the image as: +``` +image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}" +``` + +and has a values file that defines the image name and tag: +``` +image: + repository: caddy + tag: "2.10.1" +``` + +The following ImageUpdater uses a 'newest-build' strategy, but also adds an 'allowTags' field to limit updates to the `2.10.x` pattern, so as new patch versions of 2.10 are released, they will be automatically applied by Argo CD, but it will not be updated to 2.11 or higher. +``` +apiVersion: argocd-image-updater.argoproj.io/v1alpha1 +kind: ImageUpdater +metadata: + name: image-updater-helm + namespace: NAMESPACE_NAME +spec: + applicationRefs: + - namePattern: image-updater-helm # the name of the argocd app + images: + - alias: caddy # a short alias for the image name + imageName: caddy # the full name of the image + commonUpdateSettings: + updateStrategy: newest-build # Use the most recent matching build + allowTags: regexp:^2\.10\.[0-9]+$ # Only match tags like 2.10.x +``` + +### Example 2 - Kustomize +In this example, a Kustomize app uses the 'latest' tag. Because the tag does not change, the image updater uses the SHA checksum to look for changes and will apply the checksum value as the image tag in your live deployment. + +Our Kustomize base deployment uses a standard image reference: +``` +spec: + template: + spec: + containers: + - image: 'docker.io/nicolaka/netshoot:latest' +``` + +Our ImageUpdater uses the 'digest' update strategy and we add an extra block for Kustomize: +``` +apiVersion: argocd-image-updater.argoproj.io/v1alpha1 +kind: ImageUpdater +metadata: + name: image-updater-kustomize + namespace: NAMESPACE_NAME +spec: + applicationRefs: + - namePattern: image-updater-kustomize # the argocd app name + images: + - alias: netshoot + imageName: docker.io/nicolaka/netshoot:latest # full image name + commonUpdateSettings: + # Use 'digest' update strategy when tracking a tag like 'latest' + updateStrategy: digest + # For Kustomize apps, we need the following block + manifestTargets: + kustomize: + name: docker.io/nicolaka/netshoot +``` + +### Example 3 - Non-public container repo +If the container repo is not publicly available, a pull secret must be provided. + +Additionally, **you must grant permission to the image updater controller to read secrets in your namespace**. + +The image updater controller has not been granted permission to read secrets in all user namespaces. If you would like to use it with a private repo, grant access by creating a Role and RoleBinding in the same namespace as the ImageUpdater and Argo CD app. +``` +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: image-updater-secrets + namespace: NAMESPACE_NAME +rules: + - apiGroups: + - "" + resources: + - secrets + verbs: + - get +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: image-updater-secrets + namespace: NAMESPACE_NAME +subjects: + - kind: ServiceAccount + name: gitops-shared-argocd-image-updater-controller + namespace: openshift-bcgov-gitops-shared +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: image-updater-secrets +``` + +Create an image pull secret for the given container repository. + +This is like the previous example with the addition of the `pullSecret` field: +``` +apiVersion: argocd-image-updater.argoproj.io/v1alpha1 +kind: ImageUpdater +metadata: + name: image-updater-pull-secret + namespace: NAMESPACE_NAME +spec: + applicationRefs: + - namePattern: image-updater-pull-secret + images: + - alias: utility-server + imageName: artifacts.developer.gov.bc.ca/plat-util-images/utility-server:latest + commonUpdateSettings: + pullSecret: pullsecret:NAMESPACE_NAME/PULL_SECRET_NAME + # Use 'digest' update strategy when tracking a tag like 'latest' + updateStrategy: digest + # For Kustomize apps, we need the following block + manifestTargets: + kustomize: + name: artifacts.developer.gov.bc.ca/plat-util-images/utility-server +``` + + + From fd3829133601012ed12488caf9bc4fb5ae190761 Mon Sep 17 00:00:00 2001 From: Ian Watts Date: Fri, 28 Aug 2026 16:12:41 -0700 Subject: [PATCH 3/4] Add clarity to image updater doc --- src/docs/automation-and-resiliency/argo-cd-image-updater.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/docs/automation-and-resiliency/argo-cd-image-updater.md b/src/docs/automation-and-resiliency/argo-cd-image-updater.md index 39fb0577..b9d2ca2b 100644 --- a/src/docs/automation-and-resiliency/argo-cd-image-updater.md +++ b/src/docs/automation-and-resiliency/argo-cd-image-updater.md @@ -76,7 +76,10 @@ spec: ``` ### Example 2 - Kustomize -In this example, a Kustomize app uses the 'latest' tag. Because the tag does not change, the image updater uses the SHA checksum to look for changes and will apply the checksum value as the image tag in your live deployment. +In this example, a Kustomize app uses the 'latest' tag. Because the tag itself does not change, the image updater identifies new images by reading the SHA checksum. When the checksum has changed, the image updater updates the image reference in the deployment to use the checksum in addition to the tag. This causes the deployment to recognize it as a different image and thus replace the existing pods with new ones running the new version of the image. For example: +``` +image: 'docker.io/nicolaka/netshoot:latest@sha256:b09d9b21381f47a79b3cbcb30da25266dc17186ea00ae65e99fdc51396f48e70' +``` Our Kustomize base deployment uses a standard image reference: ``` From e39db39ee645034ae91b53237395c59c30312fe8 Mon Sep 17 00:00:00 2001 From: Ian Watts Date: Mon, 31 Aug 2026 09:41:57 -0700 Subject: [PATCH 4/4] Update image updater doc --- .../argo-cd-image-updater.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/src/docs/automation-and-resiliency/argo-cd-image-updater.md b/src/docs/automation-and-resiliency/argo-cd-image-updater.md index b9d2ca2b..14f07698 100644 --- a/src/docs/automation-and-resiliency/argo-cd-image-updater.md +++ b/src/docs/automation-and-resiliency/argo-cd-image-updater.md @@ -32,10 +32,10 @@ For now, because the image updater controller has not been granted write access ## Update strategies Update strategies determine how Argo CD will look for new versions of an image. -* `semver` - Use semantic versioning constraints -* `newest-build` - Use the most recent image -* `digest` - Use the most recent version of a given tag by using the SHA digest -* `alphabetical` - Sort tags alphabetically and use the "highest" one +* `semver` - (Default) Update to semantic versions +* `newest-build` - Update to the most recently built image +* `digest` - Use the most recent pushed version of a given tag, such as "latest" +* `alphabetical` - Update according to lexical sort See the [Argo CD documentation](https://argocd-image-updater.readthedocs.io/en/stable/basics/update-strategies/) for more information. @@ -57,7 +57,7 @@ image: tag: "2.10.1" ``` -The following ImageUpdater uses a 'newest-build' strategy, but also adds an 'allowTags' field to limit updates to the `2.10.x` pattern, so as new patch versions of 2.10 are released, they will be automatically applied by Argo CD, but it will not be updated to 2.11 or higher. +The following ImageUpdater uses the **semver** update strategy. This is the default update strategy and it will use the highest tag that matches the given pattern, in this case any semver-style tag beginning with `2.` (`2.10.2`, `2.11.4`, etc.). ``` apiVersion: argocd-image-updater.argoproj.io/v1alpha1 kind: ImageUpdater @@ -66,13 +66,12 @@ metadata: namespace: NAMESPACE_NAME spec: applicationRefs: - - namePattern: image-updater-helm # the name of the argocd app + - namePattern: image-updater-helm # the name of the argocd app images: - - alias: caddy # a short alias for the image name - imageName: caddy # the full name of the image + - alias: caddy # a short alias for the image name + imageName: caddy:2.x # the full name of the image commonUpdateSettings: - updateStrategy: newest-build # Use the most recent matching build - allowTags: regexp:^2\.10\.[0-9]+$ # Only match tags like 2.10.x + updateStrategy: semver # Use the highest matching tag: `2.x` ``` ### Example 2 - Kustomize @@ -90,7 +89,7 @@ spec: - image: 'docker.io/nicolaka/netshoot:latest' ``` -Our ImageUpdater uses the 'digest' update strategy and we add an extra block for Kustomize: +Our ImageUpdater uses the **digest** update strategy and we add an extra block for Kustomize: ``` apiVersion: argocd-image-updater.argoproj.io/v1alpha1 kind: ImageUpdater