Configuring images for update¶
Annotation format¶
You can specify one or more image(s) for each application that should be considered for updates. To specify those images, the following annotation is used:
argocd-image-updater.argoproj.io/image-list: <image_spec_list>
The <image_spec_list>
is a comma separated list of image specifications. Each
image specification is composed of mandatory and optional information, and is
used to specify the image, its version constraint and a few meta data.
An image specification could be formally described as:
[<alias_name>=]<image_path>[:<version_constraint>]
Specifying the fields denoted in square brackets is optional and can be left out.
Allowing an image for update¶
The most simple form of specifying an image allowed to update would be the following:
argocd-image-updater.argoproj.io/image-list: nginx
The above example would specify to update the image nginx
to it's most recent
version found in the container registry, without taking any version constraints
into consideration.
This is most likely not what you want, because you could pull in some breaking
changes when nginx
releases a new major version and the image gets updated.
So you can give a version constraint along with the image specification:
argocd-image-updater.argoproj.io/image-list: nginx:~1.26
The above example would allow the nginx
image to be updated to any patch
version within the 1.26
minor release.
More information on how to specify semantic version constraints can be found in the documentation of the Semver library we're using.
Note
If you use an
update strategy
other than semver
, the version_constraint
will not be have any effect
and all tags returned from the registry will be considered for update. If
you need to further restrict the list of tags to consider, see
filtering tags
below.
Assigning aliases to images¶
It's possible (and sometimes necessary) to assign an alias name to any given image. Alias names should consist of alphanumerical characters only, and must be unique within the same application. Re-using an alias name across different applications is allowed.
An alias name is assigned during image specification in the image-list
annotation, for example the following would assign the alias myalias
to the
image some/image
:
argocd-image-updater.argoproj.io/image-list: myalias=some/image
Assigning an alias name to an image is necessary in these scenarios:
-
If you want to use custom images with Kustomize. In this case, the name must match to what is defined in your Kustomize base.
-
If you need to specify the Helm parameters used for rendering the image name and version using Helm and the parameter names do not equal
image.name
andimage.tag
. In this case, the name is just symbolic. -
If you want to set custom options for a given image's update strategy, or require referencing unique pull secrets for each image
The alias you assign to any image will be reused as a key in the annotations
used to define further options, so a little care should be taken when defining
such a name. It's generally advised to use only alpha-numerical characters. The
character /
(forward-slash) can be used in the name, but must be referenced
as _
(underscore) in the annotation. This is a limit of Kubernetes. So for
example, if you assign the alias argoproj/argocd
to your image, the
appropriate key in the annotation would be referenced as argoproj_argocd
.
Update strategies¶
Argo CD Image Updater can update images according to the following strategies:
Strategy | Description |
---|---|
semver |
Update to the tag with the highest allowed semantic version |
latest |
Update to the tag with the most recent creation date |
name |
Update to the tag with the latest entry from an alphabetically sorted list |
You can define the update strategy for each image independently by setting the following annotation to an appropriate value:
argocd-image-updater.argoproj.io/<image_name>.update-strategy: <strategy>
If no update strategy is given, or an invalid value was used, the default
strategy semver
will be used.
Filtering tags¶
You can specify an expression that is matched against each tag returned from the registry. On a positive match, the tag will be included in the list of tags that will be considered to update the image to. If the expression does not match the tag, the tag will not be included in the list. This allows you to only consider tags that you are generally interested in.
You can define a tag filter by using the following annotation:
argocd-image-updater.argoproj.io/<image_name>.allow-tags: <match_func>
The following match functions are currently available:
Function | Description |
---|---|
regexp:<expression> |
Matches the tag name against the regular expression <expression> |
any |
Will match any tag |
If you specify an invalid match function, or the match function is misconfigured (i.e. an invalid regular expression is supplied), no tag will be matched at all to prevent considering (and possibly update to) the wrong tags by accident.
If the annotation is not specified, a match function any
will be used to match
the tag names, effectively performing no filtering at all.
Ignoring certain tags¶
If you want to ignore certain tags from the registry for any given image, you can define a comma separated list of glob-like patterns using the following annotation:
argocd-image-updater.argoproj.io/<image_name>.ignore-tags: <pattern1>[, <pattern2>, ...]
You can use glob patterns as described in this documentation
If you want to disable updating an image temporarily, without removing all of the configuration, you can do so by just ignoring all tags, effectively preventing the image updater to consider any of the tags returned from the registry:
argocd-image-updater.argoproj.io/<image_name>.ignore-tags: "*"
Please note that regular expressions are not supported to be used for patterns.
Specifying pull secrets¶
There are generally two ways on how to specify pull secrets for Argo CD Image Updater to use. Either you configure a secret reference globally for the container registry (as described here), or you can specify the pull secret to use for a given image using the annotation
argocd-image-updater.argoproj.io/<image_name>.pull-secret: <secret_ref>
A configuration for an image will override what is configured for the registry, for that certain image.
The secret_ref
can either be a reference to a secret or a reference to an
environment variable. If a secret is referenced, the secret must exist in the
cluster where Argo CD Image Updater is running in (or has access to).
Valid values for secret_ref
are:
-
secret:<namespace>/<secret_name>#<field>
- Use credentials stored in the fieldfield
from secretsecret_name
in namespacenamespace
. -
pullsecret:<namespace>/<secret_name>
- Use credentials stored in the secretsecret_name
in namespacenamespace
. The secret is treated as Docker pull secret, that is, it must have a valid Docker config in JSON format in the field.dockerconfigjson
. -
env:<variable_name>
- Use credentials supplied by the environment variable namedvariable_name
. This can be a variable that is i.e. bound from a secret within your pod spec.
In case of secret
or env
references, the data stored in the reference must
be in format <username>:<password>
Custom images with Kustomize¶
In Kustomize, if you want to use an image from another registry or a completely different image than what is specified in the manifests, you can give the image specification as follows:
<image_name>=<image_path>:<image_tag>
<image_name>
will be the original image name, as used in your manifests, and
<image_path>:<image_path>
will be the value used when rendering the
manifests.
Let's take Argo CD's Kustomize base as an example: The original image used by
Argo CD is argoproj/argocd
, pulled from the Docker Hub container registry. If
you are about to follow the latest builds, as published on the GitHub registry,
you could override the image specification in Kustomize as follows:
argoproj/argocd=docker.pkg.github.com/argoproj/argo-cd/argocd:1.7.0-a6399e59
Specifying Helm parameter names¶
In case of Helm applications which contain more than one image in the manifests
or use another set of parameters than image.name
and image.tag
to define
which image to render in the manifests, you need to set an <image_alias>
in the image specification to define an alias for that image, and then
use another set of annotations to specify the appropriate parameter names
that should get set if an image gets updated.
For example, if you have an image quay.io/dexidp/dex
that is configured in
your helm chart using the dex.image.name
and dex.image.tag
Helm parameters,
you can set the following annotations on your Application
resource so that
Argo CD Image Updater will know which Helm parameters to set:
argocd-image-updater.argoproj.io/image-list: dex=quay.io/dexidp/dex
argocd-image-updater.argoproj.io/dex.helm.image-name: dex.image.name
argocd-image-updater.argoproj.io/dex.helm.image-tag: dex.image.tag
The general syntax for the two Helm specific annotations is:
argocd-image-updater.argoproj.io/<image_alias>.helm.image-name: <name of helm parameter to set for the image name>
argocd-image-updater.argoproj.io/<image_alias>.helm.image-tag: <name of helm parameter to set for the image tag>
If the chart uses a parameter for the canonical name of the image (i.e. image name and tag combined), a third option can be used:
argocd-image-updater.argoproj.io/<image_alias>.helm.image-spec: <name of helm parameter to set for canonical name of image>
If the <image_alias>.helm.image-spec
annotation is set, the two other
annotations <image_alias>.helm.image-name
and <image_alias>.helm.image-tag
will be ignored.
Examples¶
Following an image's patch branch¶
Scenario: You have deployed image nginx:1.19.1
and want to make sure it's
always up-to-date to the latest patch level within the 1.19
branch.
Solution: Use standard semver
update strategy with a constraint on the
patch level (~
), i.e.
argocd-image-updater.argoproj.io/image-list: nginx:~1.19
Always deploy the latest build¶
Scenario: Your CI regularly pushes images built from the latest source, using some identifier (i.e. the hash of the Git commit) in the tag.
Solution:
-
Give your image a proper alias, i.e.
yourtool
and do not define a version constraint. -
Use
latest
as update strategy -
If you just want to consider a given set of tags, i.e.
v1.0.0-<hash>
, use aallow-tags
annotation.
Annotations might look like follows:
argocd-image-updater.argoproj.io/image-list: yourtool=yourorg/yourimage
argocd-image-updater.argoproj.io/yourtool.update-strategy: latest
argocd-image-updater.argoproj.io/yourtool.allow-tags: regexp:^v1.0.0-[0-9a-zA-Z]+$
Multiple images in the same Helm chart¶
Scenario: You want to update multiple images within the same Helm chart to their latest available version according to semver.
The Helm parameters to set the image version
are foo.image
and foo.tag
for the first image, and bar.image
and
bar.tag
for the second image. The image names are foo/bar
and bar/foo
for simplicity.
Solution:
-
Define an alias for both images, i.e.
fooalias
andbaralias
-
Set
helm.image-name
andhelm.image-tag
for both aliases to their appropriate values
Annotations might look like follows:
argocd-image-updater.argoproj.io/image-list: fooalias=foo/bar, baralias=bar/foo
argocd-image-updater.argoproj.io/fooalias.helm.image-name: foo.image
argocd-image-updater.argoproj.io/fooalias.helm.image-tag: foo.tag
argocd-image-updater.argoproj.io/baralias.helm.image-name: bar.image
argocd-image-updater.argoproj.io/baralias.helm.image-tag: bar.tag
Appendix¶
Available annotations¶
The following is a complete list of available annotations to control the
update strategy and set options for images. Please note, all annotations
must be prefixed with argocd-image-updater.argoproj.io
.
Annotation name | Default value | Description |
---|---|---|
image-list |
none | Comma separated list of images to consider for update |
<image_alias>.update-strategy |
semver |
The update strategy to be used for the image |
<image_alias>.allow-tags |
any | A function to match tag names from registry against to be considered for update |
<image_alias>.ignore-tags |
none | A comma-separated list of glob patterns that when match ignore a certain tag from the registry |
<image_alias>.pull-secret |
none | A reference to a secret to be used as registry credentials for this image |
<image_alias>.helm.image-spec |
none | Name of the Helm parameter to specify the canonical name of the image, i.e. holds image/name:1.0 . If this is set, other Helm parameter related options will be ignored. |
<image_alias>.helm.image-name |
image.name |
Name of the Helm parameter used for specifying the image name, i.e. holds image/name |
<image_alias>.helm.image-tag |
image.tag |
Name of the Helm parameter used for specifying the image tag, i.e. holds 1.0 |
<image_alias>.kustomize.image-name |
original name of image | Name of Kustomize image parameter to set during updates |