Skip to content

Improve Kubernetes installation docs

Joshua Lambert requested to merge 37056-improve-kubernetes-installation-docs into master

The docs at https://docs.gitlab.com/ee/install/kubernetes/ are unclear. Here are some thoughts for improvements:

  • The gitlab-omnibus doc should standalone and not refer back to the parent page, except as an overview other options. e.g. Remove the Prerequisites section, and move it into each chart page.

  • The parent page should an overview of the installation options. It should be the only page you need to understand our k8s installation strategy; what we have now and where it's going (and what we've deprecated).

  • It should be clear that gitlab-omnibus is the one chart they should be aware of first. We mark it as Recommended, but it should be stronger than that. It's not just one choice amongst many, it's the installation chart. We should make it clear that it's beta, and why, probably by saying that right there, not just at the top, perhaps with link to issue to make it GA by 10.1.

  • It should be clear that there is no GA installation method for Kubernetes.

  • gitlab-runner should be recommended if GitLab itself is not installed in Kubernetes, but you want to use k8s for runners. Does this chart need to be beta? It's pretty complete and I'm not aware of anything prohibiting its use in production.

  • Can we kill gitlab chart completely? Does it offer anything omnibus does not?

  • We should probably mention the external gitlab-ce and gitlab-ee charts, if only to say that they are not recommended.

  • Can we submit PRs to gitlab-ce and gitlab-ee charts to mark them as deprecated and point to https://docs.gitlab.com/ee/install/kubernetes/ instead?

  • The links to cloud native are 404s.

  • We can move the notice about the cloud native charts closer to the list of charts. Perhaps that will happen automatically if we remove the Prerequisites section. But perhaps we should move it towards the bottom. Make it clear that they shouldn't wait for the cloud native charts, but that there will be a migration if they start now. Ideally, we'd commit to a migration path and document that as well so people can confidently start with gitlab-omnibus knowing their work/data won't be lost. But if won't have a migration path, then explicitly state that too.

Closes #37056 (closed)

Edited by Achilleas Pipinellis

Merge request reports