Configuration of Container Registries¶

Supported registries¶

Argo CD Image Updater comes with out of the box support for most container registries that implement the Docker registry v2 API.

It has been successfully tested against the following popular registries:

Docker Hub (docker.io)
Docker Registry v2 reference implementation (on-premise)
Red Hat Quay (quay.io and on-premise)
JFrog Artifactory (jfrog.io and on-premise)
GitHub Container Registry (ghcr.io)
GitHub Packages Registry (docker.pkg.github.com)
GitLab Container Registry (registry.gitlab.com)
Google Container Registry (gcr.io)

Chances are, that it will work out of the box for other registries as well.

If you have a registry that doesn't work with Argo CD Image Updater, please let us know.

When to configure a custom registry?¶

Generally, there is no need to configure custom registries. Image Updater will infer the registry from the image slug, e.g. if you are using an image that is defined as ghcr.io/somerepo/someimage, Image Updater will infer the registry from the ghcr.io prefix and use the Docker registry at https://ghcr.io/v2.

However, there may be reasons when you need to configure a custom registry, or adapt the default settings to your requirements:

Your registry uses a self-signed (or not publicly known) TLS certificate, and you want to either turn off TLS certificate verification or provide a custom CA certificate to be used for verification
Your registry has its API endpoint at a different location. One notable example is Docker Hub, which uses docker.io as image prefix but the registry is at registry-1.docker.io. However, this quirk related to Docker Hub has been accounted for in Argo CD Image Updater, so you won't have to configure Docker Hub as a custom registry.
You want to use a certain registry with deviations from the default settings, such as setting a custom rate limit, or configuring global credentials for accessing that registry.
Your cluster's container engine is set up to use a different registry than docker.io as the default so that it does not pull images from Docker Hub when no prefix is specified, but e.g. from an on-premise registry.

Can I use my registry without further configuration?¶

There is an easy way to find out by running the argocd-image-updater CLI in test mode. You can run the CLI either from your workstation (if the registry is reachable from there) or from the pod deployed to your cluster.

Assuming you have an image at myregistry.com/somerepo/someimage, and you want to find out if Argo CD Image Updater could possibly connect to that specific registry at myregistry.com and gather information about the image, run the following command:

argocd-image-updater test myregistry.com/somerepo/someimage

You may also want to pass some options to that command to set the appropriate update strategy or credentials to access the registry.

The argocd-image-updater test command won't perform any modifications to your cluster or your workloads.

Configuring custom registries¶

Configuration format¶

Registries are configured in a configuration file in YAML syntax. That YAML must have a top level key of registries, which holds a list of registries to be configured. Each item in the list represents a single registry. You can add as many registries as you like.

The following properties can be set to configure a registry. Most of these properties are optional, unless otherwise stated:

name (mandatory) - The symbolic name for your registry. Can be any string, used only for informational purposes.

Default value: none

Example value: My Custom Registry
prefix - (mandatory) The lookup prefix for this registry. Must match a DNS name, and must be unique in the configuration.

Default value: none

Example value: docker.io
api_url - The URL to the API of the Docker registry. Must be a HTTP or HTTPS URL.

Default value: none

Example value: https://registry-1.docker.io
defaultns- Some registries (notably Docker Hub) have a default namespace, which can be specified here.

Default value: none

Example value: library
default - If set to true, use this registry as the default registry.

Default value: false

Example value: true
credentials - A string describing the credential source to use when accessing this registry and no other credentials are configured on the image level. For more information, refer to Authenticating to container registries.

Default value: none

Example value: pullsecret:argocd/dockerhub-secret
credsexpire - Whether and when credentials should expire and be re-fetched. Must be specified as Duration value, with an integer value and a unit suffix, i.e. s for seconds, m for minutes, or h for hours.

Default value: none (no expiry)

Example value: 5h
insecure - Whether to turn off verification of the registry's TLS certificate. As the name implies, it's insecure and should not be used in production environments

Default value: false

Example value: true
limit - The rate limit (max. number of requests per second) to use for this registry, specified as integer.

Default value: 20

Example value: 100

The following is an example that configures two registries.

export REGISTRY_SECRET="login:password"

registries:
- name: Docker Hub
  prefix: docker.io
  api_url: https://registry-1.docker.io
  credentials: secret:foo/bar#creds
  defaultns: library
  default: true
- name: RedHat Quay
  api_url: https://quay.io
  prefix: quay.io
  insecure: yes
  credentials: env:REGISTRY_SECRET

