Add latest changes from gitlab-org/gitlab@master

4 files changed, 114 insertions, 42 deletions

diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md
index aa70890d3cd..26b4434de77 100644
--- a/doc/administration/audit_events.md
+++ b/doc/administration/audit_events.md
@@ -41,6 +41,7 @@ From there, you can see the following actions:
 - Group created or deleted
 - Group changed visibility
 - User was added to group and with which [permissions]
+- User sign-in via [Group SAML](../user/group/saml_sso/index.md)
 - Permissions changes of a user assigned to a group
 - Removed user from group
 - Project added to group and with which visibility level
diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md
index b5258a66e59..4734df324e0 100644
--- a/doc/administration/high_availability/README.md
+++ b/doc/administration/high_availability/README.md
@@ -2,18 +2,15 @@
 type: reference, concepts
 ---
 
-# Scaling and High Availability
+# High Availability
 
-GitLab supports a number of scaling options to ensure that your self-managed
-instance is able to scale out to meet your organization's needs when scaling up
-is no longer practical or feasible.
-
-GitLab also offers high availability options for organizations that require
+GitLab offers high availability options for organizations that require
 the fault tolerance and redundancy necessary to maintain high-uptime operations.
 
-Scaling and high availability can be tackled separately as GitLab comprises
-modular components which can be individually scaled or made highly available
-depending on your organization's needs and resources.
+Please consult our [scaling documentation](../scaling) if you want to resolve
+performance bottlenecks you encounter in individual GitLab components without
+incurring the additional complexity costs associated with maintaining a
+highly-available architecture.
 
 On this page, we present examples of self-managed instances which demonstrate
 how GitLab can be scaled out and made highly available. These examples progress
