Merge branch 'pages-object-storage-settings-docs' into 'master'

Document pages object storage settings

See merge request gitlab-org/gitlab!45279

doc/administration/object_storage.md

@@ -114,6 +114,7 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details.
     gitlab_rails['object_store']['objects']['packages']['bucket'] = '<packages>'
     gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = '<dependency-proxy>'
     gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = '<terraform-state>'
+    gitlab_rails['object_store']['objects']['pages']['bucket'] = '<pages>'
     ```
 
    For GitLab 9.4 or later, if you're using AWS IAM profiles, be sure to omit the
@@ -160,6 +161,8 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details.
          bucket: <dependency_proxy>
        terraform_state:
          bucket: <terraform>
+       pages:
+         bucket: <pages>
    ```
 
 1. Edit `/home/git/gitlab-workhorse/config.toml` and add or amend the following lines:
@@ -440,6 +443,8 @@ required parameter within each type:
           bucket: dependency_proxy
         terraform_state:
           bucket: terraform
+        pages:
+          bucket: pages
 ```
 
 This maps to this Omnibus GitLab configuration:
@@ -454,6 +459,7 @@ gitlab_rails['object_store']['objects']['packages']['bucket'] = 'packages'
 gitlab_rails['object_store']['objects']['dependency_proxy']['enabled'] = false
 gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'dependency-proxy'
 gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'terraform-state'
+gitlab_rails['object_store']['objects']['pages']['bucket'] = 'pages'
 ```
 
 This is the list of valid `objects` that can be used:
@@ -467,6 +473,7 @@ This is the list of valid `objects` that can be used:
 | `packages`         | [Project packages (e.g. PyPI, Maven, NuGet, etc.)](packages/index.md) |
 | `dependency_proxy` | [GitLab Dependency Proxy](packages/dependency_proxy.md) |
 | `terraform_state`  | [Terraform state files](terraform_state.md) |
+| `pages`            | [GitLab Pages](pages/index.md) |
 
 Within each object type, three parameters can be defined:
 
@@ -548,6 +555,7 @@ supported by consolidated configuration form, refer to the following guides:
 | [Pseudonymizer](pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No |
 | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No |
 | [Terraform state files](terraform_state.md#using-object-storage) | Yes |
+| [GitLab Pages content](pages/index.md#using-object-storage) | Yes |
 
 ### Other alternatives to filesystem storage
 

doc/administration/pages/index.md

@@ -700,6 +700,77 @@ gitlab_pages['domain_config_source'] = nil
 For other common issues, see the [troubleshooting section](#failed-to-connect-to-the-internal-gitlab-api)
 or report an issue.
 
+## Using object storage
+
+> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5577) in GitLab 13.6.
+
+[Read more about using object storage with GitLab](../object_storage.md).
+
+### Object storage settings
+
+The following settings are:
+
+- Nested under `pages:` and then `object_store:` on source installations.
+- Prefixed by `pages_object_store_` on Omnibus GitLab installations.
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `enabled` | Whether object storage is enabled. | `false` |
+| `remote_directory` | The name of the bucket where Pages site content is stored. | |
+| `connection` | Various connection options described below. | |
+
+#### S3-compatible connection settings
+
+See [the available connection settings for different providers](../object_storage.md#connection-settings).
+
+In Omnibus installations:
+
+1. Add the following lines to `/etc/gitlab/gitlab.rb` and replace the values with the ones you want:
+
+   ```ruby
+   gitlab_rails['pages_object_store_enabled'] = true
+   gitlab_rails['pages_object_store_remote_directory'] = "pages"
+   gitlab_rails['pages_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
+     'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
+   }
+   ```
+
+   If you use AWS IAM profiles, be sure to omit the AWS access key and secret access key/value
+   pairs:
+
+   ```ruby
+   gitlab_rails['pages_object_store_connection'] = {
+     'provider' => 'AWS',
+     'region' => 'eu-central-1',
+     'use_iam_profile' => true
+   }
+   ```
+
+1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure)
+   for the changes to take effect.
+
+In installations from source:
+
+1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
+
+   ```yaml
+   pages:
+     object_store:
+       enabled: true
+       remote_directory: "pages" # The bucket name
+       connection:
+         provider: AWS # Only AWS supported at the moment
+         aws_access_key_id: AWS_ACESS_KEY_ID
+         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
+         region: eu-central-1
+   ```
+
+1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source)
+   for the changes to take effect.
+
 ## Backup
 
 GitLab Pages are part of the [regular backup](../../raketasks/backup_restore.md), so there is no separate backup to configure.