diff options
Diffstat (limited to 'doc/administration/packages/container_registry.md')
| -rw-r--r-- | doc/administration/packages/container_registry.md | 105 |
1 files changed, 103 insertions, 2 deletions
diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 14e54513536..a6829b90f18 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -44,7 +44,7 @@ If you have installed GitLab from source: 1. After the installation is complete, to enable it, you must configure the Registry's settings in `gitlab.yml`. 1. Use the sample NGINX configuration file from under - [`lib/support/nginx/registry-ssl`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/nginx/registry-ssl) and edit it to match the + [`lib/support/nginx/registry-ssl`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/support/nginx/registry-ssl) and edit it to match the `host`, `port`, and TLS certificate paths. The contents of `gitlab.yml` are: @@ -417,8 +417,27 @@ To configure the `s3` storage driver in Omnibus: } ``` - - `regionendpoint` is only required when configuring an S3 compatible service such as MinIO. It takes a URL such as `http://127.0.0.1:9000`. + If using with an [AWS S3 VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html), + then set `regionendpoint` to your VPC endpoint address and set `path_style` to false: + + ```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-vpc-endpoint', + 'path_style' => false + } + } + ``` + + - `regionendpoint` is only required when configuring an S3 compatible service such as MinIO, or + when using an AWS S3 VPC Endpoint. - `your-s3-bucket` should be the name of a bucket that exists, and can't include subdirectories. + - `path_style` should be set to true to use `host/bucket_name/object` style paths instead of + `bucket_name.host/object`. [Set to false for AWS S3](https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/). 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. @@ -1274,6 +1293,88 @@ curl "localhost:5001/debug/health" curl "localhost:5001/debug/vars" ``` +### Access old schema v1 Docker images + +Support for the [Docker registry v1 API](https://www.docker.com/blog/registry-v1-api-deprecation/), +including [schema V1 image manifests](https://docs.docker.com/registry/spec/manifest-v2-1/), +was: + +- [Deprecated in GitLab 13.7](https://about.gitlab.com/releases/2020/12/22/gitlab-13-7-released/#deprecate-pulls-that-use-v1-of-the-docker-registry-api) +- [Removed in GitLab 13.9](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#deprecate-pulls-that-use-v1-of-the-docker-registry-api) + +It's no longer possible to push or pull v1 images from the GitLab Container Registry. + +If you had v1 images in the GitLab Container Registry, but you did not upgrade them (following the +[steps Docker recommends](https://docs.docker.com/registry/spec/deprecated-schema-v1/)) +ahead of the GitLab 13.9 upgrade, these images are no longer accessible. If you try to pull them, +this error appears: + +- `Error response from daemon: manifest invalid: Schema 1 manifest not supported` + +For Self-Managed GitLab instances, you can regain access to these images by temporarily downgrading +the GitLab Container Registry to a version lower than `v3.0.0-gitlab`. Follow these steps to regain +access to these images: + +1. Downgrade the Container Registry to [`v2.13.1-gitlab`](https://gitlab.com/gitlab-org/container-registry/-/releases/v2.13.1-gitlab). +1. Upgrade any v1 images. +1. Revert the Container Registry downgrade. + +There's no need to put the registry in read-only mode during the image upgrade process. Ensure that +you are not relying on any new feature introduced since `v3.0.0-gitlab`. Such features are +unavailable during the upgrade process. See the [complete registry changelog](https://gitlab.com/gitlab-org/container-registry/-/blob/master/CHANGELOG.md) +for more information. + +The following sections provide additional details about each installation method. + +#### Helm chart installations + +For Helm chart installations: + +1. Override the [`image.tag`](https://docs.gitlab.com/charts/charts/registry/#configuration) + configuration parameter with `v2.13.1-gitlab`. +1. Restart. +1. Performing the [images upgrade](#images-upgrade)) steps. +1. Revert the `image.tag` parameter to the previous value. + +No other registry configuration changes are required. + +#### Omnibus installations + +For Omnibus installations: + +1. Temporarily replace the registry binary that ships with GitLab 13.9+ for one prior to + `v3.0.0-gitlab`. To do so, pull a previous version of the Docker image for the GitLab Container + Registry, such as `v2.13.1-gitlab`. You can then grab the `registry` binary from within this + image, located at `/bin/registry`: + + ```shell + id=$(docker create registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v2.13.1-gitlab) + docker cp $id:/bin/registry registry-2.13.1-gitlab + docker rm $id + ``` + +1. Replace the binary embedded in the Omnibus install, located at + `/opt/gitlab/embedded/bin/registry`, with `registry-2.13.1-gitlab`. Make sure to start by backing + up the original binary embedded in Omnibus, and restore it after performing the + [image upgrade](#images-upgrade)) steps. You should [stop](https://docs.gitlab.com/omnibus/maintenance/#starting-and-stopping) + the registry service before replacing its binary and start it right after. No registry + configuration changes are required. + +#### Source installations + +For source installations, locate your `registry` binary and temporarily replace it with the one +obtained from `v3.0.0-gitlab`, as explained for [Omnibus installations](#omnibus-installations). +Make sure to start by backing up the original registry binary, and restore it after performing the +[images upgrade](#images-upgrade)) +steps. + +#### Images upgrade + +Follow the [steps that Docker recommends to upgrade v1 images](https://docs.docker.com/registry/spec/deprecated-schema-v1/). +The most straightforward option is to pull those images and push them once again to the registry, +using a Docker client version above v1.12. Docker converts images automatically before pushing them +to the registry. Once done, all your v1 images should now be available as v2 images. + ### Advanced Troubleshooting We use a concrete example to illustrate how to |