Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
path: root/doc/administration/packages/container_registry.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/administration/packages/container_registry.md')
-rw-r--r--doc/administration/packages/container_registry.md172
1 files changed, 91 insertions, 81 deletions
diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md
index 34acf57ce70..fd3cbb2ad05 100644
--- a/doc/administration/packages/container_registry.md
+++ b/doc/administration/packages/container_registry.md
@@ -21,10 +21,8 @@ Registry, see the [user documentation](../../user/packages/container_registry/in
If you installed GitLab by using the Omnibus installation package, the Container Registry
may or may not be available by default.
-The Container Registry is automatically enabled and available on your GitLab domain, port 5050 if:
-
-- You're using the built-in [Let's Encrypt integration](https://docs.gitlab.com/omnibus/settings/ssl.html#enable-the-lets-encrypt-integration), and
-- You're using GitLab 12.5 or later.
+The Container Registry is automatically enabled and available on your GitLab domain, port 5050 if
+you're using the built-in [Let's Encrypt integration](https://docs.gitlab.com/omnibus/settings/ssl/index.html#enable-the-lets-encrypt-integration).
Otherwise, the Container Registry is not enabled. To enable it:
@@ -96,7 +94,7 @@ If `auth` is not set up, users can pull Docker images without authentication.
## Container Registry domain configuration
-There are two ways you can configure the Registry's external domain. Either:
+You can configure the Registry's external domain in either of these ways:
- [Use the existing GitLab domain](#configure-container-registry-under-an-existing-gitlab-domain).
The Registry listens on a port and reuses the TLS certificate from GitLab.
@@ -110,13 +108,15 @@ for the first time.
### Configure Container Registry under an existing GitLab domain
-If the Registry is configured to use the existing GitLab domain, you can
-expose the Registry on a port. This way you can reuse the existing GitLab TLS
+If the Container Registry is configured to use the existing GitLab domain, you can
+expose the Container Registry on a port. This way you can reuse the existing GitLab TLS
certificate.
-If the GitLab domain is `https://gitlab.example.com` and the port to the outside world is `5050`, here is what you need to set
-in `gitlab.rb` or `gitlab.yml` if you are using Omnibus GitLab or installed
-GitLab from source respectively.
+If the GitLab domain is `https://gitlab.example.com` and the port to the outside world is `5050`,
+to configure the Container Registry:
+
+- Edit `gitlab.rb` if you are using Omnibus GitLab.
+- Edit `gitlab.yml` if you installed GitLab from source.
Ensure you choose a port different than the one that Registry listens to (`5000` by default),
otherwise conflicts occur.
@@ -202,7 +202,7 @@ domain. For example, `*.gitlab.example.com`, is a wildcard that matches `registr
and is distinct from `*.example.com`.
As well as manually generated SSL certificates (explained here), certificates automatically
-generated by Let's Encrypt are also [supported in Omnibus installs](https://docs.gitlab.com/omnibus/settings/ssl.html).
+generated by Let's Encrypt are also [supported in Omnibus installs](https://docs.gitlab.com/omnibus/settings/ssl/index.html).
Let's assume that you want the container Registry to be accessible at
`https://registry.gitlab.example.com`.
@@ -261,7 +261,7 @@ docker login registry.gitlab.example.com
## Disable Container Registry site-wide
When you disable the Registry by following these steps, you do not
-remove any existing Docker images. This is handled by the
+remove any existing Docker images. Docker image removal is handled by the
Registry application itself.
**Omnibus GitLab**
@@ -557,7 +557,7 @@ you can pull from the Container Registry, but you cannot push.
1. To perform the final data sync,
[put the Container Registry in `read-only` mode](#performing-garbage-collection-without-downtime) and
[reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
-1. Sync any changes since the initial data load to your S3 bucket and delete files that exist in the destination bucket but not in the source:
+1. Sync any changes dating from after the initial data load to your S3 bucket, and delete files that exist in the destination bucket but not in the source:
```shell
sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket --delete --dryrun
@@ -590,15 +590,15 @@ you can pull from the Container Registry, but you cannot push.
#### Moving to Azure Object Storage
-> The default configuration for the storage driver will be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0.
+> The default configuration for the storage driver is scheduled to be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0.
<!--- start_remove The following content will be removed on remove_date: '2023-10-22' -->
WARNING:
-The default configuration for the storage driver will be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0. The storage driver will use `/` as the default root directory. You can add `trimlegacyrootprefix: false` to your current configuration now to avoid any disruptions. For more information, see the [Container Registry configuration](https://gitlab.com/gitlab-org/container-registry/-/tree/master/docs-gitlab#azure-storage-driver) documentation.
+The default configuration for the storage driver is scheduled to be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0. The storage driver will use `/` as the default root directory. You can add `trimlegacyrootprefix: false` to your current configuration now to avoid any disruptions. For more information, see the [Container Registry configuration](https://gitlab.com/gitlab-org/container-registry/-/tree/master/docs-gitlab#azure-storage-driver) documentation.
<!--- end_remove -->
When moving from an existing file system or another object storage provider to Azure Object Storage, you must configure the registry to use the standard root directory.
-This configuration is done by setting [`trimlegacyrootprefix: true]`](https://gitlab.com/gitlab-org/container-registry/-/blob/a3f64464c3ec1c5a599c0a2daa99ebcbc0100b9a/docs-gitlab/README.md#azure-storage-driver) in the Azure storage driver section of the registry configuration.
+Configure it by setting [`trimlegacyrootprefix: true]`](https://gitlab.com/gitlab-org/container-registry/-/blob/a3f64464c3ec1c5a599c0a2daa99ebcbc0100b9a/docs-gitlab/README.md#azure-storage-driver) in the Azure storage driver section of the registry configuration.
Without this configuration, the Azure storage driver uses `//` instead of `/` as the first section of the root path, rendering the migrated images inaccessible.
**Omnibus GitLab installations**
@@ -607,10 +607,10 @@ Without this configuration, the Azure storage driver uses `//` instead of `/` as
registry['storage'] = {
'azure' => {
'accountname' => 'accountname',
- 'accesskey' => 'base64encodedaccountkey',
+ 'accountkey' => 'base64encodedaccountkey',
'container' => 'containername',
'rootdirectory' => '/azure/virtual/container',
- 'trimlegacyrootprefix' => 'true'
+ 'trimlegacyrootprefix' => true
}
}
```
@@ -627,6 +627,8 @@ storage:
trimlegacyrootprefix: true
```
+By default, Azure Storage Driver uses the `core.windows.net` realm. You can set another value for `realm` in the `azure` section (for example, `core.usgovcloudapi.net` for Azure Government Cloud). For more information, see the [Docker documentation](https://docs.docker.com/registry/storage-drivers/azure/).
+
### Disable redirect for storage driver
By default, users accessing a registry configured with a remote backend are redirected to the default backend for the storage driver. For example, registries can be configured using the `s3` storage driver, which redirects requests to a remote S3 bucket to alleviate load on the GitLab server.
@@ -637,20 +639,20 @@ However, this behavior is undesirable for registries used by internal hosts that
1. Edit `/etc/gitlab/gitlab.rb`:
- ```ruby
- registry['storage'] = {
- 's3' => {
- 'accesskey' => 's3-access-key',
- 'secretkey' => 's3-secret-key-for-access-key',
- 'bucket' => 'your-s3-bucket',
- 'region' => 'your-s3-region',
- 'regionendpoint' => 'your-s3-regionendpoint'
- },
- 'redirect' => {
- 'disable' => true
- }
- }
- ```
+ ```ruby
+ registry['storage'] = {
+ 's3' => {
+ 'accesskey' => 's3-access-key',
+ 'secretkey' => 's3-secret-key-for-access-key',
+ 'bucket' => 'your-s3-bucket',
+ 'region' => 'your-s3-region',
+ 'regionendpoint' => 'your-s3-regionendpoint'
+ },
+ 'redirect' => {
+ 'disable' => true
+ }
+ }
+ ```
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
@@ -658,21 +660,21 @@ However, this behavior is undesirable for registries used by internal hosts that
1. Add the `redirect` flag to your registry configuration YAML file:
- ```yaml
- storage:
- s3:
- accesskey: 'AKIAKIAKI'
- secretkey: 'secret123'
- bucket: 'gitlab-registry-bucket-AKIAKIAKI'
- region: 'your-s3-region'
- regionendpoint: 'your-s3-regionendpoint'
- redirect:
- disable: true
- cache:
- blobdescriptor: inmemory
- delete:
- enabled: true
- ```
+ ```yaml
+ storage:
+ s3:
+ accesskey: 'AKIAKIAKI'
+ secretkey: 'secret123'
+ bucket: 'gitlab-registry-bucket-AKIAKIAKI'
+ region: 'your-s3-region'
+ regionendpoint: 'your-s3-regionendpoint'
+ redirect:
+ disable: true
+ cache:
+ blobdescriptor: inmemory
+ delete:
+ enabled: true
+ ```
1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
@@ -680,7 +682,7 @@ However, this behavior is undesirable for registries used by internal hosts that
You can use server-side encryption with AWS KMS for S3 buckets that have
[SSE-S3 or SSE-KMS encryption enabled by default](https://docs.aws.amazon.com/kms/latest/developerguide/services-s3.html).
-Customer master keys (CMKs) and SSE-C encryption aren't supported since this requires sending the
+Customer master keys (CMKs) and SSE-C encryption aren't supported because this requires sending the
encryption keys in every request.
For SSE-S3, you must enable the `encrypt` option in the registry settings. How you do this depends
@@ -690,18 +692,18 @@ For Omnibus GitLab installations:
1. Edit `/etc/gitlab/gitlab.rb`:
- ```ruby
- registry['storage'] = {
- 's3' => {
- 'accesskey' => 's3-access-key',
- 'secretkey' => 's3-secret-key-for-access-key',
- 'bucket' => 'your-s3-bucket',
- 'region' => 'your-s3-region',
- 'regionendpoint' => 'your-s3-regionendpoint',
- 'encrypt' => true
- }
- }
- ```
+ ```ruby
+ registry['storage'] = {
+ 's3' => {
+ 'accesskey' => 's3-access-key',
+ 'secretkey' => 's3-secret-key-for-access-key',
+ 'bucket' => 'your-s3-bucket',
+ 'region' => 'your-s3-region',
+ 'regionendpoint' => 'your-s3-regionendpoint',
+ 'encrypt' => true
+ }
+ }
+ ```
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure)
for the changes to take effect.
@@ -710,23 +712,23 @@ For installations from source:
1. Edit your registry configuration YAML file:
- ```yaml
- storage:
- s3:
- accesskey: 'AKIAKIAKI'
- secretkey: 'secret123'
- bucket: 'gitlab-registry-bucket-AKIAKIAKI'
- region: 'your-s3-region'
- regionendpoint: 'your-s3-regionendpoint'
- encrypt: true
- ```
+ ```yaml
+ storage:
+ s3:
+ accesskey: 'AKIAKIAKI'
+ secretkey: 'secret123'
+ bucket: 'gitlab-registry-bucket-AKIAKIAKI'
+ region: 'your-s3-region'
+ regionendpoint: 'your-s3-regionendpoint'
+ encrypt: true
+ ```
1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source)
for the changes to take effect.
### Storage limitations
-Currently, there is no storage limitation, which means a user can upload an
+There is no storage limitation, which means a user can upload an
infinite amount of Docker images with arbitrary sizes. This setting should be
configurable in future releases.
@@ -765,7 +767,11 @@ project, you can [disable it from your project's settings](../../user/project/se
## Use an external container registry with GitLab as an auth endpoint
-> Support for external container registries in GitLab is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/376217) in GitLab 15.8 and will be removed in GitLab 16.0.
+WARNING:
+Using external container registries in GitLab is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/376217)
+in GitLab 15.8 and the end of support is scheduled for GitLab 16.0.
+If you need to use external container registries instead of the GitLab Container Registry,
+tell us about your use cases in [feedback issue 958](https://gitlab.com/gitlab-org/container-registry/-/issues/958).
If you use an external container registry, some features associated with the
container registry may be unavailable or have [inherent risks](../../user/packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries).
@@ -871,7 +877,7 @@ You can use GitLab as an auth endpoint with an external container registry.
## Configure Container Registry notifications
You can configure the Container Registry to send webhook notifications in
-response to events happening within the registry.
+response to events happening in the registry.
Read more about the Container Registry notifications configuration options in the
[Docker Registry notifications documentation](https://docs.docker.com/registry/notifications/).
@@ -924,13 +930,17 @@ notifications:
WARNING:
If you're using a distributed architecture and Sidekiq is running on a different node, the cleanup
-policies don't work. To fix this, you must configure the `gitlab.rb` file on the Sidekiq nodes to
-point to the correct registry URL and copy the `registry.key` file to each Sidekiq node. For more
-information, see the [Sidekiq configuration](../sidekiq/index.md)
+policies don't work. To fix this:
+
+1. Configure the `gitlab.rb` file on the Sidekiq nodes to
+ point to the correct registry URL.
+1. Copy the `registry.key` file to each Sidekiq node.
+
+For more information, see the [Sidekiq configuration](../sidekiq/index.md)
page.
To reduce the amount of [Container Registry disk space used by a given project](#registry-disk-space-usage-by-project),
-administrators can clean up image tags
+administrators can setup cleanup policies
and [run garbage collection](#container-registry-garbage-collection).
### Registry Disk Space Usage by Project
@@ -993,7 +1003,7 @@ You can also [run cleanup on a schedule](../../user/packages/container_registry/
## Container Registry garbage collection
NOTE:
-Retention policies within your object storage provider, such as Amazon S3 Lifecycle, may prevent
+Retention policies in your object storage provider, such as Amazon S3 Lifecycle, may prevent
objects from being properly deleted.
Container Registry can use considerable amounts of disk space. To clear up
@@ -1037,9 +1047,9 @@ docker build -t my.registry.com/my.group/my.project:latest .
docker push my.registry.com/my.group/my.project:latest
```
-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
+Now, the `:latest` tag points to manifest of `sha256:222222`.
+Due to the architecture of registry, this data is still accessible when pulling the
+image `my.registry.com/my.group/my.project@sha256:111111`, though it is
no longer directly accessible via the `:latest` tag.
### Recycling unused tags
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-16 23:10:29 +0300