Docs: Consolidate and improve HA documentation

The various pieces of documentation for setting up GitLab HA are all over the place on the docs site, and it's difficult to know if I've even found them all, so there is no search results page.

Right now the best "landing page" for setting up HA is https://docs.gitlab.com/ee/administration/high_availability/README.html.

I propose that this page be improved to add additional information and links. Current problems or things that need to be clarified are as follows:

  • No mention at all of roles, even when clicking on the redis bullet item
  • No mention of database replication even from the linked "configuring the database"
  • no mention anywhere of recommendations around usage of sidekiq_cluster settings. I've found in an issue that it seems you can set up some nodes specifically to use sidekiq_cluster to process some of the queues.
  • Most "node" documentation pages don't show what settings should be disabled in terms of other components for each node
  • No idea if roles is just a redis thing, or if there are roles for the various database components, and front-end components. Every piece of language uses "for example" and uses redis, but the unanswered implication is that there is a full list of roles somewhere
  • There should be a link directly on the high availability landing page regarding HA lifecycle (deployment, upgrade, backups, etc...)
  • Add a link section on main High Availability describing GitLab Geo, possibly even adding it as a third bullet to the Architecture section of that doc
  • Add a list of non-core components that can have their own nodes, and the configs (including omnibus) for each. Specifically i'm talking about Registry, Elasticsearch and any other component that has omnibus/config.yaml settings and is used natively in the UI.
  • I know for example, that the registry settings can get a tad complex between the gitlab_rails configs, the registry settings, and registry_nginx settings, when trying to set it up on a node outside of the single-node architecture.
  • Add a topology image (in the manner of the existing examples) for an Implementation with scaled redis, postgres, and sidkiq nodes (any other scalable components?).
  • Add a topology image for usage of replication of database and front-end that include Gitlab Geo
  • Add list of secondary services that need to be enabled on front end nodes to the Configure the Application for HA page. (gitaly? workhorse? etc...)
  • Add a section/item for "migrating from a single-node setup to GitLab HA"
  • obtaining/creating passwords for Postgresql
  • obtaining/creating passwords for Redis
  • other?
  • Docs at https://docs.gitlab.com/ee/administration/high_availability/gitlab.html show high_availability['mountpoint'] example value as a type of String, when it actually accepts an Array
  • Docs at https://docs.gitlab.com/ee/administration/high_availability/gitlab.html, in step 3, the comment for db host should indicate that the gitlab_rails['db_host'] destination should be either the database, or the pgbouncer node if using scaled postrgresql
  • Make docs on git_data_dirs consistent between NFS docs and gitlab.rb.template
  • remove the postgres, pgbouncer, and consule enable = false settings from the several example application configurations in the configuring a Database for GitLab HA docs (several places throughout the file)
Edited May 24, 2018 by Brian Vanderbusch
Assignee Loading
Time tracking Loading