Enable serving static objects from an external storagestatic-objects-external-storage

It consists of two parts:

1. Redirecting users to the configured external storage
1. Allowing the external storage to request the static object(s)
   on behalf of the user by means of specific tokens

Part of https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/6829

1 files changed, 50 insertions, 0 deletions

diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md
new file mode 100644
index 00000000000..e4d60c77199
--- /dev/null
+++ b/doc/administration/static_objects_external_storage.md
@@ -0,0 +1,50 @@
+# Static objects external storage
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/31025) in GitLab 12.3.
+
+GitLab can be configured to serve repository static objects (for example, archives) from an external
+storage, such as a CDN.
+
+## Configuring
+
+To configure external storage for static objects:
+
+1. Navigate to **Admin Area > Settings > Repository**.
+1. Expand the **Repository static objects** section.
+1. Enter the base URL and an arbitrary token.
+
+The token is required to distinguish requests coming from the external storage, so users don't
+circumvent the external storage and go for the application directly. The token is expected to be
+set in the `X-Gitlab-External-Storage-Token` header in requests originating from the external
+storage.
+
+## Serving private static objects
+
+GitLab will append a user-specific token for static object URLs that belong to private projects,
+so an external storage can be authenticated on behalf of the user. When processing requests originating
+from the external storage, GitLab will look for the token in the `token` query parameter or in
+the `X-Gitlab-Static-Object-Token` header to check the user's ability to access the requested object.
+
+## Requests flow example
+
+The following example shows a sequence of requests and responses between the user,
+GitLab, and the CDN:
+
+```mermaid
+sequenceDiagram
+    User->>GitLab: GET /project/-/archive/master.zip
+    GitLab->>User: 302 Found
+    Note over User,GitLab: Location: https://cdn.com/project/-/archive/master.zip?token=secure-user-token
+    User->>CDN: GET /project/-/archive/master.zip?token=secure-user-token
+    alt object not in cache
+      CDN->>GitLab: GET /project/-/archive/master.zip
+      Note over CDN,GitLab: X-Gitlab-External-Storage-Token: secure-cdn-token<br/>X-Gitlab-Static-Object-Token: secure-user-token
+      GitLab->>CDN: 200 OK
+      CDN->>User: master.zip
+    else object in cache
+      CDN->>GitLab: GET /project/-/archive/master.zip
+      Note over CDN,GitLab: X-Gitlab-External-Storage-Token: secure-cdn-token<br/>X-Gitlab-Static-Object-Token: secure-user-token<br/>If-None-Match: etag-value
+      GitLab->>CDN: 304 Not Modified
+      CDN->>User: master.zip
+    end
+```