Enterprise Kubernetes, delivered

Tectonic ships with CoreOS's signature automated operations, runs multi-cloud, and is the fastest, most secure path to Kubernetes.

Using the Kubernetes auth backend

This guide shows a simple example of how to set up and authenticate against the Kubernetes auth backend. For more details consult the Vault documentation on the Kubernetes Auth Backend.

This example will:

  • Set up the Kubernetes auth backend
  • Configure a Role for a service account with some policy
  • Authenticate Vault requests using the service account token


  • Tectonic 1.7+
  • Before beginning, create the example Vault cluster that is initialized and unsealed.

Kubernetes auth backend setup

Configure port forwarding

To enable and configure the auth backend with the necessary roles and policies, make the Vault client requests authenticate with the root token.

  1. Configure port forwarding between the local machine and the active Vault node:

     kubectl -n default get vault example -o jsonpath='{.status.vaultStatus.active}' | xargs -0 -I {} kubectl -n default port-forward {} 8200
  2. Open a new terminal. Use this terminal for the rest of this guide.

  3. Export the following environment for the Vault CLI environment. Replace the <root-token> with the root token generated during initialization.

     export VAULT_ADDR='https://localhost:8200'
     export VAULT_SKIP_VERIFY="true"
     export VAULT_TOKEN=<root-token>

Set up service account for Vault token review

  1. Create the service account vault-tokenreview:
kubectl -n default create serviceaccount vault-tokenreview
  1. Create the ClusterRoleBinding for the vault-tokenreview service account to access the Kubernetes TokenReview API:
kubectl -n default create -f example/k8s_auth/vault-tokenreview-binding.yaml
  1. Fetch the token for the vault-tokenreview service account:
SECRET_NAME=$(kubectl -n default get serviceaccount vault-tokenreview -o jsonpath='{.secrets[0].name}')
TR_ACCOUNT_TOKEN=$(kubectl -n default get secret ${SECRET_NAME} -o jsonpath='{.data.token}' | base64 --decode)

Enable and configure the backend

  1. Enable the Kubernetes auth backend:

     vault auth-enable kubernetes
  2. Configure the backend with the Kubernetes master server URL and certificate-authority-data.

     vault write auth/kubernetes/config kubernetes_host=<server-url> kubernetes_ca_cert=@ca.crt token_reviewer_jwt=$TR_ACCOUNT_TOKEN

Create a policy and role

The Kubernetes backend authorizes an entity by granting it a role mapped to a service account. A role is configured with policies which control the entity's access to paths and operations in Vault.

  1. Create a new policy demo-policy using example policy file policy.hcl.

     vault write sys/policy/demo-policy policy=@example/k8s_auth/policy.hcl
  2. Create a new role demo-role configured for the service account default and policy demo-policy:

     vault write auth/kubernetes/role/demo-role \
         bound_service_account_names=default \
         bound_service_account_namespaces=default \
         policies=demo-policy \

Authenticate requests using the service account token

The backend can now be used to authenticate Vault requests using the service account default.


Now use the service account token to authenticate for the role demo-role

  1. Fetch the token for the default service account:
SECRET_NAME=$(kubectl -n default get serviceaccount default -o jsonpath='{.secrets[0].name}')
DEFAULT_ACCOUNT_TOKEN=$(kubectl -n default get secret ${SECRET_NAME} -o jsonpath='{.data.token}' | base64 --decode)
  1. Log in to the Kubernetes auth backend using the service account token:
$ vault write auth/kubernetes/login role=demo-role jwt=${DEFAULT_ACCOUNT_TOKEN}
Key                                   	Value
---                                   	-----
token                                 	74603479-607d-4ab8-a406-d0456d9f3d65
token_accessor                        	4893b0a1-f42a-bfd8-cd9c-c14b9bdb6095
token_duration                        	1h0m0s
token_renewable                       	true
token_policies                        	[default demo-policy]
token_meta_role                       	"demo-role"
token_meta_service_account_name       	"default"
token_meta_service_account_namespace  	"default"
token_meta_service_account_secret_name	"default-token-fndln"
token_meta_service_account_uid        	"aaf6c23c-b04a-11e7-9aea-0245c85cf1cc"
  1. Set the VAULT_TOKEN to the value of the key token from the output of the last step:
export VAULT_TOKEN=74603479-607d-4ab8-a406-d0456d9f3d65

Issue requests

With the above VAULT_TOKEN set, the Vault requests will be authenticated according to the role demo-role and the policy demo-policy.

Confirm that the policy enables secret creation only under the path "secret/demo/":

$ vault write secret/demo/foo value=bar
Success! Data written to: secret/demo/foo

Reject requests on non-"secret/demo/" path:

$ vault write secret/foo value=bar
Error writing data to secret/foo: Error making API request.

URL: PUT https://localhost:8200/v1/secret/foo
Code: 403. Errors:

* permission denied


kubectl -n default delete serviceaccount vault-tokenreview
kubectl -n default delete clusterrolebinding vault-tokenreview-binding