Deploying container images from a private GitLab registry

Alan Christie 2020-07-26

Containers Kubernetes

In this article we’ll see how to deploy container images from a GitLab private registry into Kubernetes.

Public container images, in registries like Docker Hub, can be deployed easily without needing to provide any credentials. Kubernetes Deployments (and other objects like StatefulSets) simply need the image, i.e. informaticsmatters/neo4j:3.5.20. However, images resident on a private registry will require you to deploy an ImagePullSecret that Kubernetes uses to pull the image.

Kubernetes documentation describes such secrets with a section explaining how they can be created from the command-line.

Here we provide a brief cheat-sheet that explains how to create a pull-secret using GitLab and then use that in a Deployment.

Firstly, we assume that you’ve created a container image in your GitLab project and loaded into the free registry that is part of your project.

Create a Deploy Token

1. Login to GitLab and navigate to your project
2. Navigate to Settings -> Repository and expand the Deploy Tokens section

3. In the Add a deploy token of the Deploy Tokens section: -

   1. Provide a Name. This is symbolic and is just for reference
   2. Provide an Expires at value if you want the token to have a life-span
   3. Provide a Username. This, along with the generated token, will be used in our secret.
   4. Click the read_registry scope
   5. Click Create deploy token

The deploy token is only visible at this stage so take a copy of the Username and the Token, which is essentially the registry access password.

Create a pull-secret

Armed with the Username and Token from above you can create a pull-secret string with the following shell commands: -

gitlab_user=<Username>
gitlab_token=<Token>
gitlab_pull_secret=$(echo -n "{\"auths\":{\"registry.gitlab.com\":{\"auth\":\"`echo -n "$gitlab_user:$gitlab_token"|base64`\"}}}"|base64)

The resultant base-64 string (the gitlab_pull_secret value) can now be used in a Kubernetes Secret as the .dockerconfigjson value. The YAML example below is taken from an Ansible template, where the variable gitlab_pull_secret is known.

---
kind: Secret
apiVersion: v1
metadata:
  name: gitlab-pull-secret
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <the pull secret Base64 string>

Using the pull-secret

To deploy a container image using the pull-secret you simply have to refer to it from your Deployment object. The following fragment from a Deployment illustrates the salient parts of the object that you need to provide.

You’ll see that the container image is based on the name of the registry (i.e. registry.gitlab.com), your GitLab organisation (or namespace) and project.

---
kind: Deployment
apiVersion: apps/v1
metadata:
  name: gitlab-image
spec:
 [...]
  template:
    [...]
    spec:
      containers:
      - name: website
        image: registry.gitlab.com/my-namespace/my-project:latest
        imagePullPolicy: IfNotPresent
      imagePullSecrets:
      - name: gitlab-pull-secret