SSoT for administration/high_availability docs

- Make sure we have type defined in the frontmatter
- Add troubleshooting sections where absent
- Meaningful intros where absent

13 files changed, 115 insertions, 7 deletions

diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md
index 4317d14ba68..41ef68f5b57 100644
--- a/doc/administration/high_availability/README.md
+++ b/doc/administration/high_availability/README.md
@@ -1,3 +1,7 @@
+---
+type: reference, concepts
+---
+
 # Scaling and High Availability
 
 GitLab supports several different types of clustering and high-availability.
diff --git a/doc/administration/high_availability/alpha_database.md b/doc/administration/high_availability/alpha_database.md
index 7bf20be60e6..7afd739f44c 100644
--- a/doc/administration/high_availability/alpha_database.md
+++ b/doc/administration/high_availability/alpha_database.md
@@ -2,5 +2,4 @@
 redirect_to: 'database.md'
 ---
 
-This documentation has been moved to the main
-[database documentation](database.md#configure_using_omnibus_for_high_availability).
+This document was moved to [another location](database.md).
diff --git a/doc/administration/high_availability/consul.md b/doc/administration/high_availability/consul.md
index 1f93c8130d3..b02a61b9256 100644
--- a/doc/administration/high_availability/consul.md
+++ b/doc/administration/high_availability/consul.md
@@ -1,6 +1,8 @@
-# Working with the bundled Consul service **(PREMIUM ONLY)**
+---
+type: reference
+---
 
-## Overview
+# Working with the bundled Consul service **(PREMIUM ONLY)**
 
 As part of its High Availability stack, GitLab Premium includes a bundled version of [Consul](https://www.consul.io/) that can be managed through `/etc/gitlab/gitlab.rb`.
 
diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md
index 1702a731647..f7a1f425b40 100644
--- a/doc/administration/high_availability/database.md
+++ b/doc/administration/high_availability/database.md
@@ -1,5 +1,12 @@
+---
+type: reference
+---
+
 # Configuring PostgreSQL for Scaling and High Availability
 
+In this section, you'll be guided through configuring a PostgreSQL database
+to be used with GitLab in a highly available environment.
+
 ## Provide your own PostgreSQL instance **(CORE ONLY)**
 
 If you're hosting GitLab on a cloud provider, you can optionally use a
diff --git a/doc/administration/high_availability/gitaly.md b/doc/administration/high_availability/gitaly.md
index b7eaa4ce105..739d1ae35fb 100644
--- a/doc/administration/high_availability/gitaly.md
+++ b/doc/administration/high_availability/gitaly.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Configuring Gitaly for Scaled and High Availability
 
 Gitaly does not yet support full high availability. However, Gitaly is quite
@@ -46,3 +50,15 @@ Continue configuration of other components by going back to:
    ```
 
 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md
index 83838928519..8818a9606de 100644
--- a/doc/administration/high_availability/gitlab.md
+++ b/doc/administration/high_availability/gitlab.md
@@ -1,4 +1,8 @@
-# Configuring GitLab Scaling and High Availability
+---
+type: reference
+---
+
+# Configuring GitLab for Scaling and High Availability
 
 > **Note:** There is some additional configuration near the bottom for
   additional GitLab application servers. It's important to read and understand
diff --git a/doc/administration/high_availability/load_balancer.md b/doc/administration/high_availability/load_balancer.md
index 28b226cacd5..9e9f604317a 100644
--- a/doc/administration/high_availability/load_balancer.md
+++ b/doc/administration/high_availability/load_balancer.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Load Balancer for GitLab HA
 
 In an active/active GitLab configuration, you will need a load balancer to route
@@ -114,3 +118,15 @@ Read more on high-availability configuration:
       if SSL was terminated at the load balancer.
 
 [gitlab-pages]: ../pages/index.md
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/monitoring_node.md b/doc/administration/high_availability/monitoring_node.md
index cbc1d4bcd52..b91a994d01e 100644
--- a/doc/administration/high_availability/monitoring_node.md
+++ b/doc/administration/high_availability/monitoring_node.md
@@ -1,7 +1,13 @@
+---
+type: reference
+---
+
 # Configuring a Monitoring node for Scaling and High Availability
 
 > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0.
 
+You can configure a Prometheus node to monitor GitLab.
+
 ## Standalone Monitoring node using GitLab Omnibus
 
 The GitLab Omnibus package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md).
@@ -67,3 +73,15 @@ Once monitoring using Service Discovery is enabled with `consul['monitoring_serv
 ensure that `prometheus['scrape_configs']` is not set  in `/etc/gitlab/gitlab.rb`. Setting both
 `consul['monitoring_service_discovery'] =  true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb`
 will result in errors.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md
index 6ab6b8bed30..ea8302f6086 100644
--- a/doc/administration/high_availability/nfs.md
+++ b/doc/administration/high_availability/nfs.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # NFS
 
 You can view information and options set for each of the mounted NFS file
@@ -236,3 +240,15 @@ Read more on high-availability configuration:
 1. [Configure the load balancers](load_balancer.md)
 
 [udp-log-shipping]: https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only "UDP log shipping"
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/nfs_host_client_setup.md b/doc/administration/high_availability/nfs_host_client_setup.md
index a8d69b9ab0a..9b0e085fe25 100644
--- a/doc/administration/high_availability/nfs_host_client_setup.md
+++ b/doc/administration/high_availability/nfs_host_client_setup.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Configuring NFS for GitLab HA
 
 Setting up NFS for a GitLab HA setup allows all applications nodes in a cluster
@@ -133,3 +137,15 @@ client with the command below.
 ```sh
 sudo ufw allow from <client-ip-address> to any port nfs
 ```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/high_availability/pgbouncer.md b/doc/administration/high_availability/pgbouncer.md
index 6890b0f7db7..0b945bc6244 100644
--- a/doc/administration/high_availability/pgbouncer.md
+++ b/doc/administration/high_availability/pgbouncer.md
@@ -1,6 +1,8 @@
-# Working with the bundle Pgbouncer service
+---
+type: reference
+---
 
-## Overview
+# Working with the bundle Pgbouncer service
 
 As part of its High Availability stack, GitLab Premium includes a bundled version of [Pgbouncer](https://pgbouncer.github.io/) that can be managed through `/etc/gitlab/gitlab.rb`.
 
diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index c29514ed9f6..1b79dde9476 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Configuring Redis for Scaling and High Availability
 
 ## Provide your own Redis instance **(CORE ONLY)**
diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index a5463e5128c..63915e5d96c 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Configuring non-Omnibus Redis for GitLab HA
 
 This is the documentation for configuring a Highly Available Redis setup when