Академический Документы
Профессиональный Документы
Культура Документы
html
With the Container Registry integrated into GitLab, every project can have its own space to store its Docker images.
You can read more about the Docker Registry at https://docs.docker.com/registry/introduction/ .
where:
Parameter Description
enabled true or false . Enables the Registry in GitLab. By default this is false .
host The host URL under which the Registry will run and the users will be able to use.
port The port under which the external Registry domain will listen on.
api_url The internal API URL under which the Registry is exposed to. It defaults to http://localhost:5000 .
key The private key location that is a pair of Registry’s rootcertbundle . Read the token auth configuration documentation .
1 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
Parameter Description
This should be the same directory like specified in Registry’s rootdirectory . Read the storage configuration
path documentation . This path needs to be readable by the GitLab user, the web-server user and the Registry user. Read
more in #container-registry-storage-path.
issuer This should be the same value as configured in Registry’s issuer . Read the token auth configuration documentation .
At the absolute minimum, make sure your Registry configuration has container_registry as the service and
https://gitlab.example.com/jwt/auth as the realm:
Use the existing GitLab domain where in that case the Registry will have to listen on a port and reuse GitLab’s TLS certificate,
Use a completely separate domain with a new TLS certificate for that domain.
Since the container Registry requires a TLS certificate, in the end it all boils down to how easy or pricey it is to get a new one.
Please take this into consideration before configuring the Container Registry for the first time.
1. Your /etc/gitlab/gitlab.rb should contain the Registry URL as well as the path to the existing TLS certificate and key used
by GitLab:
Note how the registry_external_url is listening on HTTPS under the existing GitLab URL, but on a different port.
2 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
2. Save the file and reconfigure GitLab for the changes to take effect.
3. Validate using:
1. Open /home/git/gitlab/config/gitlab.yml , find the registry entry and configure it with the following settings:
2. Save the file and restart GitLab for the changes to take effect.
3. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
Users should now be able to login to the Container Registry with their GitLab credentials using:
Let’s assume that you want the container Registry to be accessible at https://registry.gitlab.example.com .
3. Save the file and reconfigure GitLab for the changes to take effect.
If you have a wildcard certificate , you need to specify the path to the certificate in addition to the URL, in this case /etc/gitlab
3 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
1. Open /home/git/gitlab/config/gitlab.yml , find the registry entry and configure it with the following settings:
2. Save the file and restart GitLab for the changes to take effect.
3. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
Users should now be able to login to the Container Registry using their GitLab credentials:
Omnibus GitLab
2. Save the file and reconfigure GitLab for the changes to take effect.
1. Open /home/git/gitlab/config/gitlab.yml , find the registry entry and set enabled to false :
2. Save the file and restart GitLab for the changes to take effect.
4 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
2. Save the file and reconfigure GitLab for the changes to take effect.
2. Save the file and restart GitLab for the changes to take effect.
If you want to store your images on the filesystem, you can change the storage path for the Container Registry, follow the steps
below.
This path is accessible to:
1. Edit /etc/gitlab/gitlab.rb :
2. Save the file and reconfigure GitLab for the changes to take effect.
1. Open /home/git/gitlab/config/gitlab.yml , find the registry entry and change the path setting:
2. Save the file and restart GitLab for the changes to take effect.
5 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
Driver Description
s3 Amazon Simple Storage Service. Be sure to configure your storage bucket with the correct S3 Permission Scopes .
Read more about the individual driver’s config options in the Docker Registry docs .
1. Edit /etc/gitlab/gitlab.rb :
2. Save the file and reconfigure GitLab for the changes to take effect.
6 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
Storage limitations
Currently, there is no storage limitation, which means a user can upload an infinite amount of Docker images with arbitrary sizes.
This setting will be configurable in future releases.
The Registry server listens on localhost at port 5000 by default, which is the address for which the Registry server should accept
connections. In the examples below we set the Registry’s port to 5001 .
Omnibus GitLab
2. Save the file and reconfigure GitLab for the changes to take effect.
1. Open the configuration file of your Registry server and edit the http:addr value:
7 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
2. A certificate-key pair is required for GitLab and the external container registry to communicate securely. You will need to create
a certificate-key pair, configuring the external container registry with the public certificate and configuring GitLab with the
private key. To do that, add the following to /etc/gitlab/gitlab.rb :
3. To change the container registry URL displayed in the GitLab Container Registry pages, set the following configurations:
4. Save the file and reconfigure GitLab for the changes to take effect.
2. Save the file and restart GitLab for the changes to take effect.
8 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
1. Edit /etc/gitlab/gitlab.rb :
2. Save the file and reconfigure GitLab for the changes to take effect.
Container Registry can use considerable amounts of disk space. To clear up some unused layers, the registry includes a garbage
collect command.
GitLab offers a set of APIs to manipulate the Container Registry and aid the process of removing unused tags. Currently, this is
exposed using the API, but in the future, these controls will be migrated to the GitLab interface.
Project maintainers can delete Container Registry tags in bulk periodically based on their own criteria, however, this alone does not
recycle data, it only unlinks tags from manifests and image blobs. To recycle the Container Registry data in the whole GitLab instance,
you can use the built-in command provided by gitlab-ctl .
9 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
Now, the :latest tag points to manifest of sha256:222222 . However, due to the architecture of registry, this data is still accessible
when pulling the image my.registry.com/my.group/my.project@sha256:111111 , even though it is no longer directly accessible via the
:latest tag.
The built-in command will stop the registry before it starts the garbage collection.
The garbage collect command takes some time to complete, depending on the amount of data that exists.
If you changed the location of registry configuration file, you will need to specify its path.
After the garbage collection is done, the registry should start up automatically.
If you did not change the default location of the configuration file, run:
This command will take some time to complete, depending on the amount of layers you have stored.
If you changed the location of the Container Registry config.yml :
You may also remove all unreferenced manifests, although this is a way more destructive operation, and you should first understand
the implications.
The GitLab Container Registry follows the same default workflow as Docker Distribution: retain all layers, even ones that are
unreferenced directly to allow all content to be accessed using context addressable identifiers.
However, in most workflows, you don’t care about old layers if they are not directly referenced by the registry tag. The registry-
garbage-collect command supports the -m switch to allow you to remove all unreferenced manifests and layers that are not
directly accessible via tag :
10 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
Since this is a way more destructive operation, this behavior is disabled by default. You are likely expecting this way of operation, but
before doing that, ensure that you have backed up all registry data.
This will set the Container Registry into the read only mode.
3. Next, trigger the garbage collect command:
This will start the garbage collection, which might take some time to complete.
4. Once done, in /etc/gitlab/gitlab.rb change it back to read-write mode:
11 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
Troubleshooting
Before diving in to the following sections, here’s some basic troubleshooting:
1. Check to make sure that the system clock on your Docker client and GitLab server have been synchronized (e.g. via NTP).
2. If you are using an S3-backed Registry, double check that the IAM permissions and the S3 credentials (including region) are
correct. See the sample IAM policy for more details.
3. Check the Registry logs (e.g. /var/log/gitlab/registry/current ) and the GitLab production logs for errors (e.g. /var/log
/gitlab/gitlab-rails/production.log ). You may be able to find clues there.
The Docker daemon running the command expects a cert signed by a recognized CA, thus the error above.
While GitLab doesn’t support using self-signed certificates with Container Registry out of the box, it is possible to make it work by
instructing the docker-daemon to trust the self-signed certificates , mounting the docker-daemon and setting privileged =
false in the Runner’s config.toml . Setting privileged = true takes precedence over the docker-daemon:
Example error:
12 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
GitLab has a default token expiration of 5 minutes for the registry. When pushing larger images, or images that take longer than 5
minutes to push, users may encounter this error.
Administrators can increase the token duration in Admin area > Settings > Container Registry > Authorization token duration
(minutes).
AWS S3 with the GitLab registry error when pushing large images
When using AWS S3 with the GitLab registry, an error may occur when pushing large images. Look in the Registry log for the
following error:
To resolve the error specify a chunksize value in the Registry configuration. Start with a value between 25000000 (25MB) and
50000000 (50MB).
1. Edit /etc/gitlab/gitlab.rb :
2. Save the file and reconfigure GitLab for the changes to take effect.
1. Edit config/gitlab.yml :
2. Save the file and restart GitLab for the changes to take effect.
1. Edit /etc/gitlab/gitlab.rb :
2. Save the file and reconfigure GitLab for the changes to take effect.
13 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
1. Edit the YML configuration file you created when you deployed the registry . Add the following snippet:
Leading underscore
Trailing hyphen/dash
Double hyphen/dash
To get around this, you can change the group path, change the project path or change the branch name. Another option is to create
a push rule to prevent this at the instance level.
1. Edit /etc/gitlab/gitlab.rb :
2. Save the file and reconfigure GitLab for the changes to take effect.
1. Edit the YML configuration file you created when you deployed the registry . Add the following snippet:
2. Save the file and restart GitLab for the changes to take effect.
14 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
Advanced Troubleshooting
Sometimes it’s not obvious what is wrong, and you may need to dive deeper into the communication between the Docker client and
the Registry to find out what’s wrong. We will use a concrete example in the past to illustrate how to diagnose a problem with the S3
setup.
This error is ambiguous, as it’s not clear whether the 403 is coming from the GitLab Rails application, the Docker Registry, or
something else. In this case, since we know that since the login succeeded, we probably need to look at the communication between
the client and the Registry.
The REST API between the Docker client and Registry is described here . Normally, one would just use Wireshark or tcpdump to
capture the traffic and see where things went wrong. However, since all communications between Docker clients and servers are
done over HTTPS, it’s a bit difficult to decrypt the traffic quickly even if you know the private key. What can we do instead?
One way would be to disable HTTPS by setting up an insecure Registry . This could introduce a security hole and is only
recommended for local testing. If you have a production system and can’t or don’t want to do this, there is another way: use
mitmproxy, which stands for Man-in-the-Middle Proxy.
mitmproxy
mitmproxy allows you to place a proxy between your client and server to inspect all traffic. One wrinkle is that your system needs
to trust the mitmproxy SSL certificates for this to work.
The following installation instructions assume you are running Ubuntu:
1. Install mitmproxy .
2. Run mitmproxy --port 9000 to generate its certificates. Enter CTRL - C to quit.
15 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
If everything is set up correctly, you will see information on the mitmproxy window and no errors from the curl commands.
This will launch the Docker daemon and proxy all connections through mitmproxy.
In the example above, we see the following trace on the mitmproxy window:
The initial PUT requests went through fine with a 201 status code.
16 of 17 21-Feb-20, 4:55 PM
GitLab Container Registry administration | GitLab https://docs.gitlab.com/ee/administration/packages/container_registry.html
What does this mean? This strongly suggests that the S3 user does not have the right permissions to perform a HEAD request .
The solution: check the IAM permissions again . Once the right permissions were set, the error will go away.
If you spot an error or a need for improvement and would like to fix it yourself in a
merge request
17 of 17 21-Feb-20, 4:55 PM