Major overhaul of the Registry admin docs
This commit is contained in:
parent
c1af75192d
commit
e9817f21f4
|
@ -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.
|
||||
|
||||
---
|
||||
|
||||
If you have installed GitLab from source:
|
||||
- Omnibus has some things configured for you
|
||||
**Installations from source**
|
||||
|
||||
- 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`.
|
||||
If you have installed GitLab from source:
|
||||
|
||||
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:
|
||||
|
||||
Users should now be able to login to the Container Registry using:
|
||||
```
|
||||
registry:
|
||||
enabled: true
|
||||
host: 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 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.*
|
||||
```
|
||||
|
||||
Once the SSL certificate is in place, edit `/etc/gitlab/gitlab.rb` with:
|
||||
1. Once the TLS certificate is in place, edit `/etc/gitlab/gitlab.rb` with:
|
||||
|
||||
```ruby
|
||||
registry_external_url 'https://registry.gitlab.example.com'
|
||||
```
|
||||
```ruby
|
||||
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
|
||||
docker login registry.gitlab.example.com
|
||||
```
|
||||
|
||||
with their GitLab credentials.
|
||||
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"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**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 their GitLab
|
||||
credentials:
|
||||
|
||||
```bash
|
||||
docker login registry.gitlab.example.com
|
||||
```
|
||||
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
|
||||
|
||||
## Disable Container Registry site-wide
|
||||
|
||||
**Omnibus GitLab**
|
||||
|
||||
```ruby
|
||||
gitlab_rails['registry_enabled'] = true
|
||||
```
|
||||
|
||||
```
|
||||
# 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
|
||||
## Storage limitations
|
||||
|
||||
**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"
|
||||
```
|
||||
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])**
|
||||
|
||||
[reconfigure gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
|
||||
[wildcard certificate]: "https://en.wikipedia.org/wiki/Wildcard_certificate"
|
||||
- GitLab Container Registry feature was introduced.
|
||||
|
||||
[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
|
||||
|
|
Loading…
Reference in New Issue