Private registries authentication

As the source for install or upgrade can be an OCI image and sometimes those are behind a private container registry, Kairos implements the default basic authentication used by docker for private registries.

To install/upgrade with a container image behind a registry with authentication, Kairos reads the following files in order to find about registry auth:

• ${XDG_CONFIG_HOME}/.docker/config.json
• If set, DOCKER_CONFIG environment variable which points to a directory as per the docs.
• ${XDG_RUNTIME_DIR}/containers/auth.json for podman

Note

If you are using sudo to perform the upgrade, you have a couple of options:

• You can create the file /root/.docker/config.json with your credentials.
• You can use sudo --preserve-env to give sudo access to the relevant environment variables.

See the login docs for docker or the login docs for podman for more information.

You can also just generate that file yourself with the proper auth parameters like so:

{
	"auths": {
		"registry.example.com": {
			"auth": "a2Fpcm9zOmh1bnRlcjIK"
		}
	}
}

The auths map has an entry per registry, and the auth field contains your username and password encoded as HTTP 'Basic' Auth.

NOTE: This means that your credentials are stored in plaintext. Have a look at the docker docs for the credentials-store

Insecure registries

The source for an install or upgrade can be an OCI image. If the registry is served over plain HTTP, or presents an untrusted or self-signed TLS certificate, pass the --allow-insecure-registries flag to kairos-agent:

# Upgrade from an image on a plain-HTTP or self-signed-cert registry
kairos-agent upgrade --source oci:my-registry.internal:5000/kairos/ubuntu:24.04 --allow-insecure-registries

# Install from such a registry
kairos-agent install --allow-insecure-registries

You can also set it in the cloud config, under install for installs and under upgrade for upgrades:

#cloud-config
install:
  allow-insecure-registries: true
upgrade:
  allow-insecure-registries: true

caution

Disabling TLS verification removes protection against man-in-the-middle attacks. Use it only in controlled environments (such as a local registry you operate), not against public registries.