diff --git a/docs/container_registry.md b/docs/container_registry.md index 5c655e7b..640269d7 100644 --- a/docs/container_registry.md +++ b/docs/container_registry.md @@ -1,9 +1,9 @@ GitLab Container Registry ========================= -Since `8.8.0` GitLab introduces container registry. Container Registry is a feature that handles your authentication for a docker registry. - +Since `8.8.0` GitLab introduces container registry. GitLab is helping to authenticate the user against the registry and proxy it via NGINX. If we are talking about [Registry](https://docs.docker.com/registry) we are meaning the registry from docker and Container Registry is the feature of GitLab. - [Prerequisites](#prerequisites) +- [Avialable Paramerts](#available-parameters) - [Installation](#installation) - [Maintenance](#maintenance) - [Creating Backups](#creating-backups) @@ -11,32 +11,67 @@ Since `8.8.0` GitLab introduces container registry. Container Registry is a feat - [Upgrading from an existing GitLab instance](#Upgrading-from-an-existing-GitLab-instance) # Prerequisites + - [Docker Distribution](https://github.com/docker/distribution) >= 2.4 - [Docker GitLab](https://github.com/sameersbn/docker-gitlab) >= 8.8.5-1 + +# Available Parameters + +Here is an example of all configuration parameters that can be used in the GitLab container. + +``` +... +gitlab: + ... + environment: + - GITLAB_REGISTRY_ENABLED=true + - GITLAB_REGISTRY_HOST=registry.gitlab.example.com + - GITLAB_REGISTRY_PORT=5500 + - GITLAB_REGISTRY_API_URL=http://registry:5000 + - GITLAB_REGISTRY_KEY_PATH=/certs/registry-auth.key + - GITLAB_REGISTRY_ISSUER=gitlab-issuer + - SSL_REGISTRY_KEY_PATH=/certs/registry.key + - SSL_REGISTRY_CERT_PATH=/certs/registry.crt +``` + +where: + +| Parameter | Description | +| --------- | ----------- | +| `GITLAB_REGISTRY_ENABLED ` | `true` or `false`. Enables the Registry in GitLab. By default this is `false`. | +| `GITLAB_REGISTRY_HOST ` | The host URL under which the Registry will run and the users will be able to use. | +| `GITLAB_REGISTRY_PORT ` | The port under which the external Registry domain will listen on. | +| `GITLAB_REGISTRY_API_URL ` | The internal API URL under which the Registry is exposed to. | +| `GITLAB_REGISTRY_KEY_PATH `| The private key location that is a pair of Registry's `rootcertbundle`. Read the [token auth configuration documentation][token-config]. | +| `GITLAB_REGISTRY_PATH ` | This should be the same directory like specified in Registry's `rootdirectory`. Read the [storage configuration documentation][storage-config]. This path needs to be readable by the GitLab user, the web-server user and the Registry user *if you use filesystem as storage configuration*. Read more in [#container-registry-storage-path](#container-registry-storage-path). | +| `GITLAB_REGISTRY_KEY_ISSUER` | This should be the same value as configured in Registry's `issuer`. Otherwise the authentication will not work. For more info read the [token auth configuration documentation][token-config]. | +| `SSL_REGISTRY_KEY_PATH ` | The private key of the `SSL_REGISTRY_CERT_PATH`. This will be later used in nginx to proxy your registry via https. | +| `SSL_REGISTRY_CERT_PATH ` | The certificate for the private key of `SSL_REGISTRY_KEY_PATH`. This will be later used in nginx to proxy your registry via https. | + +For more info look at [Available Configuration Parameters](https://github.com/sameersbn/docker-gitlab#available-configuration-parameters). + +A minimum set of these parameters are required to use the GitLab Container Registry feature. + +```yml +... +gitlab: + environment: + - GITLAB_REGISTRY_ENABLED=true + - GITLAB_REGISTRY_HOST=registry.gitlab.example.com + - GITLAB_REGISTRY_API_URL=http://registry:5000 + - GITLAB_REGISTRY_KEY_PATH=/certs/registry-auth.key + - GITLAB_REGISTRY_ISSUER=gitlab-issuer +... +``` # Installation -Starting a fresh installation with GitLab Container registry would be like this `docker-compose` file. -## Generating certificate for authentication with the registry - -You can skip the following steps if you have a **trusted certificate**. - -- **Step 1**: Create a certs dir - ```bash - mkdir certs && cd certs - ``` - -- **Step 2**: Generate a private key and sign request for the private key -```bash -openssl req -nodes -newkey rsa:4096 -keyout registry-auth.key -out registry-auth.csr -subj "/CN=gitlab-issuer" -``` - -- **Step 3**: Sign your created privated key -```bash -openssl x509 -in registry-auth.csr -out registry-auth.crt -req -signkey registry-auth.key -days 3650 -``` +Starting a fresh installation with GitLab Container registry would be like the `docker-compose` file. ## Docker Compose + +This is an example with a registry and filesystem as storage driver. + ```yml version: '2' @@ -47,12 +82,12 @@ services: command: - --loglevel warning volumes: - - /srv/gitlab/redis:/var/lib/redis:Z + - ./redis:/var/lib/redis:Z postgresql: restart: always image: sameersbn/postgresql:9.4-22 volumes: - - /srv/gitlab/postgresql:/var/lib/postgresql:Z + - ./postgresql:/var/lib/postgresql:Z environment: - DB_USER=gitlab - DB_PASS=password @@ -70,8 +105,8 @@ services: - "5500:5500" - "10022:22" volumes: - - /srv/gitlab/gitlab:/home/git/data:Z - - /srv/gitlab/logs:/var/log/gitlab + - ./gitlab:/home/git/data:Z + - ./logs:/var/log/gitlab - ./certs:/certs environment: - DEBUG=false @@ -87,7 +122,7 @@ services: - REDIS_PORT=6379 - GITLAB_SSH_PORT=10022 - GITLAB_PORT=10080 - - GITLAB_HOST=localhost + - GITLAB_HOST=gitlab.example.com - GITLAB_SECRETS_DB_KEY_BASE=superrandomsecret - GITLAB_REGISTRY_ENABLED=true @@ -102,12 +137,12 @@ services: restart: always image: registry:2.4.1 volumes: - - /srv/gitlab/shared/registry:/registry - - ./certs:/certs + - ./gitlab/shared/registry:/registry + - ./certs:/certs environment: - REGISTRY_LOG_LEVEL=info - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/registry - - REGISTRY_AUTH_TOKEN_REALM=https://gitlab.example.com:10080/jwt/auth + - REGISTRY_AUTH_TOKEN_REALM=http://gitlab.example.com:10080/jwt/auth - REGISTRY_AUTH_TOKEN_SERVICE=container_registry - REGISTRY_AUTH_TOKEN_ISSUER=gitlab-issuer - REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE=/certs/registry-auth.crt @@ -119,10 +154,122 @@ services: > 2. `REGISTRY_AUTH_TOKEN_REALM` need to be look like `http/s://gitlab.example.com/jwt/auth`. Endpoint must be `/jwt/auth` > These configuration options are required by the GitLab Container Registry. -The trick is here that you are mounting the registry data as volume from `$GITLAB_REGISTRY_DIR`. So this adds the ability to do backups and restore them. + +## Generating certificate for authentication with the registry + +So GitLab handles for us the authentication with Registry we need an certifcate to do that secure. +With have here two options: + +1. Use a signed certificate from an Trusted Certificate Authority. +2. Self-Signed Certificate for the authentication process. + +### Signed Certifcate +If you have a signed certificate from a Trusted Certificate Authority you need only to copy the files in then `certs` folder and mount the folder in both containers (gitlab,registry) like in the docker-compose example. +After that you need to set an environment variable in each container. +In the **GitLab Container** you need to set `GITLAB_REGISTRY_KEY_PATH` this is the private key of the signed certificate. +In the **Registry Container** you need to set `REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE` to the certificate file of the signed certifcate. +For more info read [token auth configuration documentation][token-config]. + +### Self Signed Certificate + +Generate a self signed certificate with openssl. + +- **Step 1**: Create a certs dir + ```bash + mkdir certs && cd certs + ``` + +- **Step 2**: Generate a private key and sign request for the private key +```bash +openssl req -nodes -newkey rsa:4096 -keyout registry-auth.key -out registry-auth.csr -subj "/CN=gitlab-issuer" +``` + +- **Step 3**: Sign your created privated key +```bash +openssl x509 -in registry-auth.csr -out registry-auth.crt -req -signkey registry-auth.key -days 3650 +``` + +After this mount the `certs` dir in both containers and set the same environment variables like way of the signed certificate. + + + +## Container Registry storage driver + +You can configure the Container Registry to use a different storage backend by +configuring a different storage driver. By default the GitLab Container Registry +is configured to use the filesystem driver, which makes use of [storage path](#container-registry-storage-path) +configuration. These configurations will all be done in the registry container. + +The different supported drivers are: + +| Driver | Description | +|------------|-------------------------------------| +| filesystem | Uses a path on the local filesystem | +| azure | Microsoft Azure Blob Storage | +| gcs | Google Cloud Storage | +| s3 | Amazon Simple Storage Service | +| swift | OpenStack Swift Object Storage | +| oss | Aliyun OSS | + +Read more about the individual driver's config options in the +[Docker Registry docs][storage-config]. + +> **Warning** GitLab will not backup Docker images that are not stored on the filesystem. Remember to enable backups with your object storage provider if desired. +> +> If you use **filesystem** as storage driver you need to mount the path from `GITLAB_REGISTRY_DIR` of the GitLab container in the registry container. So both container can access the registry data. +> If you don't change `GITLAB_REGISTRY_DIR` you will find your registry data in the mounted volume from the GitLab Container under `./gitlab/shared/registry`. This don't need to be seprated mounted because `./gitlab` is already mounted in the GitLab Container. If it will be mounted seperated the whole restoring proccess of GitLab backup won't work because gitlab try to create an folder under `./gitlab/shared/registry` /`GITLAB_REGISTRY_DIR` and GitLab can't delete/remove the mount point inside the container so the restoring process of the backup will fail. +> An example how it works is in the `docker-compose`. + +### Example for Amazon Simple Storage Service (s3) + +If you want to configure your registry via `/etc/docker/registry/config.yml` your storage part should like this snippet below. + +```yaml +storage: + s3: + accesskey: 'AKIAKIAKI' + secretkey: 'secret123' + bucket: 'gitlab-registry-bucket-AKIAKIAKI' + cache: + blobdescriptor: inmemory + delete: + enabled: true +``` + + + +```yaml + ... + registry: + restart: always + image: registry:2.4.1 + volumes: + - ./certs:/certs + environment: + - REGISTRY_LOG_LEVEL=info + - REGISTRY_AUTH_TOKEN_REALM=https://gitlab.example.com:10080/jwt/auth + - REGISTRY_AUTH_TOKEN_SERVICE=container_registry + - REGISTRY_AUTH_TOKEN_ISSUER=gitlab-issuer + - REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE=/certs/registry-auth.crt + - REGISTRY_STORAGE_S3_ACCESSKEY=AKIAKIAKI + - REGISTRY_STORAGE_S3_SECRETKEY=secret123 + - REGISTRY_STORAGE_S3_BUCKET=gitlab-registry-bucket-AKIAKIAKI + - REGISTRY_CACHE_BLOBDESCRIPTOR=inmemory + - REGISTRY_STORAGE_DELETE_ENABLED=true +``` + +Generaly for more information about the configuration of the registry container you can find it under [registry configuration](https://docs.docker.com/registry/configuration). + + +## 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. # Maintenance +If you use another storage configuration than filesystem it will have no impact on your Maintenance workflow. ## Creating Backups @@ -225,3 +372,12 @@ docker run --name gitlab -d [PREVIOUS_OPTIONS] \ --link registry:registry sameersbn/gitlab:8.9.5 ``` + + +[wildcard certificate]: https://en.wikipedia.org/wiki/Wildcard_certificate +[ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040 +[docker-insecure]: https://docs.docker.com/registry/insecure/ +[registry-deploy]: https://docs.docker.com/registry/deploying/ +[storage-config]: https://docs.docker.com/registry/configuration/#storage +[token-config]: https://docs.docker.com/registry/configuration/#token +[8-8-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-8-stable/doc/administration/container_registry.md \ No newline at end of file