When running Argo CD Image Updater from the command line (e.g. using the test command), the path to this YAML file can be specified with the command line parameter --registries-conf-path <path>.

If you are running Argo CD Image Updater as a Kubernetes workload, you will need to tie that up in the argocd-image-updater-config ConfigMap, as a multi line string under the registries.conf key, e.g.:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-image-updater-config
data:
  registries.conf: |
    registries:
    - name: Docker Hub
      prefix: docker.io
      api_url: https://registry-1.docker.io
      credentials: secret:foo/bar#creds
      defaultns: library
      default: true
    - name: RedHat Quay
      api_url: https://quay.io
      prefix: quay.io
      insecure: yes
      credentials: env:REGISTRY_SECRET

Note

Argo CD Image Updater pod must be restarted for changes to the registries configuration to take effect. There are plans to change this behaviour so that changes will be reload automatically in a future release.

Configuring a default registry¶

Warning

When you change the default registry for Argo CD Image Updater, make sure it matches the default registry set up in your cluster. If the default registries mismatch between the Argo CD Image Updater and your cluster, it is going to break your workloads.

Most container engines will follow Docker's approach and use Docker Hub as the default registry when no registry is specified in the image's reference. For example, in most environments, the two image references argoproj/argocd and docker.io/argoproj/argocd are semantically the same, and would refer to the same image stored in Docker Hub's registry. You can configure the default registry if your cluster's container engine is configured to use a different default registry than docker.io, which is the default for Argo CD Image Updater in the standard configuration.

In order to set another registry to be used as default, you will have to set the registry's default property to true, e.g. the following:

registries:
- name: RedHat Quay
  api_url: https://quay.io
  prefix: quay.io
  default: true

would make quay.io the default registry, so argoproj/argocd would become synonymous to quay.io/argoproj/argocd.

Please note that you can only configure one registry as the default registry. If you set default to true for more than one registry's configuration, Argo CD Image Updater will not load that configuration.

Also note, as stated previously, Docker Hub (i.e. docker.io) is the default used by Image Updater without any additional configuration.

Configuring a registry's default namespace¶

Some registries provide a default namespace, that is, a namespace that doesn't have to be specified in the image's slug. A good example for that is the implicit library namespace on Docker Hub, that allows you to pull an image from that library by just specifying the name of the image. Consider e.g. the command docker pull nginx, which will pull from docker.io/library/nginx.

If your registry supports a default namespace and you would like this to be used with Image Updater, you can configure this by setting the defaultns property of the registry to the name of the namespace to use as the default.

The canonical example for Docker Hub would be:

registries:
- name: Docker Hub
  api_url: https://registry-1.docker.io
  prefix: docker.io
  defaultns: library

Configuring a request rate limit for your registry¶

Some registries might be picky about how many requests per time they let you perform from a client's connection. In order to play nicely, and to prevent Image Updater from triggering rate limit failures on your registry, you can set a rate limit for each of the registries you are using.

The rate limit can currently be configured as requests per second allowed and is specified via the limit configuration property. It takes an integer as argument.

For example, the following connection would cap requests to quay.io to 10 per second:

registries:
- name: RedHat Quay
  api_url: https://quay.io
  prefix: quay.io
  limit: 10

Please note that the limit considers all HTTP requests sent to the registry. For inspecting a single tag of any given image, Image Updater may require performing multiple requests to the registry.

The default for all registries is 20 requests per second. If your registry doesn't impose limits upon you, raising this limit may significantly speed up Argo CD Image Updater. But please be considerate and careful before you increase the limit.

Configuring default credentials for container registries¶

If you require authentication for accessing your registry, you can configure a set of default credentials to use. If you have configured the credentials on the registry level, it will be reused for any image processed from that registry, unless an image configuration overrides it. A benefit of having the credentials configured at the registry level is

Registry credentials are configured using the credentials property of a registry's configuration.

Credentials caching¶

By default, credentials specified in registry configuration are read once on startup and then cached until argocd-image-updater is restarted. There are two strategies to overcome this:

Use per-image credentials in annotations - credentials will be read from their source every time an image update cycle is performed, and your credentials will always be up-to-date (i.e. if you update a secret).
Specify credential expiry time in the registry configuration - if set, the registry credentials will have a defined lifetime, and will be re-read from the source after expiration. This can be especially useful if you generate credentials with a script which returns a token with a limited lifetime, i.e. for getting EKS credentials from the aws CLI. For example, if the token has a lifetime of 12 hours, you can set credsexpire: 12h and Argo CD Image Updater will get a new token after 12 hours.