Setting Up Kubernetes Auth in Vault

Note

This is general guide that is referenced by other documents in the wiki. You might be looking for one of the guides refering to specific secret serving methods.

Prerequisites

• Kubernetes cluster
• Vault installed and running (This guide assumes external installation)

Installatoin

Example

All of the files used in the installation process are also available on the GitHub repository.

Step 1. Configuring Kubernetes

In general, communication between Vault and Kubernetes is authenticated via Kubernetes ServiceAccounts there are two ways to setup this communication: 1. Each pod has service account with system:auth-delegator capability for self verification by Vault. 2. A single service account with system:auth-delegator capability is used by Vault instance to verify service accounts of the target pods.

We will use the second method, as it doesn't require elevating privileges of each pod.

So, first we need to create the ServiceAccount that will be used by Vault to validate the JWT tokens of the pods, and the ClusterRoleBinding for system:auth-delegator capability, so the vault can actually verify the tokens.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: <service-account-name>
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: <service-account-name>-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:auth-delegator
subjects:
- kind: ServiceAccount
  name: <service-account-name>
  namespace: hashicorp-vault

With the ServiceAccount created we then need a JWT token that we can pass to Vault for Authentication against Kubernetes API. We can achieve this by creating a secret tied to the ServiceAccount, and the Kubernetes will fill it with the JWT token.

apiVersion: v1
kind: Secret
metadata:
  name: <service-account-name>-reviewer-token
  annotations:
    kubernetes.io/service-account.name: <service-account-name>
type: kubernetes.io/service-account-token

You can now verify that the service account has been created and the token has been generated by running the following commands:

$ kubectl describe serviceaccounts -n hashicorp-vault vault-csi-csi-provider
# Name:                <service-account-name>
# Namespace:           hashicorp-vault
# Labels:              [Output omitted]
# Annotations:         meta.helm.sh/release-name: csi
#                      meta.helm.sh/release-namespace: hashicorp-vault
# Image pull secrets:  <none>
# Mountable secrets:   <none>
# Tokens:              <service-account-name>-reviewer-token
# Events:              <none>

Step 2. Configuring Vault

Tip

This guide uses Vault Web UI for convinience, however the same steps can be performed easily using Vault CLI or API.

1. Enable the Kubernetes auth method:
2. Open the Vault Web UI; Login with administrative credentials.
3. Click on Access > Authentication Methods, you should be presented with a screen similar to the one below:
4. Click on Enable New Method and select Kubernetes. Settings you will be presented in Method Options with are Vault specific and do not require any tweaking.
5. Click on Enable Method to enable the Kubernetes auth method. You should be presented with a configuration page. Unfold the Kubernetes Options section and the screen should look like this:
6. Retrieve the Kubernetes JWT token configuration. You should be able to see the token values in the secret you created in the previously, like following:

   $ kubectl get secret <service-account-name>-reviewer-token -n hashicorp-vault -o yaml
   # apiVersion: v1
   # data:
   #   ca.crt: [Output omitted | base64 encoded]
   #   namespace: aGFzaGljb3JwLXZhdWx0
   #   token: [Output omitted | base64 encoded]
   # kind: Secret
   # metadata:
   #   annotations: [Output omitted]
   #   creationTimestamp: "2025-03-02T23:45:20Z"
   #   labels: [Output omitted]
   #   name: <service-account-name>-reviewer-token
   #   namespace: hashicorp-vault
   #   resourceVersion: "24666018"
   #   uid: f4c9656a-6425-4abc-8f3c-4c6d6cf1d51a
   # type: kubernetes.io/service-account-token
   

   As you can see the secret stores both ca certificate and the JWT token, they're base64 encoded, you can decode them yourself or use the following commands:

   $ kubectl get secret <service-account-name>-reviewer-token -n hashicorp-vault -o jsonpath="{.data.token}" | base64 --decode
   $ kubectl get secret <service-account-name>-reviewer-token -n hashicorp-vault -o jsonpath="{.data.ca\.crt}" | base64 --decode
   

7. Fill in the following:
   • Kubernetes Host: The Kubernetes API server address. This is the address of the Kubernetes API server that Vault will use to communicate with the Kubernetes cluster. This is usually the address of the Kubernetes API server service in the Kubernetes cluster.
   • Kubernetes CA Certificate: The CA certificate of the Kubernetes API server. Acquired in the previous step from the secret.
   • Token Reviewer JWT: The JWT token that Vault will use to authenticate with the Kubernetes API server. Acquired in the previous step from the secret.
   • Press Save to save the configuration.