Mastering GitLab Container Registry with Buildx: Your Comprehensive Guide¶

Gulcan Topcu

Jan 20, 2024

10 min read

🏷️Tagged with:

In this article, we’ll guide you through the process of getting started with GitLab Container Registry using the powerful buildx tool. Follow the steps below to locate the container registry, authenticate securely, and build your Docker image.

Table of Contents¶

Locating Container Registry
Authenticating to the Registry
Tagging and Building the Image using Buildx

Locating Container Registry¶

Navigate to your project in GitLab.
Select the “Deploy” option from the project menu.
Click on “Container Registry.” You’ll be directed to a blank page with instructions.

Container Registry

Authenticating to the Registry¶

To securely authenticate with GitLab Container Registry, follow these steps:

docker login $CI_REGISTRY -u <username> -p <access_token>

dockerhub: https://index.docker.io/v1
gitlab ci: registry.gitlab.com

docker login registry.gitlab.com

Avoid using your password; instead, use a personal access token. Here’s how you can generate one:

Go to your GitLab profile.
Navigate to “Access Tokens” under “Edit Profile.”
Add a new token with a name of your choice.
Set the scope to read_registry (for pull access) and write_registry (for push rights).

After generating the token, remove the existing entry in $HOME/.docker/config.json related to GitLab:

{
    "auths": {
        "registry.gitlab.com": {}
    },
    "credsStore": "desktop.exe"
}

Authenticate again using your personal access token:

docker login registry.gitlab.com

Tagging and Building the Image using Buildx¶

Tagging the Image¶

Here is the structure of tagging an image to push to the registry:

tag=registry.gitlab.com/<gitlab-username>/<project-name>

Why Buildx?¶

GitLab recommends using buildx for building container images due to its enhanced features and capabilities compared to the traditional build command. You can read more on multi-platform images using buildx here. Let’s take a look at how to properly tag the image for pushing.

What is a Builder?¶

A builder is a tool that uses BuildKit, a build engine, to carry out your builds. BuildKit interprets the instructions in a Dockerfile to generate a container image or other outputs.

You can interact with the builders using the docker buildx ls command. The asterisk (*) marks the selected platforms for the image:

Now, let’s clarify the difference between docker build and docker buildx build:

docker build: The classic Docker build command for building images, suitable for single-platform builds.
docker buildx build: An advanced version using BuildKit, offering extra features like multi-arch builds and advanced options for a more flexible and capable building process.

BuildKit is the underlying build engine that powers these builders. It efficiently processes the build steps in a Dockerfile to produce the desired container image or other artifacts.

Building the Image¶

Change the directory to your application code where the Dockerfile resides and create a builder instance:

Change Directory

export DOCKER_IMAGE_NAME=registry.gitlab.com/colossus06/cka-ckad-study-group-2024
docker buildx ls
docker buildx create --name mybuilder --use
docker buildx inspect --bootstrap

We can see that the default builder is mybuilder:

Automatic Load with Buildx

It’s time to start a build from our builder we created in the previous step. We will use --push to automatically push our multi-platform build result to GitLab Container Registry, and BuildKit will assemble the image manifest for the target architectures.

cd <Dockerfile-directory>
docker buildx build --load --platform linux/amd64 -t $DOCKER_IMAGE_NAME:gitlab .

Now we can see that our builder is registered:

Display our image:

docker image inspect $DOCKER_IMAGE_NAME:gitlab | grep Architecture

Expected output:

Displaying the Image on GitLab Registry

Run the following command to push your image to the GitLab Container Registry:

docker push $DOCKER_IMAGE_NAME:gitlab

Display your registry by navigating to the following URL:

https://gitlab.com/<gitlab-username>/<repo-name>/container_registry/ or project/deploy/container_registry

Editing the Builder Instance

If you wanr to delete the builder instance, run the following:

docker buildx rm mybuilder

Creating a new builder:

docker buildx create --use --name voting-app
docker buildx build --load --platform linux/amd64 -t $DOCKER_IMAGE_NAME:gitlab .

Let’s put together all the commands we used:

docker buildx rm mybuilder
docker buildx ls
docker buildx create --use --name voting-app
docker buildx inspect --bootstrap
docker buildx build --load --platform linux/amd64 -t $DOCKER_IMAGE_NAME:gitlab .
docker push $DOCKER_IMAGE_NAME:gitlab

Final Words¶

In this hands-on blog post, we have authenticated, built, and pushed our Docker image to GitLab Container Registry using buildx.

Challenges:

Here are two challenges for you.

Can you build and push a multi-arch image to GitLab and Docker Hub?

Try also authenticating to Docker Hub, build a multi-arch image, and push it to the Docker Hub Container Registry:

docker login -u <dockerhub-username> -p <password>
docker buildx build --push --platform linux/amd64,linux/arm64 -t <dockerhub-username>/multiarch:v1 .

Can you save some space by keeping only 5 tags per image?

References¶

Happy building!

👉 For a wealth of knowledge, check our blog archives. Happy reading! 📚✨