GitLab Container Registry

[This is part 4/8 on GitLab Continuous Integration series]

The GitLab Docker Container Registry was introduced in 2016 (version 8.8) when it was integrated into GitLab to:

• Allow that every GitLab project can have its own secure and private Docker Registry space to store its Docker images so you don’t need to set up and administer yet another service, or use a public registry.
• If you set the URL & Port in the configuration file and Docker is installed, GitLab becomes responsible for running the Docker registry and ensuring that it’s accessible to the user.

According to the release announcement it provides the following advantages:

• User authentication is from GitLab itself, so all the user and group definitions are respected.
• There’s no need to create repositories in the registry; the project is already defined in GitLab.
• Projects have a new tab, ‘Container Registry’, which lists all images related to the project.
• Every project can have an image repository, but this can be turned off per-project.
• Developers can easily upload and download images from GitLab CI.
• There’s no need to download or install additional software.

---

I. Enable the GitLab Container Registry

We are setting an insecure Registry in our local GitLab server that will be accessible over HTTP.

A warning is given in the admin guide (several times): “The container registry works under HTTPS by default. Using HTTP is possible but not recommended”. The following procedure configures Docker to entirely disregard security for your registry. This is very insecure as it exposes your registry to trivial man-in-the-middle (MITM) attacks. Only use this solution for isolated testing or in a tightly controlled, air-gapped environment.”

1. Enlist the registry's machine in your network.

• The default registry hostname is registry.example.com. Edit each computer’s ‘/etc/hosts’ file to add the new IP and FQDN

$ sudo vi /etc/hosts
# Add
192.168.1.221   registry.example.com

2. Configure the Docker daemon to accept the insecure protocol.

• Edit the daemon.json file, whose default location is /etc/docker/daemon.json on Linux. If the file does not exist, create it.The file should have the following contents. Substitute the address of your registry:

$ sudo vi /etc/docker/daemon.json
# Add or modify it:
{
  "insecure-registries" : ["http://registry.example.com:5050"]
}

Note: With insecure registries enabled, Docker goes through the following steps:

1. First, try using HTTPS.
2. If HTTPS is available but the certificate is invalid, ignore the error about the certificate.
3. If HTTPS is not available, fall back to HTTP.

• Restart Docker service for the changes to take effect.

$ sudo systemctl daemon-reload
$ sudo systemctl restart docker

Test Docker Registry login:

$ echo 'Clave123' | docker login registry.example.com:5050 -u devguy --password-stdin
# Answer
WARNING! Your password will be stored unencrypted in /home/pi/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login Succeeded

Repeat these steps on every Docker Engine host that wants to access your registry. (Not the Server).

3. Modify the GitLab configuration

We only need to modify two lines and uncomment the URL addresses. One is for the GitLab Source Control Server and another for the Docker Repository. If we like we can use the exactly the same FQDN for both as the access for each service its done in its own port.

• Edit the GitLab config file:

  $ sudo vi /etc/gitlab/gitlab.rb

• Remove the comment in registry_external_url line and port and update it. In this case both are on HTTP, the first listens on por 80, the second on 5050:

external_url "http://gitlab.example.com"

registry_external_url "http://registry.example.com:5050"

Save and exit

• Reconfigure your GitLab instance to apply the changes:

$ sudo gitlab-ctl reconfigure

---

II. Check if the GitLab Container Registry is enabled

As administrator:

• Check if the Container Registry is enabled by confirmin the availability ot two areas in the GitLab: ‘Admin area’ > Settings > CI/CD OR’Admin Area’ -> Settings > Repository

As a user:

• The project web page in GitLab instance will show a warning in the top of the project page if the Container Registry is not enabled:
  “Container registry is not enabled on this GitLab instance. Ask an administrator to enable it in order for Auto DevOps to work.”
• If the project is public, so is the Container Registry. It should be under Packages & Registries > Container Registry. If its not in your sidebar then it is not enabled. ORProject Settings > Container Registry if it is not shown the it is not enabled in your GitLab instance.

---

III. Authenticating from a CI/CD job

If you visit the Packages > Container Registry link under your project’s menu, you can see the following instructions to login to the Container Registry using your GitLab credentials:

# If you have Two-Factor Authentication enabled, use a Personal Access Token instead of a password.
$ docker login registry.example.com:5050
​
# You can add an image to this registry with the following commands: 
$ docker build -t registry.example.com:5050/devguy/php_example .
$ docker push registry.example.com:5050/devguy/php_example

For example if the Registry’s URL is registry.example.com:5050, then you should be able to login with:

$ echo 'Clave123' | docker login registry.example.com:5050 -u devguy --password-stdin
# Answer
WARNING! Your password will be stored unencrypted in /home/XXXXXXX/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login Succeeded

To view these commands, go to your project’s Packages & Registries > Container Registry.

---

Notes

Keep in mind that:

• By default, it is assumed that both services GitLab Server and GitLab Registry are running on the same node.
• The default location where images are stored (Omnibus install) is /var/opt/gitlab/gitlab-rails/shared/registry
• The log files are in /var/log/gitlab/registry/current
• The GitLab production error logs are in /var/log/gitlab/gitlab-rails/production.log.

---

Reference

• Architecture of the GitLab Registry
  https://docs.gitlab.com/omnibus/architecture/registry/
• Maintenance and notes for the registry from the GitLab team
  https://docs.gitlab.com/ee/user/packages/container_registry/
• Registry admin guide
  https://docs.gitlab.com/ee/administration/packages/container_registry.html
• Registry User Guide
  https://docs.gitlab.com/ee/user/packages/container_registry
• GitLab and Docker Registry
  https://dev.to/zaptic/how-to-gitlab-and-docker-registry-2moh
• Docker registries concepts
  https://docs.docker.com/registry/deploying
• Insecure registry docs
  https://docs.docker.com/registry/insecure/
• Setup guide [in Spanish]
  https://blog.irontec.com/creando-un-docker-registry-en-nuestro-gitlab

Advertisement