From 0cdc080a4a4d8146f6c874c91b8bff6960214c56 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 20 May 2016 13:18:18 -0500 Subject: [PATCH] Refactor container docs --- doc/administration/container_registry.md | 181 ++++++++++++++++++----- 1 file changed, 148 insertions(+), 33 deletions(-) diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index 17a0c229b97..15c3c1a7470 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -3,11 +3,18 @@ > **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. + +You can read more about Docker Registry at https://docs.docker.com/registry/introduction/. + +--- + **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* -- [Assumptions](#assumptions) +- [Differences between Omnibus and source installations](#differences-between-omnibus-and-source-installations) - [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) @@ -17,67 +24,110 @@ This feature was [introduced][ce-4040] in GitLab 8.8. -## Assumptions + +## Differences between Omnibus and source installations If you are using Omnibus, you have to bare in mind the following: - The container Registry will be enabled by default if GitLab is configured with HTTPS and it will listen on port `5005`. If you want the Registry to - listen on a port other than `5005` which is the default, read [#Container Registry under existing GitLab domain](#container-registry-under-existing-gitlab-domain) + listen on a port other than `5005`, read [#Container Registry under existing GitLab domain](#container-registry-under-existing-gitlab-domain) 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. Note that using HTTP is - possible but not recommended and out of the scope of this document, +- 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 implement this. +--- + +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`. + +The contents of `gitlab.yml` are: + +``` +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 +``` + +where: + +| Parameter | Description | +| --------- | ----------- | +| `enabled` | 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]. | +| `issuer` | This should be the same value as configured in Registry's `issuer`. Read the [token auth configuration documentation][token-config]. | + ## Container Registry domain configuration -There are two ways you can configure the container Registry domain. Either use +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. -1. 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`). -1. 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 - certificate. - Please take this into consideration before configuring the Container Registry for the first time. -Read more about Docker Registry at https://docs.docker.com/registry/introduction/. - ### Container Registry under existing GitLab domain -Lets assume that your GitLab instance is accessible at -`https://gitlab.example.com`. You can expose the Container Registry under -a separate port. +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 +certificate. -Lets assume that you've exposed port `4567` in your network firewall. +Assuming that the GitLab domain is `https://gitlab.example.com` and the port the +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** +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. + + ```ruby + 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 + + # 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. + --- -Your `/etc/gitlab/gitlab.rb` should contain the Container Registry URL as -well as the path to the existing SSL certificate and key used by GitLab. +**Installation from source** -```ruby -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 - -# registry_nginx['ssl_certificate'] = "/path/to/certificate.pem" -# registry_nginx['ssl_certificate_key'] = "/path/to/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 +``` Users should now be able to login to the Container Registry using: @@ -89,7 +139,11 @@ with their GitLab credentials. ### Container Registry under its own domain -Lets assume that you want the Container Registry to be accessible at +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`). + +Let's assume that you want the container Registry to be accessible at `https://registry.gitlab.example.com`. --- @@ -114,6 +168,17 @@ registry_external_url 'https://registry.gitlab.example.com' 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 +``` + Users should now be able to login to the Container Registry using: ```bash @@ -132,6 +197,17 @@ registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem" registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" ``` +``` +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 +``` + ## Container Registry storage path It is possible to change path where containers will be stored by the Container @@ -152,6 +228,17 @@ In `/etc/gitlab/gitlab.rb`: gitlab_rails['registry_path'] = "/path/to/registry/storage" ``` +``` +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 +``` + 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 @@ -159,6 +246,31 @@ 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" + +# 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" +``` ## Changelog @@ -167,3 +279,6 @@ have access to this directory. [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