How to pull an image from Gitlab container registry on Kubernetes

Gitlab container registry is extremely useful, especially if you are using Gitlab CI/CD to build and deploy your images and containers.

In this post we are going to walk though the steps to be completed in order to securely store and use the credentials necessary for Kubernetes to pull an image from the Gitlab container registry.

For the purpose of keeping this brief, we will assume that the image is already being hosted in the Gitlab container registry of the project.

Create a gitlab access token in Project > Settings > Access Tokens
1. Select read_registry
2. Save the project access token
Create a secret with auth credentials to be used wit Gitlab Container Registry
```
kubectl create secret docker-registry regcred \
	--docker-server=registry.gitlab.com \
	--docker-username=project_{PROJECT_ID}_bot \
	--docker-password=**THETOKEN**
```
*_ You can get the PROJECT_ID value from the project general settings. More details about the access token here._

Deploy the pod, and make sure your YAML file includes

spec:
	containers:
	    image: registry.gitlab.com/{GROUP_NAME}/{PROJECT_NAME}:{TAG}
			...
	imagePullSecrets:
	  - name: regcred
		...

Debugging `ErrImagePull`

Our pod.yaml file should contain something like the following:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
  - name: my-app
    image: registry.gitlab.com/{GROUP_NAME}/{PROJECT_NAME}:{TAG}
    ...
  imagePullSecrets:
  - name: regcred
	...

This means that the pod will pull the image located in the registry with the url registry.gitlab.com/{GROUP_NAME}/{PROJECT_NAME}:{TAG} and it'll use the credentials stored in the secret regcred to get the authorization to pull that image.

To create the pod we will run something like kubectl apply -f pod.yaml. You may add a particular namespace, but for the purpose of this example that's not necessary and kubectl will deploy the pod in the default namespace.

Now, if you check if your pod is running, you'll see the following message

NAME         READY   STATUS             RESTARTS   AGE
my-app       0/1     ImagePullBackOff   0          92s

And if we run kubectl describe pod my-app in the chain of events we will see

Events:
  Type     Reason          Age                From               Message
  ----     ------          ----               ----               -------
  ...
  Normal   BackOff         31s (x6 over 54s)  kubelet            Back-off pulling image "registry.gitlab.com/dumpk/my-app"
  Warning  Failed          31s (x6 over 54s)  kubelet            Error: ImagePullBackOff
  Normal   Pulling         17s (x3 over 57s)  kubelet            Pulling image "registry.gitlab.com/dumpk/my-app"
  Warning  Failed          16s (x3 over 56s)  kubelet            Failed to pull image "registry.gitlab.com/dumpk/my-app": rpc error: code = Unknown desc = Error response from daemon: Get https://registry.gitlab.com/v2/dumpk/my-app/manifests/latest: denied: access forbidden
  Warning  Failed          16s (x3 over 56s)  kubelet            Error: ErrImagePull

This means that there's something wrong with your credentials.

The URL to the image could be wrong
The credentials might be invalid
The image might not exist

For more information about Project Access Tokens click here

Debugging ErrImagePull

Debugging `ErrImagePull`