·

Kubernetes - Using a private registry, like Gitlab

Pull images from a private GitLab Container Registry in Kubernetes: docker-registry secret, imagePullSecrets, test pod and sharing the secret across namespaces.

First published on this blog on July 6, 2018, by Dimitri DO BAIRRO, and put back online in November 2026 as it was written. Package versions and commands date from 2018: check the current documentation before reusing them.

Introduction

This article shows how to use secrets to pull an image from a private Docker registry.

Description

Incredibly powerful, Kubernetes offer a simple way to manage your secrets and customize the default registry (Docker Hub).

In this example, we'll use the Gilab Container Registry service.

Let's go!

Create a file ~/.dockerconfig with your registry credentials on your local machine.

$ export DOCKER_REGISTRY_SERVER=https://registry.gitlab.com
$ export DOCKER_USER=user
$ export DOCKER_EMAIL=user@example.com
$ export DOCKER_PASSWORD=password

Export variables from~/.dockerconfig.

$ source ~/.dockerconfig

To verify the configuration.

$ printenv | grep DOCKER

You should have the same output:

DOCKER_REGISTRY_SERVER=https://registry.gitlab.com
DOCKER_USER=user
DOCKER_EMAIL=user@example.com
DOCKER_PASSWORD=password

Everything is ok, let's create Kubernetes gitlab-registry secret.

kubectl create secret docker-registry gitlab-registry \
--docker-server=$DOCKER_REGISTRY_SERVER \
--docker-username=$DOCKER_USER \
--docker-password=$DOCKER_PASSWORD \
--docker-email=$DOCKER_EMAIL

It's time to test it!

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: foo
spec:
  containers:
    - name: foo
      image: foo/your-gitlab-private-image:latest
      imagePullPolicy: Always
  imagePullSecrets:
    - name: gitlab-registry
EOF

To check if your private image has been pulled, your can:

$ kubectl describe po/foo | grep -i pull

Extra

To remove the created pod.

$ kubectl delete po/foo

To remove local Docker configuration.

# Remove environment variables file
$ rm ~/.dockerconfig

# Remove environment variables
$ unset DOCKER_REGISTRY_SERVER
$ unset DOCKER_USER
$ unset DOCKER_EMAIL
$ unset DOCKER_PASSWORD

To sharing the secret across multiple Kubernetes namespaces.

export NAMESPACE=your-namespace
kubectl get secret gitlab-registry -o yaml \
  | sed "s/default/$NAMESPACE/g" \
  | kubectl -n $NAMESPACE create -f -