GitLab High Availability/Scaling Documentation Improvements
Our HA docs need some work - these docs were great when written but our needs, product, our understanding and many other things have simply evolved (let's say, iterated, because it's one of our values! So now we need to iterate on the docs, too.)
Here's a brain dump of some things to consider:
- Administrators currently have a difficult time understanding the order in which things should happen during install/configuration. For example, backend services like PG, Redis and Gitaly should be configured before application nodes.
- We never really mention that
gitlab-secrets.jsonfile and SSH host keys should be synced, or broach the subject of backups, upgrade, etc. Admins are left to their own devices.
- We have both scaling and full HA scenarios that require different steps for the same components. For example, for scaling we need a single PG node but for HA we need Consul, PgBouncer, and PostgreSQL all with a crazy amount of steps. Similar, for Redis we need a single node for scaling but Sentinel for HA. How do we present these to users in a nice way but also keep things DRY?
- We don't mention which tiers things are in. i.e. Omnibus has HA support in EE with Premium/Ultimate sub and Support team can only help with Premium/Ultimate subscribers.
- Somehow merge CE and EE docs. Aim to have general HA/Scaling info in both CE and EE and then EE should also have Omnibus HA for PG, Redis, etc. This item really shouldn't be too difficult to solve if we can solve the scaling vs. HA problems. Because 'HA' for CE is basically just scaled GitLab OR the administrator provides their own PG and Redis HA which is completely on them.
Original issue description
We now have a problem between CE and EE High Availability docs. CE docs have some portion of Omnibus HA included, while it's not available for CE. For example, https://docs.gitlab.com/ce/administration/high_availability/redis.html includes documentation on Omnibus Redis HA, and it's not completely up to date.
I propose the following to get things in a good state:
- Revert any Omnibus HA related changes to CE HA docs. Then it should be fairly generic information on basic HA architecture, scaling, and how to configure GitLab itself. It will not describe how to set up HA database, Redis or other components. Basically, the docs will be like they were prior to Omnibus HA.
- Move the EE docs to different paths so there are not merge conflicts between CE and EE. We could simply append
-ee.html. If we don't do this in EE as opposed to namespacing the CE docs then bad things will happen when we merge CE to EE.