The Kubernetes Secrets Engine for Vault generates Kubernetes service account tokens, and optionally service accounts, role bindings, and roles. The created service account tokens have a configurable TTL and any objects created are automatically deleted when the Vault lease expires.
For each lease, Vault will create a service account token attached to the defined service account. The service account token is returned to the caller.
We do not recommend using tokens created by the Kubernetes Secrets Engine to authenticate with the Vault Kubernetes Auth Method. This will generate many unique identities in Vault that will be hard to manage.
Setup
The Kubernetes Secrets Engine must be configured in advance before it can perform its functions. These steps are usually completed by an operator or configuration management tool.
By default, Vault will connect to Kubernetes using its own service account. If using the standard Helm chart, this service account is created automatically by default and named after the Helm release (often vault, but this can be configured via the Helm value server.serviceAccount.name).
It's necessary to ensure that the service account Vault uses will have permissions to manage service account tokens, and optionally manage service accounts, roles, and role bindings. These permissions can be managed using a Kubernetes role or cluster role. The role is attached to the Vault service account with a role binding or cluster role binding.
For example, a minimal cluster role to create service account tokens is:
Create this role in Kubernetes (e.g., with kubectl apply -f).
Moreover, if you want to use label selection to configure the namespaces on which a role can act, you will need to grant Vault permissions to read namespaces.
Getting the right permissions for Vault will require some trial and error most likely since Kubernetes has strict protections against privilege escalation. You can read more in the Kubernetes RBAC documentation.
Protect the Vault service account, especially if you use broader permissions for it, as it is essentially a cluster administrator account.
Create a role binding to bind the role to Vault's service account and grant Vault permission to manage tokens.
For more information on Kubernetes roles, service accounts, bindings, and tokens, visit the Kubernetes RBAC documentation.
If Vault will not be automatically managing roles or service accounts (see Automatically Managing Roles and Service Accounts), then you will need to set up a service account that Vault will issue tokens for.
It is highly recommended that the service account that Vault issues tokens for is NOT the same service account that Vault itself uses.
The examples we will use will under the namespace test, which you can create if it does not already exist.
$ kubectl create namespace test
namespace/test created
Here is a simple set up of a service account, role, and role binding in the Kubernetes test namespace with basic permissions we will use for this document:
apiVersion: v1
kind: ServiceAccount
metadata:
name: test-service-account-with-generated-token
namespace: test
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: test-role-list-pods
namespace: test
rules:
- apiGroups: [""]
resources: ["pods"]
verbs: ["list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: test-role-abilities
namespace: test
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: test-role-list-pods
subjects:
- kind: ServiceAccount
name: test-service-account-with-generated-token
namespace: test
You can create these objects with kubectl apply -f.
Go to the Secrets engine tab, click Enable new engine + , then select Kubernetes to enable a new Kubernetes engine.
By default, the secrets engine will mount at the same name as the engine, i.e., kubernetes/ here. This can be changed by passing the -path argument when enabling.
Configure the mount point. An empty config is allowed.
$ vault write -f kubernetes/config
Select the Configuration Tab and click on Configure Kubernetes.
Click on the Get config values button, and then Save.
Configuration options are available as specified in the API docs.
You can now configure Kubernetes Secrets Engine to create a Vault role (not the same as a Kubernetes role) that can generate service account tokens for the given service account:
After a user has authenticated to Vault and has sufficient permissions, a write to the creds endpoint for the Vault role will generate and return a new service account token.
You can use the service account token above (eyJHbG...) with any Kubernetes API request that its service account is authorized for (through role bindings).
You can also set a TTL (ttl) when you generate the token from the credentials endpoint. The TTL of the token will be given the default if not specified (and cannot exceed the maximum TTL of the role, if present).
You can set default audiences (token_default_audiences) when creating or tuning the Vault role. The Kubernetes cluster default audiences for service account tokens will be used if not specified.
You can also set audiences (audiences) when you generate the token from the credentials endpoint. The audiences of the token will be given the default audiences if not specified.
When configuring the Vault role, you can pass in parameters to specify that you want to automatically generate the Kubernetes service account and role binding, and optionally generate the Kubernetes role itself.
If you want to configure the Vault role to use a pre-existing Kubernetes role, but generate the service account and role binding automatically, you can set the kubernetes_role_name parameter.
Vault's service account will also need access to the resources it is granting access to. This can be done for the examples above with kubectl -n test create rolebinding --role test-role-list-pods --serviceaccount=vault:vault vault-test-role-abilities. This is how Kubernetes prevents privilege escalation. You can read more in the Kubernetes RBAC documentation.
You can then get credentials with the automatically generated service account.
Furthermore, Vault can also automatically create the role in addition to the service account and role binding by specifying the generated_role_rules parameter, which accepts a set of JSON or YAML rules for the generated role.
