Merge branch 'mek/availability-trade-offs' into 'master'

Create new reference architectures page

See merge request gitlab-org/gitlab!30781

doc/README.md

@@ -23,10 +23,11 @@ No matter how you use GitLab, we have documentation for you.
 | Essential Documentation                                                                                                                    | Essential Documentation                                                                                                    |
 |:-------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------|
 | [**User Documentation**](user/index.md)<br/>Discover features and concepts for GitLab users.                                               | [**Administrator documentation**](administration/index.md)<br/>Everything GitLab self-managed administrators need to know. |
-| [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute!                                              | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have the resources to get you started.                             |
+| [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute!                                              | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have the resources to get you started.                         |
 | [**Building an integration with GitLab?**](#building-an-integration-with-gitlab)<br/>Consult our automation and integration documentation. | [**Coming to GitLab from another platform?**](#coming-to-gitlab-from-another-platform)<br/>Consult our handy guides.       |
 | [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms.                                  | [**Customers**](subscriptions/index.md)<br/>Information for new and existing customers.                                    |
-| [**Update GitLab**](update/README.md)<br/>Update your GitLab self-managed instance to the latest version.                                  | [**GitLab Releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab.                                        |
+| [**Update GitLab**](update/README.md)<br/>Update your GitLab self-managed instance to the latest version.                                  | [**Reference Architectures**](administration/reference_architectures/index.md)<br/>GitLab's reference architectures       |
+| [**GitLab Releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab.                                                        |                                                                                                                            |
 
 ## Popular Documentation
 

doc/administration/availability/index.md

 ---
-type: reference, concepts
+redirect_to: ../reference_architectures/index.md
 ---
 
-# Availability
-
-GitLab offers a number of options to manage availability and resiliency. Below are the options to consider with trade-offs.
-
-| Event | GitLab Feature | Recovery Point Objective (RPO) | Recovery Time Objective (RTO) | Cost |
-| ----- | -------------- | --- | --- | ---- |
-| Availability Zone failure | "GitLab HA" | No loss | No loss | 2x Git storage, multiple nodes balanced across AZ's |
-| Region failure | [GitLab Geo Disaster Recovery](../geo/disaster_recovery/index.md) | 5-10 minutes | 30 minutes | 2x primary cost |
-| All failures | Backup/Restore | Last backup | Hours to Days | Cost of storing the backups |
+This document was moved to [another location](../reference_architectures/index.md).

doc/administration/file_hooks.md

@@ -35,7 +35,7 @@ Follow the steps below to set up a custom hook:
    `/home/git/gitlab/file_hooks/`. For Omnibus installs the path is
    usually `/opt/gitlab/embedded/service/gitlab-rails/file_hooks`.
 
-    For [highly available](availability/index.md) configurations, your hook file should exist on each
+    For [highly available](reference_architectures/index.md) configurations, your hook file should exist on each
     application server.
 
 1. Inside the `file_hooks` directory, create a file with a name of your choice,

doc/administration/geo/replication/external_database.md

@@ -143,7 +143,7 @@ To configure the connection to the external read-replica database and enable Log
 database to keep track of replication status and automatically recover from
 potential replication issues. Omnibus automatically configures a tracking database
 when `roles ['geo_secondary_role']` is set. For high availability,
-refer to [Geo High Availability](../../availability/index.md).
+refer to [Geo High Availability](../../reference_architectures/index.md).
 If you want to run this database external to Omnibus, please follow the instructions below.
 
 The tracking database requires an [FDW](https://www.postgresql.org/docs/9.6/postgres-fdw.html)

doc/administration/geo/replication/high_availability.md

@@ -47,12 +47,12 @@ It is possible to use cloud hosted services for PostgreSQL and Redis, but this i
 ## Prerequisites: Two working GitLab HA clusters
 
 One cluster will serve as the **primary** node. Use the
-[GitLab HA documentation](../../availability/index.md) to set this up. If
+[GitLab HA documentation](../../reference_architectures/index.md) to set this up. If
 you already have a working GitLab instance that is in-use, it can be used as a
 **primary**.
 
 The second cluster will serve as the **secondary** node. Again, use the
-[GitLab HA documentation](../../availability/index.md) to set this up.
+[GitLab HA documentation](../../reference_architectures/index.md) to set this up.
 It's a good idea to log in and test it, however, note that its data will be
 wiped out as part of the process of replicating from the **primary**.
 
@@ -371,7 +371,7 @@ more information.
 
 The minimal reference architecture diagram above shows all application services
 running together on the same machines. However, for high availability we
-[strongly recommend running all services separately](../../availability/index.md).
+[strongly recommend running all services separately](../../reference_architectures/index.md).
 
 For example, a Sidekiq server could be configured similarly to the frontend
 application servers above, with some changes to run only the `sidekiq` service:

doc/administration/geo/replication/index.md

@@ -2,7 +2,7 @@
 
 > - Introduced in GitLab Enterprise Edition 8.9.
 > - Using Geo in combination with
->   [High Availability](../../availability/index.md)
+>   [High Availability](../../reference_architectures/index.md)
 >   is considered **Generally Available** (GA) in
 >   [GitLab Premium](https://about.gitlab.com/pricing/) 10.4.
 

doc/administration/high_availability/README.md

 ---
-type: reference, concepts
+redirect_to: ../reference_architectures/index.md
 ---
 
-The page have been deprecated, please see:
+# Reference Architectures
 
-1. [Availability page](../availability/index.md)
-1. [Scaling page](../scaling/index.md)
-1. [Docs page for high availability](./gitlab.md)
-1. [High availability solutions page](https://about.gitlab.com/solutions/high-availability/)
+This document was moved to [another location](../reference_architectures/index.md).

doc/administration/high_availability/database.md

@@ -24,7 +24,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL:
 
 ## PostgreSQL in a Scaled and Highly Available Environment
 
-This section is relevant for [Scalable and Highly Available Setups](../scaling/index.md).
+This section is relevant for [Scalable and Highly Available Setups](../reference_architectures/index.md).
 
 ### Provide your own PostgreSQL instance **(CORE ONLY)**
 

doc/administration/high_availability/gitaly.md

@@ -11,7 +11,7 @@ should consider using Gitaly on a separate node.
 See the [Gitaly HA Epic](https://gitlab.com/groups/gitlab-org/-/epics/289) to
 track plans and progress toward high availability support.
 
-This document is relevant for [Scalable and Highly Available Setups](../scaling/index.md).
+This document is relevant for [scalable and highly available setups](../reference_architectures/index.md).
 
 ## Running Gitaly on its own server
 
@@ -19,7 +19,7 @@ See [Running Gitaly on its own server](../gitaly/index.md#running-gitaly-on-its-
 in Gitaly documentation.
 
 Continue configuration of other components by going back to the
-[Scaling](../scaling/index.md#components-provided-by-omnibus-gitlab) page.
+[reference architecture](../reference_architectures/index.md#configure-gitlab-to-scale) page.
 
 ## Enable Monitoring
 

doc/administration/high_availability/gitlab.md

@@ -2,7 +2,9 @@
 type: reference
 ---
 
-# Configuring GitLab for Scaling and High Availability
+# Configuring GitLab application (Rails)
+
+This section describes how to configure the GitLab application (Rails) component.
 
 NOTE: **Note:** There is some additional configuration near the bottom for
 additional GitLab application servers. It's important to read and understand

doc/administration/high_availability/monitoring_node.md

@@ -11,7 +11,7 @@ You can configure a Prometheus node to monitor GitLab.
 ## Standalone Monitoring node using Omnibus GitLab
 
 The Omnibus GitLab package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md).
-The monitoring node is not highly available. See [Scaling and High Availability](../scaling/index.md)
+The monitoring node is not highly available. See [Scaling and High Availability](../reference_architectures/index.md)
 for an overview of GitLab scaling and high availability options.
 
 The steps below are the minimum necessary to configure a Monitoring node running Prometheus and Grafana with

doc/administration/high_availability/redis.md

@@ -27,7 +27,7 @@ These will be necessary when configuring the GitLab application servers later.
 
 ## Redis in a Scaled and Highly Available Environment
 
-This section is relevant for [Scalable and Highly Available Setups](../scaling/index.md).
+This section is relevant for [scalable and highly available setups](../reference_architectures/index.md).
 
 ### Provide your own Redis instance **(CORE ONLY)**
 
@@ -43,8 +43,8 @@ In this configuration Redis is not highly available, and represents a single
 point of failure. However, in a scaled environment the objective is to allow
 the environment to handle more users or to increase throughput. Redis itself
 is generally stable and can handle many requests so it is an acceptable
-trade off to have only a single instance. See [High Availability](../availability/index.md)
-for an overview of GitLab scaling and high availability options.
+trade off to have only a single instance. See the [reference architectures](../reference_architectures/index.md)
+page for an overview of GitLab scaling and high availability options.
 
 The steps below are the minimum necessary to configure a Redis server with
 Omnibus:
@@ -89,7 +89,7 @@ Advanced configuration options are supported and can be added if
 needed.
 
 Continue configuration of other components by going back to the
-[Scaling](../scaling/index.md#components-provided-by-omnibus-gitlab) page.
+[reference architectures](../reference_architectures/index.md#configure-gitlab-to-scale) page.
 
 ### High Availability with Omnibus GitLab **(PREMIUM ONLY)**
 

doc/administration/index.md

@@ -34,7 +34,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Install](../install/README.md): Requirements, directory structures, and installation methods.
   - [Database load balancing](database_load_balancing.md): Distribute database queries among multiple database servers. **(STARTER ONLY)**
   - [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only) **(STARTER ONLY)**
-- [High Availability](availability/index.md): Configure multiple servers for scaling or high availability.
+- [High Availability](reference_architectures/index.md): Configure multiple servers for scaling or high availability.
   - [Installing GitLab HA on Amazon Web Services (AWS)](../install/aws/index.md): Set up GitLab High Availability on Amazon AWS.
 - [Geo](geo/replication/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **(PREMIUM ONLY)**
 - [Disaster Recovery](geo/disaster_recovery/index.md): Quickly fail-over to a different site with minimal effort in a disaster situation. **(PREMIUM ONLY)**

doc/administration/object_storage.md

@@ -37,7 +37,7 @@ For configuring GitLab to use Object Storage refer to the following guides:
 
 ### Other alternatives to filesystem storage
 
-If you're working to [scale out](scaling/index.md) your GitLab implementation,
+If you're working to [scale out](reference_architectures/index.md) your GitLab implementation,
 or add [fault tolerance and redundancy](high_availability/README.md) you may be
 looking at removing dependencies on block or network filesystems.
 See the following guides and
@@ -77,7 +77,7 @@ with the Fog library that GitLab uses. Symptoms include:
 
 ### GitLab Pages requires NFS
 
-If you're working to add more GitLab servers for [scaling or fault tolerance](scaling/index.md)
+If you're working to add more GitLab servers for [scaling or fault tolerance](reference_architectures/index.md)
 and one of your requirements is [GitLab Pages](../user/project/pages/index.md) this currently requires
 NFS. There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/issues/196)
 to remove this dependency. In the future, GitLab Pages may use

doc/install/README.md

@@ -14,15 +14,15 @@ and cost of hosting.
 There are many ways you can install GitLab depending on your platform:
 
 1. **Omnibus GitLab**: The official deb/rpm packages that contain a bundle of GitLab
-   and the various components it depends on like PostgreSQL, Redis, Sidekiq, etc.
+   and the various components it depends on, like PostgreSQL, Redis, Sidekiq, etc.
 1. **GitLab Helm chart**: The cloud native Helm chart for installing GitLab and all
    its components on Kubernetes.
 1. **Docker**: The Omnibus GitLab packages dockerized.
 1. **Source**: Install GitLab and all its components from scratch.
 
 TIP: **If in doubt, choose Omnibus:**
-The Omnibus GitLab packages are mature, scalable, support
-[high availability](../administration/availability/index.md) and are used
+The Omnibus GitLab packages are mature,
+[scalable](../administration/reference_architectures/index.md) and are used
 today on GitLab.com. The Helm charts are recommended for those who are familiar
 with Kubernetes.
 
@@ -36,7 +36,7 @@ The Omnibus GitLab package uses our official deb/rpm repositories. This is
 recommended for most users.
 
 If you need additional flexibility and resilience, we recommend deploying
-GitLab as described in our [High Availability documentation](../administration/availability/index.md).
+GitLab as described in our [reference architecture documentation](../administration/reference_architectures/index.md).
 
 [**> Install GitLab using the Omnibus GitLab package.**](https://about.gitlab.com/install/)
 
@@ -67,7 +67,7 @@ GitLab maintains a set of official Docker images based on the Omnibus GitLab pac
 ## Installing GitLab from source
 
 If the Omnibus GitLab package is not available in your distribution, you can
-install GitLab from source: Useful for unsupported systems like *BSD. For an
+install GitLab from source: Useful for unsupported systems like \*BSD. For an
 overview of the directory structure, read the [structure documentation](structure.md).
 
 [**> Install GitLab from source.**](installation.md)

doc/install/aws/index.md

@@ -739,7 +739,7 @@ Have a read through these other resources and feel free to
 [open an issue](https://gitlab.com/gitlab-org/gitlab/issues/new)
 to request additional material:
 
-- [Scaling GitLab](../../administration/scaling/index.md):
+- [Scaling GitLab](../../administration/reference_architectures/index.md):
   GitLab supports several different types of clustering and high-availability.
 - [Geo replication](../../administration/geo/replication/index.md):
   Geo is the solution for widely distributed development teams.

doc/install/requirements.md

@@ -95,7 +95,7 @@ This is the recommended minimum hardware for a handful of example GitLab user ba
 - 4 cores supports up to 500 users
 - 8 cores supports up to 1,000 users
 - 32 cores supports up to 5,000 users
-- More users? Run it high-availability on [multiple application servers](https://about.gitlab.com/solutions/high-availability/)
+- More users? Consult the [reference architectures page](../administration/reference_architectures/index.md)
 
 ### Memory
 
@@ -112,7 +112,7 @@ errors during usage.
 - 16GB RAM supports up to 500 users
 - 32GB RAM supports up to 1,000 users
 - 128GB RAM supports up to 5,000 users
-- More users? Run it high-availability on [multiple application servers](https://about.gitlab.com/solutions/high-availability/)
+- More users? Consult the [reference architectures page](../administration/reference_architectures/index.md)
 
 We recommend having at least [2GB of swap on your server](https://askubuntu.com/a/505344/310789), even if you currently have
 enough available RAM. Having swap will help reduce the chance of errors occurring