Authentication in Argo CD Image Updater¶
There are several scenarios where Argo CD Image Updater needs to authenticate to external systems in order to fulfil its duties.
Authentication to Kubernetes¶
If you are running Argo CD Image Updater as a Kubernetes workload in the
kubernetes API access mode (which is the default), it uses the token of a
ServiceAccount mounted to its pod to authenticate at the Kubernetes API.
The name of this ServiceAccount is
argocd-image-updater, and it gets
created through the installation manifests in the installation namespace.
The ServiceAccount is accompanied with an appropriate Kubernetes RBAC
Role that holds the required permissions, and a RoleBinding to bind the
Role to the ServiceAccount.
In the default installation scenario, i.e. Argo CD Image Updater installed
argocd namespace, no further configuration has to done in order
for Argo CD Image Updater to access the Kubernetes API. If your Argo CD
installation is in a different namespace than
argocd, you would have
to adapt the RoleBinding to bind to the ServiceAccount in the correct
Authentication to Argo CD¶
If you are using Argo CD Image Updater to connect to Argo CD via its API, you will need to create credentials in Argo CD and provide them to the Image Updater.
This usually involves the following steps:
- Create a local user with
apiKeycapabilities in Argo CD
- Generate an authentication token for that user
- Create appropriate RBAC permissions for that user in Argo CD
- Configure Argo CD Image Updater to connect to the Argo CD API endpoint instead of the Kubernetes API
- Configure Argo CD Image Updater to use the credentials created in steps 1 and 2 for authenticating at the Argo CD API
A complete walk-through can be found in the installation guide.
Authentication to container registries¶
If you are using private registries, or private repositories on public registries, chances are that you will need to have Argo CD Image Updater use credentials to access the registry.
Credentials can be configured either on a per registry basis or on a per image basis. You can also use a mixed setup where credentials are configured in both ways.
If credentials are configured on a per registry basis, all requests to that registry will use these credentials, without requiring any further configuration. Also, credentials configured for a registry will be cached for a configurable time and don't have to be re-read for every authentication requests. This can be useful especially for situations where you use tokens with a limited life time that are generated externally, and don't want to regenerate the token for each request.
However, you can override the credentials used for authentication to the same registry on a per image basis, e.g. if you use repositories on the registry that require a different set of credentials.
Types of supported credential sources¶
Argo CD Image Updater can source credentials for accessing registries using the following mechanisms:
Secrets stored in Kubernetes. Argo CD Image Updater can either use a typical Docker pull secret, or a custom secret with credentials in a certain format.
An environment variable available to Argo CD Image Updater (for example, an environment variable mounted to the pod from a secret)
A script that, when executed, outputs the credentials to stdout.
The following sections describe the configuration format to be used for the different types of credential sources.
Using a pull secret¶
A pull secret is a secret with a well-defined format, that can also be used by Kubernetes' container engine to pull container images from registries.
These secrets typically have a field
.dockerconfigjson in the
section, which holds a JSON string with the appropriate credentials.
In its default configuration, Argo CD Image Updater can only read secrets from the same namespace where it is installed to.
Pull secrets can be referenced as follows in credentials configuration:
<namespace> is the namespace the secret resides in, and
is the name of the Secret resource.
You can create a pull secret by using
kubectl. The following command would
create a pull secret for Docker Hub named
dockerhub-secret in the namespace
kubectl create -n argocd secret docker-registry dockerhub-secret \ --docker-username someuser \ --docker-password s0m3p4ssw0rd \ --docker-registry "https://registry-1.docker.io"
This secret could then be referred to as
Using a generic secret¶
Argo CD Image Updater can also retrieve credentials from a field in a generic Secret. This may be useful if you have similar credentials for a different set of registries, and don't want to maintain a unique pull-secret for each registry.
The credentials can be stored in any field of the Secret's
but credentials must be stored in the format
To retrieve the credentials from a generic secret, you must specify the field name along with the namespace and name of the secret like follows:
E.g. if you have stored your credentials in the field
creds in the secret
some-secret in the namespace
argocd, you would refer to it as
Using an environment variable¶
Argo CD Image Updater can read credentials from an environment variable. This
can be useful for testing purposes (e.g. when using the command
argocd-image-updater test to test access to a registry), or if you have the
environment variable to use mounted from a secret to the
To retrieve credentials from an environment variable, you must specify the name of the environment variable as follows:
The credentials passed via environment variables must be specified in the format
<username>:<password>, e.g. to store credentials in an environment variable
And then, to use this environment variable, reference it as
Using a script to generate credentials¶
Argo CD Image Updater supports using credentials that are generated by an external script. In order to retrieve the credentials, Argo CD Image Updater will execute a user configured script or executable, and parse its output.
Having a script generate the credentials can be useful if your registry does require a short-lived token for authentication which is issued by a third party system, possibly with this third party system requiring a different set of credentials. A prominent example would be ECR on aws.
Referencing a script used to output the credentials is done as follows:
When executing the script, Argo CD Image Updater does not pass any arguments to it.
The executed script is expected to output exactly one line to stdout, which
holds the credentials used for accessing the registry in the format
<username>:<password>. Please note that the output should contain a newline
character. For example, the most simple form of such a script would be:
#!/bin/sh echo "someuser:s0mep4ssw0rd"
When executing on Kubernetes, the script to be executed must exist in the Image Updater container's file system. You can either mount the script from a config map, or use an init container to copy it. Make sure that the script is executable.
For example, if above script would exist at
would be referenced as
Please keep in mind that executing scripts to retrieve credentials can become expensive. If possible, use this method only on a per-registry level with proper caching. Read more about this in the Registry configuration section of the docs.
A typical pull secret, i.e. a secret containing a
.dockerconfigjsonfield which holds a Docker client configuration with auth information in JSON format. This kind of secret is specified using the notation
A custom secret, which has the credentials stored in a configurable field in the format
<username>:<password>. This kind of secret is specified using the notation
An environment variable which holds the credentials in the format
<username>:<password>. This kind of secret is specified using the notation
A script that outputs credentials on a single line to stdout, in the format
<username:password>. This can be used to support external authentication mechanisms. You can specify this kind of secret in the notation
ext:/path/to/script. Please note that the script must be referenced as absolute path, and must be executable (i.e. have the
+xbit set). You can add scripts to
argocd-image-updaterby using an init container.