@@ -29,39 +26,7 @@ watch [this 1 hour Q&A](https://www.youtube.com/watch?v=uCU8jdYzpac)
 with [John Northrup](https://gitlab.com/northrup), and live questions coming
 in from some of our customers.
 
-## Scaling examples
-
-### Single-node Omnibus installation
-
-This solution is appropriate for many teams that have a single server at their disposal. With automatic backup of the GitLab repositories, configuration, and the database, this can be an optimal solution if you don't have strict availability requirements.
-
-You can also optionally configure GitLab to use an [external PostgreSQL service](../external_database.md)
-or an [external object storage service](object_storage.md) for added
-performance and reliability at a relatively low complexity cost.
-
-References:
-
-- [Installation Docs](../../install/README.md)
-- [Backup/Restore Docs](https://docs.gitlab.com/omnibus/settings/backups.html#backup-and-restore-omnibus-gitlab-configuration)
-
-### Omnibus installation with multiple application servers
-
-This solution is appropriate for teams that are starting to scale out when
-scaling up is no longer meeting their needs. In this configuration, additional application nodes will handle frontend traffic, with a load balancer in front to distribute traffic across those nodes. Meanwhile, each application node connects to a shared file server and PostgreSQL and Redis services on the back end.
-
-The additional application servers adds limited fault tolerance to your GitLab
-instance. As long as one application node is online and capable of handling the
-instance's usage load, your team's productivity will not be interrupted. Having
-multiple application nodes also enables [zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates).
-
-References:
-
-- [Configure your load balancer for GitLab](load_balancer.md)
-- [Configure your NFS server to work with GitLab](nfs.md)
-- [Configure packaged PostgreSQL server to listen on TCP/IP](https://docs.gitlab.com/omnibus/settings/database.html#configure-packaged-postgresql-server-to-listen-on-tcpip)
-- [Setting up a Redis-only server](https://docs.gitlab.com/omnibus/settings/redis.html#setting-up-a-redis-only-server)
-
-## High-availability examples
+## Examples
 
 ### Omnibus installation with automatic database failover
 
diff --git a/doc/administration/scaling/index.md b/doc/administration/scaling/index.md
new file mode 100644
index 00000000000..99e8ca9a65f
--- /dev/null
+++ b/doc/administration/scaling/index.md
@@ -0,0 +1,73 @@
+---
+type: reference, concepts
+---
+
+# Scaling
+
+GitLab supports a number of scaling options to ensure that your self-managed
+instance is able to scale out to meet your organization's needs when scaling up
+a single-box GitLab installation is no longer practical or feasible.
+
+Please consult our [high availability documentation](../high_availability/README.md)
+if your organization requires fault tolerance and redundancy features, such as
+automatic database system failover.
+
+## GitLab components and scaling instructions
+
+Here's a list of components directly provided by Omnibus GitLab or installed as
+part of a source installation and their configuration instructions for scaling.
+
+| Component | Description | Configuration instructions |
+|-----------|-------------|----------------------------|
+| [PostgreSQL](../../development/architecture.md#postgresql) | Database | [PostgreSQL configuration](https://docs.gitlab.com/omnibus/settings/database.html) |
+| [Redis](../../development/architecture.md#redis)  | Key/value store for fast data lookup and caching | [Redis configuration](../high_availability/redis.md) |
+| [GitLab application services](../../development/architecture.md#unicorn) | Unicorn/Puma, Workhorse, GitLab Shell - serves front-end requests requests (UI, API, Git over HTTP/SSH) | [GitLab app scaling configuration](../high_availability/gitlab.md) |
+| [PgBouncer](../../development/architecture.md#pgbouncer) | Database connection pooler | [PgBouncer configuration](../high_availability/pgbouncer.md#running-pgbouncer-as-part-of-a-non-ha-gitlab-installation) **(PREMIUM ONLY)** |
+| [Sidekiq](../../development/architecture.md#sidekiq) | Asynchronous/background jobs | [Sidekiq configuration](../high_availability/sidekiq.md) |
+| [Gitaly](../../development/architecture.md#gitaly) | Provides access to Git repositories | [Gitaly configuration](../gitaly/index.md#running-gitaly-on-its-own-server) |
+| [Prometheus](../../development/architecture.md#prometheus) and [Grafana](../../development/architecture.md#grafana) | GitLab environment monitoring | [Monitoring node for scaling](../high_availability/monitoring_node.md) |
+
+## Third-party services used for scaling
+
+Here's a list of third-party services you may require as part of scaling GitLab.
+The services can be provided by numerous applications or vendors and further
+advice is given on how best to select the right choice for your organization's
+needs.
+
+| Component | Description | Configuration instructions |
+|-----------|-------------|----------------------------|
+| Load balancer(s) | Handles load balancing, typically when you have multiple GitLab application services nodes | [Load balancer configuration](../high_availability/load_balancer.md)      |
+| Object storage service | Recommended store for shared data objects | [Cloud Object Storage configuration](../high_availability/object_storage.md) |
+| NFS | Shared disk storage service. Can be used as an alternative for Gitaly or Object Storage. Required for GitLab Pages | [NFS configuration](../high_availability/nfs.md) |
+
+## Examples
+
+### Single-node Omnibus installation
+
+This solution is appropriate for many teams that have a single server at their disposal. With automatic backup of the GitLab repositories, configuration, and the database, this can be an optimal solution if you don't have strict availability requirements.
+
+You can also optionally configure GitLab to use an [external PostgreSQL service](../external_database.md)
+or an [external object storage service](../high_availability/object_storage.md) for added
+performance and reliability at a relatively low complexity cost.
+
+References:
+
+- [Installation Docs](../../install/README.md)
+- [Backup/Restore Docs](https://docs.gitlab.com/omnibus/settings/backups.html#backup-and-restore-omnibus-gitlab-configuration)
+
+### Omnibus installation with multiple application servers
+
+This solution is appropriate for teams that are starting to scale out when
+scaling up is no longer meeting their needs. In this configuration, additional application nodes will handle frontend traffic, with a load balancer in front to distribute traffic across those nodes. Meanwhile, each application node connects to a shared file server and PostgreSQL and Redis services on the back end.
+
+The additional application servers adds limited fault tolerance to your GitLab
+instance. As long as one application node is online and capable of handling the
+instance's usage load, your team's productivity will not be interrupted. Having
+multiple application nodes also enables [zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates).
+
+References:
+
+- [Configure your load balancer for GitLab](../high_availability/load_balancer.md)
+- [Configure your NFS server to work with GitLab](../high_availability/nfs.md)
+- [Configure packaged PostgreSQL server to listen on TCP/IP](https://docs.gitlab.com/omnibus/settings/database.html#configure-packaged-postgresql-server-to-listen-on-tcpip)
+- [Setting up a Redis-only server](https://docs.gitlab.com/omnibus/settings/redis.html#setting-up-a-redis-only-server)
diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md
index 475b7d44eac..b66b6e8c90a 100644
--- a/doc/administration/troubleshooting/ssl.md
+++ b/doc/administration/troubleshooting/ssl.md
@@ -137,3 +137,36 @@ To fix this problem:
     ```shell
     git config --global http.sslVerify false
     ```
+
+## SSL_connect wrong version number
+
+A misconfiguration may result in:
+
+- `gitlab-rails/exceptions_json.log` entries containing:
+
+  ```plaintext
+  "exception.class":"Excon::Error::Socket","exception.message":"SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)",
+  "exception.class":"Excon::Error::Socket","exception.message":"SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)",
+  ```
+
+- `gitlab-workhorse/current` containing:
+
+  ```plaintext
+  http: server gave HTTP response to HTTPS client
+  http: server gave HTTP response to HTTPS client
+  ```
+
+- `gitlab-rails/sidekiq.log` or `sidekiq/current` containing:
+
+  ```plaintext
+  message: SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)
+  message: SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)
+  ```
+
+Some of these errors come from the Excon Ruby gem, and could be generated in circumstances
+where GitLab is configured to initiate an HTTPS session to a remote server
+that is serving just HTTP.
+
+One scenario is that you're using [object storage](../high_availability/object_storage.md)
+which is not served under HTTPS. GitLab is misconfigured and attempts a TLS handshake,
+but the object storage will respond with plain HTTP.