Docs: Improve page about Kubernetes deploy
This is about this documentation page: https://docs.gitlab.com/ce/user/project/clusters/
I followed this page to set up Kubernetes integration and there were three points where I struggled and where I think the documentation could be improved. All the information is there somewhere, but they could be cross-linked better:
-
I first skipped forward to the section What you can get with the Kubernetes integration and found it confusing that it mentions neither the creation of namespaces and service accounts nor the Deployment Variables that are available to CI jobs. Those are arguably two main parts of the Kubernetes integration.
-
The section Deployment variables could repeat the warning that those are only available to deployment jobs. This is mentioned on the linked page, but I think it's easy to miss. Also, neither page explains what a "deployment job" is. Jobs in stage "deploy"? Jobs that have an
environment
set? (Answer: It's the latter.) -
The section Deployment variables should also mention that you also have to create a Deploy Token, you have to name it
gitlab-deploy-token
and you have to runkubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f -
in your deploy job script, otherwise Kubernetes won't be able to access the registry and the deploy will fail.