Merge branch 'eread/refactor-external-storage-admin-area-config' into 'master'

Refactor external storage admin area configuration UI and docs

See merge request gitlab-org/gitlab!66219

app/views/admin/application_settings/_repository_static_objects.html.haml

@@ -7,12 +7,12 @@
         = _('External storage URL')
       = f.text_field :static_objects_external_storage_url, class: 'form-control gl-form-input'
       %span.form-text.text-muted#static_objects_external_storage_url_help_block
-        = _('URL of the external storage that will serve the repository static objects (e.g. archives, blobs, ...).')
+        = _('URL of the external storage to serve the repository static objects.')
     .form-group
       = f.label :static_objects_external_storage_auth_token, class: 'label-bold' do
         = _('External storage authentication token')
       = f.text_field :static_objects_external_storage_auth_token, class: 'form-control gl-form-input'
       %span.form-text.text-muted#static_objects_external_storage_auth_token_help_block
-        = _('A secure token that identifies an external storage request.')
+        = _('Secure token that identifies an external storage request.')
 
   = f.submit _('Save changes'), class: "gl-button btn btn-confirm"

app/views/admin/application_settings/repository.html.haml

@@ -55,10 +55,11 @@
 %section.settings.as-repository-static-objects.no-animate#js-repository-static-objects-settings{ class: ('expanded' if expanded_by_default?) }
   .settings-header
     %h4
-      = _('Repository static objects')
+      = _('External storage for repository static objects')
     %button.btn.gl-button.btn-default.js-settings-toggle{ type: 'button' }
       = expanded_by_default? ? _('Collapse') : _('Expand')
     %p
-      = _('Serve repository static objects (e.g. archives, blobs, ...) from an external storage (e.g. a CDN).')
+      = _('Serve repository static objects (for example, archives and blobs) from external storage.')
+      = link_to s_('Learn more.'), help_page_path('administration/static_objects_external_storage.md'), target: '_blank', rel: 'noopener noreferrer'
   .settings-content
     = render 'repository_static_objects'

doc/administration/static_objects_external_storage.md

@@ -5,22 +5,23 @@ info: "To determine the technical writer assigned to the Stage/Group associated
 type: reference
 ---
 
-# Static objects external storage **(FREE)**
+# External storage for static objects **(FREE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31025) in GitLab 12.3.
 
-You can configure GitLab to serve repository static objects, like archives or raw blobs,
-from an external storage, such as a Content Delivery Network (CDN).
+Configure GitLab to serve repository static objects (such as archives or raw blobs) from external
+storage such as a content delivery network (CDN).
 
-## Configuring
+## Configure external storage
 
 To configure external storage for static objects:
 
 1. On the top bar, select **Menu >** **{admin}** **Admin**.
 1. In the left sidebar, select **Settings > Repository**.
-1. Expand the **Repository static objects** section.
+1. Expand the **External storage for repository static objects** section.
 1. Enter the base URL and an arbitrary token. When you [set up external storage](#set-up-external-storage),
    use a script that sets these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`.
+1. Select **Save changes**.
 
 The token is required to distinguish requests coming from the external storage, so users don't
 circumvent the external storage and access the application directly. GitLab expects
@@ -29,18 +30,23 @@ originating from the external storage.
 
 ## Serving private static objects
 
-GitLab appends a user-specific token for static object URLs belonging to private projects,
-so an external storage can be authenticated on the user's behalf. When processing requests originating
-from the external storage, GitLab checks the following places to confirm the user may
-access the requested object:
+GitLab appends a user-specific token for static object URLs belonging to private projects so
+external storage can be authenticated on the user's behalf.
+
+When processing requests originating
+from the external storage, GitLab checks the following to confirm the user may access the requested
+object:
 
 - The `token` query parameter.
 - The `X-Gitlab-Static-Object-Token` header.
 
 ## Requests flow example
 
-The following example shows a sequence of requests and responses between the user,
-GitLab, and the CDN:
+The following example shows a sequence of requests and responses between:
+
+- The user.
+- GitLab.
+- The content delivery network.
 
 ```mermaid
 sequenceDiagram
@@ -72,7 +78,7 @@ other CDNs or Function as a Service (FaaS) systems should work using the same pr
    - `ORIGIN_HOSTNAME`: the hostname of your GitLab installation.
    - `STORAGE_TOKEN`: any arbitrary secure token. You can get a token by running
      `pwgen -cn1 64` on a UNIX machine. Save this token for the Admin Area, as
-     described in the [configuring](#configuring) section.
+     described in the [configuring](#configure-external-storage) section.
 
      ```javascript
      const ORIGIN_HOSTNAME = 'gitlab.installation.com' // FIXME: SET CORRECT VALUE
@@ -229,4 +235,4 @@ other CDNs or Function as a Service (FaaS) systems should work using the same pr
 
 1. Create a new worker with this script.
 1. Copy your values for `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`.
-   Use those values [to configure external storage for static objects](#configuring).
+   Use those values [to configure external storage for static objects](#configure-external-storage).

doc/user/admin_area/settings/index.md

@@ -54,7 +54,7 @@ To access the default page for Admin Area settings:
 | [Repository mirror](visibility_and_access_controls.md#allow-mirrors-to-be-set-up-for-projects) | Configure repository mirroring. |
 | [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. |
 | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. |
-| [Repository static objects](../../../administration/static_objects_external_storage.md) | Serve repository static objects (for example, archives, blobs, ...) from an external storage (for example, a CDN). |
+| [Repository static objects](../../../administration/static_objects_external_storage.md) | Serve repository static objects (for example, archives and blobs) from an external storage (for example, a CDN). |
 
 ## Templates **(PREMIUM SELF)**
 

locale/gitlab.pot

@@ -1501,9 +1501,6 @@ msgstr ""
 msgid "A rebase is already in progress."
 msgstr ""
 
-msgid "A secure token that identifies an external storage request."
-msgstr ""
-
 msgid "A sign-in to your account has been made from the following IP address: %{ip}"
 msgstr ""
 
@@ -13389,6 +13386,9 @@ msgstr ""
 msgid "External storage authentication token"
 msgstr ""
 
+msgid "External storage for repository static objects"
+msgstr ""
+
 msgid "ExternalAuthorizationService|Classification label"
 msgstr ""
 
@@ -27713,9 +27713,6 @@ msgstr ""
 msgid "Repository size is above the limit."
 msgstr ""
 
-msgid "Repository static objects"
-msgstr ""
-
 msgid "Repository storage"
 msgstr ""
 
@@ -28829,6 +28826,9 @@ msgstr ""
 msgid "Secret token"
 msgstr ""
 
+msgid "Secure token that identifies an external storage request."
+msgstr ""
+
 msgid "Security"
 msgstr ""
 
@@ -29627,7 +29627,7 @@ msgstr ""
 msgid "SeriesFinalConjunction|and"
 msgstr ""
 
-msgid "Serve repository static objects (e.g. archives, blobs, ...) from an external storage (e.g. a CDN)."
+msgid "Serve repository static objects (for example, archives and blobs) from external storage."
 msgstr ""
 
 msgid "Server supports batch API only, please update your Git LFS client to version 1.0.1 and up."
@@ -34815,7 +34815,7 @@ msgstr ""
 msgid "URL of the external Spam Check endpoint"
 msgstr ""
 
-msgid "URL of the external storage that will serve the repository static objects (e.g. archives, blobs, ...)."
+msgid "URL of the external storage to serve the repository static objects."
 msgstr ""
 
 msgid "URL or request ID"