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 usesidekiq_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, theregistry
settings, andregistry_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 ofString
, when it actually accepts anArray
-
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 thepgbouncer
node if using scaled postrgresql -
Make docs on git_data_dirs
consistent between NFS docs and gitlab.rb.template -
remove the postgres
,pgbouncer
, andconsule
enable = false
settings from the several example application configurations in the configuring a Database for GitLab HA docs (several places throughout the file)
Edited by Brian Vanderbusch