Merge branch 'custom-registry-storage-docs' into 'master'

Add documentation and examples for configuring cloud storage for registry images.

## What does this MR do?
Adds documentation and examples for configuring cloud storage for registry images.

Waits for backend config to get merged in:
https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/816

## What are the relevant issue numbers?

https://gitlab.com/gitlab-org/omnibus-gitlab/issues/1320
## Does this MR meet the acceptance criteria?

- [ ] ~~[CHANGELOG](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CHANGELOG) entry added~~
- [x] [Documentation created/updated](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/doc_styleguide.md)
- [ ] ~~API support added~~
- [ ] Tests
  - [ ] ~~Added for this feature/bug~~
  - [x] All builds are passing
- [ ] Conform by the [style guides](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#style-guides)
- [ ] Branch has no merge conflicts with `master` (if you do - rebase it please)
- [ ] [Squashed related commits together](https://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits)

cc\ @marin

See merge request !4812
Signed-off-by: Rémy Coutable <remy@rymai.me>

CHANGELOG

@@ -8,6 +8,7 @@ v 8.9.1 (unreleased)
   - Add some docs for Docker Registry configuration. !4738
   - Ensure we don't send the "access request declined" email to access requesters on project deletion. !4744
   - Display group/project access requesters separately in the admin area. !4798
+  - Add documentation and examples for configuring cloud storage for registry images. !4812
   - Fix MR-auto-close text added to description. !4836
   - Fix typo in export failure email. !4847
 

doc/administration/container_registry.md

@@ -22,6 +22,7 @@ You can read more about Docker Registry at https://docs.docker.com/registry/intr
 - [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)
+- [Container Registry storage driver](#container-registry-storage-driver)
 - [Storage limitations](#storage-limitations)
 - [Changelog](#changelog)
 
@@ -317,8 +318,12 @@ the Container Registry by themselves, follow the steps below.
 
 ## Container Registry storage path
 
-To change the storage path where Docker images will be stored, follow the
-steps below.
+>**Note:**
+For configuring storage in the cloud instead of the filesystem, see the
+[storage driver configuration](#container-registry-storage-driver).
+
+If you want to store your images on the filesystem, you can change the storage
+path for the Container Registry, follow the steps below.
 
 This path is accessible to:
 
@@ -360,6 +365,72 @@ The default location where images are stored in source installations, is
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
+## 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.
+
+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.
+
+---
+
+**Omnibus GitLab installations**
+
+To configure the storage driver in Omnibus:
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+    ```ruby
+    registry['storage'] = {
+      's3' => {
+        'accesskey' => 's3-access-key',
+        'secretkey' => 's3-secret-key-for-access-key',
+        'bucket' => 'your-s3-bucket'
+      }
+    }
+    ```
+
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+---
+
+**Installations from source**
+
+Configuring the storage driver is done in your registry config YML file created
+when you [deployed your docker registry][registry-deploy].
+
+Example:
+
+```
+storage:
+  s3:
+    accesskey: 'AKIAKIAKI'
+    secretkey: 'secret123'
+    bucket: 'gitlab-registry-bucket-AKIAKIAKI'
+  cache:
+    blobdescriptor: inmemory
+  delete:
+    enabled: true
+```
+
 ## Storage limitations
 
 Currently, there is no storage limitation, which means a user can upload an