diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-05-22 04:08:26 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-05-22 22:54:29 +0300 |
commit | e9817f21f4baa20244095f56dd0d45b5c2e9c5dc (patch) | |
tree | 3922df54233af9a7a76466b983922f827404cf52 /doc/administration | |
parent | c1af75192dd281e23249a5d4eb4126dce5bc5efd (diff) |
Major overhaul of the Registry admin docs
Diffstat (limited to 'doc/administration')
-rw-r--r-- | doc/administration/container_registry.md | 294 |
1 files changed, 187 insertions, 107 deletions
diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index 15c3c1a7470..21f086792cd 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -3,8 +3,8 @@ > **Note:** This feature was [introduced][ce-4040] in GitLab 8.8. -With the Docker container Registry integrated into GitLab, every project can -have its own space for Docker images. +With the Docker Container Registry integrated into GitLab, every project can +have its own space to store its Docker images. You can read more about Docker Registry at https://docs.docker.com/registry/introduction/. @@ -14,18 +14,22 @@ You can read more about Docker Registry at https://docs.docker.com/registry/intr <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* -- [Differences between Omnibus and source installations](#differences-between-omnibus-and-source-installations) +- [How to enable the Container Registry](#how-to-enable-the-container-registry) - [Container Registry domain configuration](#container-registry-domain-configuration) - - [Container Registry under existing GitLab domain](#container-registry-under-existing-gitlab-domain) - - [Container Registry under its own domain](#container-registry-under-its-own-domain) + - [Configure Container Registry under an existing GitLab domain](#configure-container-registry-under-an-existing-gitlab-domain) + - [Configure Container Registry under its own domain](#configure-container-registry-under-its-own-domain) +- [Disable Container Registry site-wide](#disable-container-registry-site-wide) +- [Disable Container Registry per project](#disable-container-registry-per-project) +- [Disable Container Registry for new projects site-wide](#disable-container-registry-for-new-projects-site-wide) - [Container Registry storage path](#container-registry-storage-path) -- [Disable Container Registry](#disable-container-registry) +- [Storage limitations](#storage-limitations) - [Changelog](#changelog) <!-- END doctoc generated TOC please keep comment here to allow auto update --> +## How to enable the Container Registry -## Differences between Omnibus and source installations +**Omnibus GitLab installations** If you are using Omnibus, you have to bare in mind the following: @@ -35,19 +39,21 @@ If you are using Omnibus, you have to bare in mind the following: on how to achieve that. You will also have to configure your firewall to allow connections to that port. - The container Registry works under HTTPS by default. Using HTTP is possible - but not recommended and out of the scope of this document, - [see the insecure Registry documentation][docker-insecure] if you want to + but not recommended and out of the scope of this document. + [See the insecure Registry documentation][docker-insecure] if you want to implement this. --- +**Installations from source** + If you have installed GitLab from source: -- Omnibus has some things configured for you -- You will have to install Docker Registry by yourself. You can follow the - [official documentation][registry-deploy]. -- The container Registry will not be enabled by default, you will have to - configure it in `gitlab.yml`. +1. You will have to [install Docker Registry][registry-deploy] by yourself. +1. After the installation is complete, you will have to configure the Registry's + settings `gitlab.yml` in order to enable it. +1. Use the sample NGINX configuration file that is found under + [`lib/support/nginx/registry-ssl`][registry-ssl]. The contents of `gitlab.yml` are: @@ -66,26 +72,31 @@ where: | Parameter | Description | | --------- | ----------- | -| `enabled` | Enables the Registry in GitLab. By default this is false. | +| `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_path`| The private key location that is a pair of Registry's `rootcertbundle`. Read the [token auth configuration documentation][token-config]. | -| `path` | This should be the same directory like specified in Registry's `rootdirectory`. Read the [storage configuration documentation][storage-config]. | +| `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. Read more in [#container-registry-storage-path](#container-registry-storage-path). | | `issuer` | This should be the same value as configured in Registry's `issuer`. Read the [token auth configuration documentation][token-config]. | +>**Note:** +GitLab does not ship with a Registry init file. Hence, [restarting GitLab][restart gitlab] +will not restart the Registry should you modify its settings. Read the upstream +documentation on how to achieve that. + ## Container Registry domain configuration There are two ways you can configure the Registry's external domain. Either use the existing GitLab domain where in that case the Registry will listen on a port, or use a completely separate domain. Since the container Registry requires a -TLS certificate, in the end it all boils down to how easy or pricey is to -get a new TLS certificate. +TLS certificate, in the end it all boils down to how easy or pricey is to get a +new TLS certificate. Please take this into consideration before configuring the Container Registry for the first time. -### Container Registry under existing GitLab domain +### 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 so that you can reuse the existing GitLab TLS @@ -96,118 +107,203 @@ Registry is exposed to the outside world is `4567`, 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. -**Omnibus GitLab packages** +--- + +**Omnibus GitLab installations** + +>**Note:** +If you are using HTTPS in your Omnibus packages, then the Registry will be +enabled by default and exposed under port `5005`. Follow the steps below only if +you want to change the default port. 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. + path to the existing TLS certificate and key used by GitLab: ```ruby + gitlab_rails['registry_port'] = "4567" + gitlab_rails['registry_host'] = "gitlab.example.com" + + # The following setting is needed for NGINX registry_external_url 'https://gitlab.example.com:4567' + ``` - ## If your SSL certificate is not in /etc/gitlab/ssl/gitlab.example.com.crt - ## and key not in /etc/gitlab/ssl/gitlab.example.com.key uncomment the lines - ## below + If your TLS certificate is not in `/etc/gitlab/ssl/gitlab.example.com.crt` + and key not in `/etc/gitlab/ssl/gitlab.example.com.key` uncomment the lines + below: - # registry_nginx['ssl_certificate'] = "/path/to/certificate.pem" - # registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key" + ```ruby + registry_nginx['ssl_certificate'] = "/path/to/certificate.pem" + registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key" ``` 1. Save the file and [reconfigure GitLab][] for the changes to take effect. --- -**Installation from source** +**Installations from source** -``` -registry: - enabled: true - host: registry.gitlab.example.com - port: 5005 - api_url: http://localhost:5000/ - key_path: config/registry.key - path: shared/registry - issuer: gitlab-issuer -``` +1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and + configure it with the following settings: + + ``` + registry: + enabled: true + host: gitlab.example.com + port: 4567 + ``` -Users should now be able to login to the Container Registry using: +1. Save the file and [restart GitLab][] for the changes to take effect. +1. 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: ```bash docker login gitlab.example.com:4567 ``` -with their GitLab credentials. - -### Container Registry under its own domain +### Configure Container Registry under its own domain If the Registry is configured to use its own domain, you will need a TLS certificate for that specific domain (e.g., `registry.example.com`) or maybe -a wildcard certificate if hosted under a subdomain (e.g., `registry.gitlab.example.com`). +a wildcard certificate if hosted under a subdomain of your existing GitLab +domain (e.g., `registry.gitlab.example.com`). Let's assume that you want the container Registry to be accessible at `https://registry.gitlab.example.com`. --- -**Omnibus GitLab packages** +**Omnibus GitLab installations** -Place your SSL certificate and key in -`/etc/gitlab/ssl/registry.gitlab.example.com.crt` -and -`/etc/gitlab/ssl/registry.gitlab.example.com.key` and make sure they have -correct permissions: +1. Place your TLS certificate and key in + `/etc/gitlab/ssl/registry.gitlab.example.com.crt` and + `/etc/gitlab/ssl/registry.gitlab.example.com.key` and make sure they have + correct permissions: -```bash -chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.* -``` + ```bash + chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.* + ``` + +1. Once the TLS certificate is in place, edit `/etc/gitlab/gitlab.rb` with: + + ```ruby + registry_external_url 'https://registry.gitlab.example.com' + ``` -Once the SSL certificate is in place, edit `/etc/gitlab/gitlab.rb` with: +1. Save the file and [reconfigure GitLab][] for the changes to take effect. +> **Note:** +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/gitlab.rb` will +look like: +> ```ruby registry_external_url 'https://registry.gitlab.example.com' +registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem" +registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" ``` -Save the file and [reconfigure GitLab][] for the changes to take effect. +--- -``` -registry: - enabled: true - host: registry.gitlab.example.com - port: 5005 - api_url: http://localhost:5000/ - key_path: config/registry.key - path: shared/registry - issuer: gitlab-issuer -``` +**Installations from source** + +1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and + configure it with the following settings: + + ``` + registry: + enabled: true + host: registry.gitlab.example.com + port: 4567 + ``` + +1. Save the file and [restart GitLab][] for the changes to take effect. +1. 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: +Users should now be able to login to the Container Registry using their GitLab +credentials: ```bash docker login registry.gitlab.example.com ``` -with their GitLab credentials. +## Disable Container Registry site-wide -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/gitlab.rb` will -look like: +**Omnibus GitLab** ```ruby -registry_external_url 'https://registry.gitlab.example.com' -registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem" -registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" +gitlab_rails['registry_enabled'] = true ``` ``` -registry: - enabled: true - host: registry.gitlab.example.com - port: 5005 - api_url: http://localhost:5000/ - key_path: config/registry.key - path: shared/registry - issuer: gitlab-issuer +# gitlab_rails['registry_port'] = "5005" +# gitlab_rails['registry_host'] = "registry.gitlab.example.com" +# gitlab_rails['registry_api_url'] = "http://localhost:5000" +# gitlab_rails['registry_key_path'] = "/var/opt/gitlab/gitlab-rails/certificate.key" +# gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry" +# gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer" + +# Settings used by Registry application +# registry['enable'] = true +# registry['username'] = "registry" +# registry['group'] = "registry" +# registry['uid'] = nil +# registry['gid'] = nil +# registry['dir'] = "/var/opt/gitlab/registry" +# registry['log_directory'] = "/var/log/gitlab/registry" +# registry['log_level'] = "info" +# registry['rootcertbundle'] = "/var/opt/gitlab/registry/certificate.crt" ``` +## Disable Container Registry per project + +If Registry is enabled in your GitLab instance, but you don't need it for your +project, you can disable it from your project's settings. Read the user guide +on how to achieve that. + +## Disable Container Registry for new projects site-wide + +The Registry is enabled by default on all new projects. To disable this function +and let the owners of a project to enable Registry by themselves, follow the +steps below. + +--- + +**Omnibus GitLab installations** + +1. Edit `/etc/gitlab/gitlab.rb` and add the following line: + + ```ruby + gitlab_rails['gitlab_default_projects_features_container_registry'] = false + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. + +--- + +**Installations from source** + +1. Open `/home/git/gitlab/config/gitlab.yml`, find the `default_projects_features` + entry and configure it so that `container_registry` is set to `false`: + + ``` + ## Default project features settings + default_projects_features: + issues: true + merge_requests: true + wiki: true + snippets: false + builds: true + container_registry: false + ``` + +1. Save the file and [restart GitLab][] for the changes to take effect. + ## Container Registry storage path It is possible to change path where containers will be stored by the Container @@ -244,41 +340,25 @@ Save the file and [reconfigure GitLab][] for the changes to take effect. **NOTE** You should confirm that the GitLab, registry and the web server user have access to this directory. -## Disable Container Registry - -**Omnibus GitLab** - -``` -# Settings used by GitLab application -# gitlab_rails['registry_enabled'] = true -``` - -``` -# gitlab_rails['registry_host'] = "registry.gitlab.example.com" -# gitlab_rails['registry_api_url'] = "http://localhost:5000" -# gitlab_rails['registry_key_path'] = "/var/opt/gitlab/gitlab-rails/certificate.key" -# gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry" -# gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer" +## Storage limitations -# Settings used by Registry application -# registry['enable'] = true -# registry['username'] = "registry" -# registry['group'] = "registry" -# registry['uid'] = nil -# registry['gid'] = nil -# registry['dir'] = "/var/opt/gitlab/registry" -# registry['log_directory'] = "/var/log/gitlab/registry" -# registry['log_level'] = "info" -# registry['rootcertbundle'] = "/var/opt/gitlab/registry/certificate.crt" -``` +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. ## Changelog +**GitLab 8.8 ([source docs][8-8-docs])** + +- GitLab Container Registry feature was introduced. -[reconfigure gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation" -[wildcard certificate]: "https://en.wikipedia.org/wiki/Wildcard_certificate" +[reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure +[restart gitlab]: restart_gitlab.md#installations-from-source +[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 +[registry-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/nginx/registry-ssl |