Configuring Image Registries
Every container run by the Container Service must start from an image. The container is essentially a "running" version of the image. The image consists of layers of files that must be present on the node where the container will run. If the image is not present when you initiate a container launch, the compute backend will attempt to pull the image from some registry. By default, images are pulled from Docker Hub, which requires no authentication. For some registries and some images, the request to pull an image must be authenticated. The credentials for pulling images can be stored within XNAT and retrieved at the time an image needs to be pulled.
At time of writing we only support registry credentials for Docker and Docker Swarm backends; we do not support configuring registry credentials within XNAT for Kubernetes backends. In Kubernetes mode the registry credentials must be configured within Kubernetes itself. For more information, see the Configuring Registry Credentials in Kubernetes section below.
The Image Registries can be configured in the Container Service admin interface (Administer > Plugin Settings > Container Service > Compute Backend) in the Image Hosts table.
Add a new Registry by clicking the "New Image Host" button.
Setting | Description |
|---|---|
Image Host Name | A label for the image host |
URL | The URL for the image host, such as gcr.io |
Username | Your username on the image host |
Access Token | An access token for the image host (if the image host supports them) or your account password. See Docker Hub's Access tokens documentation. |
Set Default Hub? | Should this be used as the default when pulling images and launching containers? Default: NO |
Configuring Registry Credentials in Kubernetes
If you have configured your Kubernetes cluster with a Namespace and a ServiceAccount dedicated to the Container Service, then configuring your Kubernetes to pull authenticated images should be easy. You can follow the Kubernetes documentation to Add ImagePullSecrets to a service account. We will make one small adjustment to the instructions, so I will reproduce the steps here.
First you make a Secret containing the registry credentials. (In the example this is called myregistrykey but it can be named whatever you like.) The Secret must be created by an account with the proper permissions to create Secrets, which is likely an admin user account; the service account that you created for the Container Service does not have permission to create Secrets. Also the Secret must be created within the Namespace where you run your containers.
kubectl create secret docker-registry myregistrykey \
--namespace <namespace> \
--docker-server=<registry url> \
--docker-username=<registry user username> \
--docker-password=<registry user password> \
--docker-email=<registry user email>
Fill in the placeholders in the angle brackets < > with the real values.
Next, run this command to configure the default service account in the namespace to use this Secret when pulling images.
kubectl patch serviceaccount default --namespace <namespace> -p '{"imagePullSecrets": [{"name": "myregistrykey"}]}'
Replace <namespace> with your namespace and myregistrykey with whatever registry name you used when creating the Secret.
Note that we added the imagePullSecrets to the default service account. This is not the same service account that we recommended you create for the Container Service itself. That service account is used only for authenticating the communication from the Container Service to the cluster and controlling the Container Service's access to cluster resources. However, all the Jobs, Pods, and containers launched by the Container Service will run as the default service account, so this is the account that should have access to the registry credentials secret for pulling images.
Those two steps should enable all Pods launched by the Container Service to pull images with authentication.