Improve Kubernetes installation docs
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
andgitlab-ee
charts, if only to say that they are not recommended. -
Can we submit PRs to gitlab-ce
andgitlab-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.