summaryrefslogtreecommitdiff
path: root/doc/administration/packages/container_registry.md
diff options
context:
space:
mode:
authorGitLab Bot <gitlab-bot@gitlab.com>2021-06-16 18:25:58 +0000
committerGitLab Bot <gitlab-bot@gitlab.com>2021-06-16 18:25:58 +0000
commita5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 (patch)
treefb69158581673816a8cd895f9d352dcb3c678b1e /doc/administration/packages/container_registry.md
parentd16b2e8639e99961de6ddc93909f3bb5c1445ba1 (diff)
downloadgitlab-ce-a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4.tar.gz
Add latest changes from gitlab-org/gitlab@14-0-stable-eev14.0.0-rc42
Diffstat (limited to 'doc/administration/packages/container_registry.md')
-rw-r--r--doc/administration/packages/container_registry.md105
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