Skip to content

WIP: Refactor scaling / availability to System Architecture page in the docs

Tanya Pazitny requested to merge tp-update-scaling-high-availability into master

What does this MR do?

Based on feedback from Sid, this MR refactors the scaling and high availability pages into one streamlined page, System Architecture. Rather than being nested in the Administrator section of the docs, it now lives in the Install section because it should be considered before a self-managed customer embarks on installing GitLab.

There was a decent amount of redundant information on the former scaling and high availability pages, so they are now included as sub-sections on one page. The reader's journey should now go from a high-level recommendation based on number of users right at the start, followed by a dive from simpler/less scaled/less available -> more complex/scaled/highly available as they are walked through scaling and high availability concerns. Finally, the page ends with reference architecture information.

There are some to-do's I wasn't able to address in this first iteration.

  1. Item 3.c.i from the working session: Clearly differentiate between different High Availability features and their tradeoffs. Fabian is out on Easter break and I couldn't find an MR in progress for this issue. #209855 (closed)
  2. Item 2.a.ii from the working session: Add concrete information around how to identify when it's time to scale out an individual service, plus instructions for how to actually scale out. #214055 (closed)
  3. Item 3.c.v from the working session: Build and certify non-HA versions of reference architectures for 10k users or less. This will be a significant effort and needs to be planned and prioritized. Issue has been created: gitlab-org/quality/performance#223 (closed)
  4. Item 4.b.i from the working session: We found another page that could add to customer confusion which we need to refactor. #214054 (closed)

Related issues

Author's checklist

Review checklist

All reviewers can help ensure accuracy, clarity, completeness, and adherence to the Documentation Guidelines and Style Guide.

1. Primary Reviewer

  • Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.

2. Technical Writer

  • Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable DevOps stage.

3. Maintainer

  1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
  2. Ensure a release milestone is set.
  3. If there has not been a technical writer review, create an issue for one using the Doc Review template.
Edited by 🤖 GitLab Bot 🤖

Merge request reports