Merge branch '217913-update-pages-admin-docs-deprecation' into 'master'

Deprecate domain_config_source for GitLab Pages

See merge request gitlab-org/gitlab!53689

doc/administration/pages/index.md

@@ -689,7 +689,7 @@ Pages server.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217912) in GitLab 13.3.
 
 GitLab Pages can use different sources to get domain configuration.
-The default value is `nil`. However, GitLab Pages defaults to `auto`.
+The default value for Omnibus installations is `nil`.
 
    ```ruby
    gitlab_pages['domain_config_source'] = nil
@@ -700,8 +700,33 @@ preferred source is `gitlab`, which uses [API-based configuration](#gitlab-api-b
 
 For more details see this [blog post](https://about.gitlab.com/blog/2020/08/03/how-gitlab-pages-uses-the-gitlab-api-to-serve-content/).
 
+### Deprecated domain_config_source
+
+WARNING:
+The flag `gitlab_pages['domain_config_source']` is deprecated for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913),
+and is planned for removal in GitLab 14.0.
+
+GitLab 13.0 introduced the special flag `domain_config_source` to support manual opt-in to
+[API-based configuration](#gitlab-api-based-configuration).
+GitLab 13.7 introduced the [`auto` value](https://gitlab.com/gitlab-org/gitlab/-/issues/218358)
+to support a smoother transition to API-based configuration.
+
+Starting with GitLab 14.0, GitLab Pages only supports API-based configuration, and
+[disk source configuration is removed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/382).
+Therefore, GitLab 14.0 also removes `domain_config_source`.
+
+GitLab Pages fails to start if it can't connect to the GitLab API. For other common issues, see the
+[troubleshooting section](#failed-to-connect-to-the-internal-gitlab-api)
+or report an issue.
+
 ### GitLab API-based configuration
 
+WARNING:
+The flag `gitlab_pages['domain_config_source']` is deprecated for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913),
+and is planned for removal in GitLab 14.0. In GitLab 14.0 and later, GitLab Pages attempts to
+connect to the API automatically, without requiring the manual configuration steps shown here. Pages
+fails to start if this automatic connection fails.
+
 GitLab Pages can use an API-based configuration. This replaces disk source configuration, which
 was used prior to GitLab 13.0. Follow these steps to enable it:
 
@@ -937,6 +962,11 @@ error="failed to connect to internal Pages API: Get \"https://gitlab.example.com
 
 ### Pages cannot communicate with an instance of the GitLab API
 
+WARNING:
+The flag `gitlab_pages['domain_config_source']` is [deprecated](#deprecated-domain_config_source)
+for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913),
+and is planned for removal in GitLab 14.0.
+
 If you use the default value for `domain_config_source=auto` and run multiple instances of GitLab
 Pages, you may see intermittent 502 error responses while serving Pages content. You may also see
 the following warning in the Pages logs: