docs: Reconcile Gitaly Cluster (Praefect) on Kubernetes support status

Andrew Dunnrequested to merge
docs/reconcile-praefect-kubernetes-support-status into master

What does this MR do?

Three documentation pages state three different support statuses for Gitaly Cluster (Praefect) on Kubernetes, and one page contradicts itself. This reconciles the two statements in this project against the status the Praefect page already publishes.

As of master:

Page Statement
doc/administration/gitaly/praefect/_index.md, "Gitaly Cluster on Kubernetes" Status: Beta, introduced in GitLab 19.1
doc/administration/gitaly/praefect/_index.md, "Known issues" Gitaly Cluster (Praefect) "is not supported" in Kubernetes, citing epic 6127
doc/administration/reference_architectures/cloud_native.md "Gitaly Cluster (Praefect) is not supported on Kubernetes.", and separately "not supported in Cloud Native architectures"
doc/administration/gitaly/kubernetes.md "Gitaly (non-Cluster) is the only option" for a Cloud Native deployment
Using the Praefect chart (gitlab-org/charts/gitlab) Status: Experiment, "not yet suitable for production use"

The known-issues row predates the 19.1 beta. Epic 6127's plan is written against FY25 quarters, so the row was accurate when written and the beta landing did not update it.

The practical cost is that a reader planning a Cloud Native Hybrid to Cloud Native migration lands on the reference architecture page, reads that the topology is not supported, and stops. A reader who starts on the Praefect page reads that it shipped in 19.1 and plans around it. Both readings are supported by the current text and they lead to opposite decisions.

What changed

Three one-line edits, so that every statement of the claim in this project reads the same way.

doc/administration/gitaly/praefect/_index.md, the known-issues row: scoped to Kubernetes, with a pointer to the same page's beta section. The Amazon ECS statement is unchanged, because nothing in the 19.1 work speaks to ECS. The resolution column is scoped to production deployments.

doc/administration/reference_architectures/cloud_native.md: the note under "Kubernetes components" and the "Gitaly considerations" paragraph both carried the flat denial. Both now give the maturity and the reason the topology is absent from these architectures. The paragraph routing readers who need automatic failover to Cloud Native Hybrid is unchanged.

doc/administration/gitaly/kubernetes.md: "Gitaly (non-Cluster) is the only option" is now scoped to generally available, pointing at the beta.

The reconciliation this encodes

Stated plainly so it can be corrected rather than inferred from the diff:

  • The capability exists at beta maturity and is available to pilot.
  • The Cloud Native reference architecture does not include it, so production deployments that need automatic Git failover remain on Cloud Native Hybrid.
  • "Not supported" without qualification is no longer accurate for Kubernetes, and "beta" without the reference-architecture caveat is incomplete.

If group::gitaly reads that differently, I would rather land your wording than mine. The goal is one answer across the pages, not this particular phrasing.

Two things I have not changed

Both live in gitlab-org/charts/gitlab, so I have left them for routing rather than guessing:

  1. The chart page carries Status: Experiment while the admin page carries Status: Beta. Is the intent that the capability is beta and the chart delivering it is a separate, earlier-stage artifact, or has one label not caught up?
  2. The chart page directs readers who want a GA timeline to charts epic 33, which is open with a due date of 2022-03-17 and a status note that predates the beta. Epic 20405 and epic 21774 look closer to the live work. Which epic should that link point at?

Related issues

None. Surfaced while answering a self-managed customer's question about the support status of a fully Kubernetes-native high availability deployment.

Author's checklist

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

  • If the content requires it, ensure the information is reviewed by a subject matter expert. The support-status reconciliation above is the item that needs group::gitaly's read.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
  • Review by assigned maintainer.

Verification

Docs-only, text changes to four lines across three files. Verified against master at author time:

Claim How it was verified
Praefect page carries Status: Beta, introduced in 19.1 Fetched doc/administration/gitaly/praefect/_index.md from master; the section carries Status: Beta and [Introduced](https://gitlab.com/groups/gitlab-org/-/work_items/21774) in GitLab 19.1
"not generally available" is the page's own framing Same page: "We are working over these known issues and other related items before moving it to general availability"
#gitaly-cluster-on-kubernetes anchor resolves Matches the ## Gitaly Cluster on Kubernetes heading in the same file
../gitaly/praefect/_index.md resolves from the reference architecture page Fetched on master; matches the path form already used in the same note for ../gitaly/kubernetes.md#requirements
../../reference_architectures/_index.md resolves from the Praefect page Fetched on master
Epic 6127 is accessible and its plan predates the beta Fetched via API: open, public, with a timeline written against FY25 quarters
Charts epic 33 due date and status Fetched via API: open, due 2022-03-17, status note predating the beta
Chart page carries Status: Experiment Fetched doc/charts/gitlab/praefect/_index.md from gitlab-org/charts/gitlab master

AI-Generated Content Disclosure: This MR was prepared with assistance from Claude Code. The output has been reviewed for correctness, verified against source per the verification table above, and validated against the documentation style guide.

Edited by Andrew Dunn

Merge request reports