Uncategorized Documents

Using authentication for a registry

Many container image registries require authentication. This document explains how to configure container management software like Docker, Kubernetes, rkt, and Mesos to authenticate with and pull containers from registries like Quay and Docker Hub.

Using a Quay robot for registry auth

The recommended way to authenticate container manager software with quay.io is via a Quay Robot. The robot account acts as an authentication token with some nice features, including:

Readymade repository authentication configuration files

Credentials are limited to specific repositories

Choose from read, write, or admin privileges

Token regeneration

Quay robots provide config files for Kubernetes, Docker, Mesos, and rkt, along with intructions for using each. Find this information in the Robot Accounts tab under your Quay user settings. For more information, see the Quay robot documentation.

Manual registry auth setup

If you are using a registry other than Quay (e.g., Docker Hub, Docker Store, etc) you will need to manually configure your credentials with your container-runtime or orchestration tool.

Docker

The Docker client uses an interactive command to authenticate with a centralized service.

On Container Linux, this process can be automated by writing out the config file during system provisioning with a Container Linux Config. Since the config is written to the core user's home directory, ensure that your systemd units run as that user, by adding, e.g., User=core.

Docker also offers the ability to configure a credentials store, such as your operating system's keychain. This is outlined in the Docker login documentation.

Copying the config file with a Container Linux Config

Container Linux Configs can be used to provision a Container Linux node on first boot. Here we will use it to copy registry authentication config files to their appropriate destination on disk. This provides immediate access to your private Docker Hub and Quay image repositories without the need for manual intervention. The same Container Linux Config file can be used to copy registry auth configs onto an entire cluster of Container Linux nodes.

Here is an example of using a Container Linux Config to write the .docker/config.json registry auth configuration file mentioned above to the appropriate path on the Container Linux node:

This is the human-readable config file. This should not be immediately passed to Container Linux. Learn more.

# This config is meant to be consumed by the config transpiler, which will# generate the corresponding Ignition config. Do not pass this config directly# to instances of Container Linux.storage:files:-path:/home/core/.docker/config.jsonfilesystem:rootmode:0644contents:inline:|{"auths": {"quay.io": {"auth": "AbCdEfGhIj","email": "your.email@example.com"}}}

This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.

This is the human-readable config file. This should not be immediately passed to Container Linux. Learn more.

# This config is meant to be consumed by the config transpiler, which will# generate the corresponding Ignition config. Do not pass this config directly# to instances of Container Linux.storage:files:-path:/home/core/.docker/config.jsonfilesystem:rootmode:0644contents:remote:url:http://internal.infra.example.com/cluster-docker-config.jsonverification:hash:function:sha512sum:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.