Skip to content

Authentication in Argo CD Image Updater

There are several scenarios where Argo CD Image Updater needs to authenticate to external systems in order to fulfill its duties.

Authentication to Kubernetes

If you are running Argo CD Image Updater as a Kubernetes workload, 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-controller, 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 to the argocd namespace, no further configuration has to be 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 namespace.

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.

You can read more about configuration credentials at the registry level and configuration credentials at the image level for more details on how to configure either mechanisms.

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 .data 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:

pullsecret:<namespace>/<secret_name>

Where <namespace> is the namespace the secret resides in, and <secret_name> 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 argocd:

kubectl create -n argocd secret docker-registry dockerhub-secret \
  --docker-username someuser \
  --docker-password s0m3p4ssw0rd \
  --docker-server "https://registry-1.docker.io"

This secret could then be referred to as

pullsecret:argocd/dockerhub-secret

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 .data section, but credentials must be stored in the format <username>:<password>.

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:

secret:<namespace>/<secret_name>#<field_name>

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

secret:argocd/some-secret#creds

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 argocd-image-updater pod.

To retrieve credentials from an environment variable, you must specify the name of the environment variable as follows:

env:<name_of_environment_variable>

The credentials passed via environment variables must be specified in the format <username>:<password>, e.g. to store credentials in an environment variable named DOCKER_HUB_CREDS:

DOCKER_HUB_CREDS=someuser:s0m3p4ssw0rd

And then, to use this environment variable, reference it as

env:DOCKER_HUB_CREDS

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:

ext:<full_path_to_script>

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 configmap, or use an init container to copy it. Make sure that the script is executable.

For example, if above script would exist at /usr/local/bin/creds.sh, it would be referenced as

ext:/usr/local/bin/creds.sh

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 .dockerconfigjson field which holds a Docker client configuration with auth information in JSON format. This kind of secret is specified using the notation pullsecret:<namespace>/<secret_name>

  • 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 secret:<namespace>/<secret_name>#<field_in_secret>

  • An environment variable which holds the credentials in the format <username>:<password>. This kind of secret is specified using the notation env:<env_var_name>.

  • 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 +x bit set). You can add scripts to argocd-image-updater by using an init container.