GitLab Documentation

Architecture of GitLab Container Registry

The GitLab registry is what users use to store their own Docker images. Because of that the Registry is client facing, meaning that we expose it directly on the web server (or load balancers, LB for short).

GitLab Registry diagram

The flow described by the diagram above:

  1. A user runs docker login registry.gitlab.example on their client. This reaches the web server (or LB) on port 443.
  2. Web server connects to the Registry backend pool (by default, using port 5000). Since the user didn’t provide a valid token the Registry returns a 401 HTTP code and the url (token_realm from Registry configuration) where to get one. This points to the GitLab API.
  3. The Docker client then connects to the GitLab API and obtains a token.
  4. The API signs the token with the registry key and hands it to the Docker client
  5. The Docker client now logs in again with the token received from the API. It can now push and pull Docker images.

Reference: https://docs.docker.com/registry/spec/auth/token/

Communication between GitLab and Registry

Registry doesn’t have a way to authenticate users internally so it relies on GitLab to validate credentials. The connection between Registry and GitLab is TLS encrypted. The key is used by GitLab to sign the tokens while the certificate is used by Registry to validate the signature. By default, a self-signed certificate key pair is generated for all installations. This can be overridden as needed.

GitLab interacts with the Registry using the Registry private key. When a Registry request goes out, a new short-living (10 minutes) namespace limited token is generated and signed with the private key. The Registry then verifies that the signature matches the registry certificate specified in its configuration and allows the operation. GitLab background jobs processing (through sidekiq) also interacts with Registry. These jobs talk directly to Registry in order to handle image deletion.

Configuring GitLab and Registry to run on separate nodes

By default, package assumes that both services are running on the same node. In order to get GitLab and Registry to run on a separate nodes, separate configuration is necessary for Registry and GitLab.

Configuring Registry

Below you will find configuration options you should set in /etc/gitlab/gitlab.rb, for Registry to run separately from GitLab:

Configuring GitLab

Below you will find configuration options you should set in /etc/gitlab/gitlab.rb, for GitLab to run separately from Registry:


Leave a comment below if you have any feedback on the documentation. For support and other enquiries, see getting help.