Documentation consistency for "Kubernetes Auth"

Dear Hashicorp Vault Team,

Hope you are doing well. Thank you for the amazing support and creating documentation for the same. We really appreciate it.

Recently, we want to create a Certificate Authority using Vault and issue certificates using cert-manager cluster-issuer in Kubernetes that requires creating a service account and ClusterRoleBinding for that service account.

I am afraid to say, it took my approx 3-4 days to do the same with good amount of debugging, googling, reading issues and what I am doing wrong whereas it's probably a 30 mins job .

The problem is a bit of miss in the documentation. For instance, for creating the CA and using cert-manager, there's a Configure Vault as a Certificate Manager in Kubernetes with Helm, now if we read this documentation. In the Configure Kubernetes authentication, there is a

vault write auth/kubernetes/config \
    kubernetes_host="https://$KUBERNETES_PORT_443_TCP_ADDR:443" \
    token_reviewer_jwt="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" \
    kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
    issuer="https://kubernetes.default.svc.cluster.local"
Success! Data written to: auth/kubernetes/config

Now, it is not exactly provided that which service account is /var/run/secrets/kubernetes.io/serviceaccount/token. A beginner like me just blindly copied the code and executed (I am not the only one). Now, later in section Configure an issuer and generate a certificate, we create a service account issuer that is ideally used for Kubernetes authentication, rather than the one that was mounted on the /var/run/secrets/kubernetes.io/serviceaccount/token in the vault-0 pod.

Now, here I was confused whether there are two service accounts - issuer and the default in either the default namespace or cert-manager namespace. Further, the above documentation fails to mention the ClusterRoleBinding required for the service account for Kubernetes Auth.

So, the result of following the above documentation kind of results into multiple people facing issues like Kubernetes Authentication Denied and Vault ClusterIssuer with Kubernetes authentication not possible?

Documentation Integrate a Kubernetes Cluster with an External Vault also doesn't mention anything about ClusterRoleBinding probably because helm would have installed it automatically (might be wrong).

Now, the best and proper documentation on Kubernetes Auth that solved my issue in 5 mins was Vault Agent with Kubernetes. It clearly mentions about process of Kube Auth, service account, TokenReviewAPI and ClusterRoleBinding. I followed this and was able to resolve the issue.

Suggestion

A minor suggestion I have is maybe we can structure the tutorials/documentation in a different way. For instance,

Vault Installation
- Downloading binary and running it
- Via Helm3
- Via Kubernetes Operator
Kubernetes Auth
- Vault Agent (installed using Helm and using injector)
- Creating service account (providing access to TokenReviewAPI/ ClusterRoleBinding)
- Any other method

The benefit probably might be

Clear and concise documentation
Less repeatation of documentation. For instance, in most of the tutorials, we install MiniKube, setup Vault using Helm, configure Kubernetes Auth. There are high chances of these subsection being out-of-sync as result of 1) being written by different authors 2) some tutorial being updated/left.
If we follow the above structure, we can just point to one doc and say "Install Minikube" as described here.

Just sharing the thoughts, feel free to ignore.

Thank you again for your awesome support.

Kind Regards, Vijay

hashicorp / vault

Documentation consistency for "Kubernetes Auth" #13645