Kubernetes secrets engine (API)
This is the API documentation for the Vault Kubernetes secrets engine. To learn more about the usage and operation, see the Kubernetes secrets engine documentation.
This documentation assumes the Kubernetes secrets engine is mounted at the /kubernetes
path in Vault. Since it is possible to enable secrets engines at any location, please update your API calls accordingly.
Write configuration
This endpoint configures the plugin with the necessary information to reach the Kubernetes API and authenticate with it.
Parameters
kubernetes_host
(string: "https://$KUBERNETES_SERVICE_HOST:KUBERNETES_SERVICE_PORT_HTTPS")
- Kubernetes API URL to connect to. Must be specified if the standard pod environment variablesKUBERNETES_SERVICE_HOST
orKUBERNETES_SERVICE_PORT_HTTPS
are not set.kubernetes_ca_cert
(string: "")
- PEM encoded CA certificate to verify the Kubernetes API server certificate. Defaults to the local pod's CA certificate at/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
if found, or otherwise the host's root CA set.service_account_jwt
(string: "")
- The JSON web token of the service account used by the secrets engine to manage Kubernetes credentials. Defaults to the local pod's JWT at/var/run/secrets/kubernetes.io/serviceaccount/token
if found.disable_local_ca_jwt
(bool: false)
- Disable defaulting to the local CA certificate and service account JWT when running in a Kubernetes pod.
Sample payload
Sample request
Read configuration
Returns the config previously set, excluding credentials.
Sample request
Sample response
Delete configuration
Deletes the config previously set.
Sample request
Create role
A role configures what service account tokens can be generated, and what permissions will be attached to them. The permissions attached to a service account token depend on the Kubernetes roles applied to its service account.
Each Kubernetes secrets engine role can operate in one of 3 modes. Each successive mode generates more Kubernetes objects, and therefore requires more permissions for Vault's own Kubernetes service account.
Generate a service account token for a pre-existing service account - set
service_account_name
.Generate a service account and a token, and bind a pre-existing Kubernetes role - set
kubernetes_role_name
.Generate a Kubernetes role, role binding, service account and token - set
generated_role_rules
.
Only one of service_account_name
, kubernetes_role_name
or generated_role_rules
can be set.
Parameters
name
(string: <required>)
- The name of the role. Included in the path.allowed_kubernetes_namespaces
(array: [])
- The list of Kubernetes namespaces this role can generate credentials for. If set to"*"
all namespaces are allowed. If set withallowed_kubernetes_namespace_selector
, the conditions areOR
ed.allowed_kubernetes_namespace_selector
(string: "")
- A label selector for Kubernetes namespaces in which credentials can be generated. Accepts either a JSON or YAML object. The value should be of type LabelSelector as illustrated in Sample Payload 4 and Sample Payload 5 below. If set withallowed_kubernetes_namespaces
, the conditions areOR
ed.token_max_ttl
(string: "")
- The maximum TTL for generated Kubernetes tokens, specified in seconds or as a Go duration format string, e.g."1h"
. If not set or set to 0, the system default will be used.token_default_ttl
(string: "")
- The default TTL for generated Kubernetes tokens, specified in seconds or as a Go duration format string, e.g."1h"
. If not set or set to 0, the system default will be used.token_default_audiences
(string: "")
- The default intended audiences for generated Kubernetes tokens, specified by a comma separated string. e.g"custom-audience-0,custom-audience-1"
. If not set or set to""
, the Kubernetes cluster default for audiences of service account tokens will be used.service_account_name
(string: "")
- The pre-existing service account to generate tokens for. Mutually exclusive with all role parameters. If set, only a Kubernetes token will be created when credentials are requested. See the Kubernetes service account documentation for more details on service accounts.kubernetes_role_name
(string: "")
- The pre-existing Role or ClusterRole to bind a generated service account to. If set, Kubernetes token, service account, and role binding objects will be created when credentials are requested. See the Kubernetes roles documentation for more details on Kubernetes roles.kubernetes_role_type
(string: "Role")
- Specifies whether the Kubernetes role is aRole
orClusterRole
.generated_role_rules
(string: "")
- The Role or ClusterRole rules to use when generating a role. Accepts either JSON or YAML formatted rules. If set, the entire chain of Kubernetes objects will be generated when credentials are requested. The value should be arules
key with an array of PolicyRule objects, as illustrated in the Kubernetes RBAC documentation and Sample Payload 3 below.name_template
(string: "")
- The name template to use when generating service accounts, roles and role bindings. If unset, a default template is used. See username templating for details on how to write a custom template.extra_annotations
(map<string|string>: nil)
- Additional annotations to apply to all generated Kubernetes objects. See the Kubernetes annotations documentation for more details on annotations.extra_labels
(map<string|string>: nil)
- Additional labels to apply to all generated Kubernetes objects. See the Kubernetes labels documentation for more details on labels.
Sample payload 1
To generate tokens for a pre-existing service account:
Sample payload 2
To generate tokens for a pre-existing ClusterRole:
Sample payload 3
To generate tokens for a defined set of Kubernetes role rules:
Or to define the same rules as JSON:
Sample payload 4
To generate tokens in namespaces based on a label selector for the namespaces:
Or to define the same selector as JSON:
Sample payload 5
To generate tokens in namespaces based on a label selector for the namespaces and via a normal namespace array:
In the payload above, the token can be generated for any namespace that either contains the labels defined in the selector, or is named vault-system
or testing
.
Sample request
Read role
Returns the previously configured role.
Parameters
name
(string: <required>)
- Name of the role.
Sample request
Sample response
List roles
Lists all the roles that are configured.
Sample request
Sample response
Delete role
Deletes the previously configured role.
Parameters
role
(string: <required>)
- Name of the role.
Sample request
Generate credentials
Generate a service account token.
Parameters
role
(string: <required>)
- Name of the role to generate credentials for.kubernetes_namespace
(string)
- The name of the Kubernetes namespace in which to generate the credentials. Optional if the Vault role is configured with a single namespace that is not"*"
; required otherwise.cluster_role_binding
(bool: false)
- If true, generate a ClusterRoleBinding to grant permissions across the whole cluster instead of within a namespace. Requires the Vault role to havekubernetes_role_type
set to ClusterRole.ttl
(string: "")
- The TTL of the generated Kubernetes service account token, specified in seconds or as a Go duration format string, e.g."1h"
. The TTL returned may be different from the TTL specified due to limits specified in Kubernetes, Vault system-wide controls, or role-specific controls.audiences
(string: "")
- A comma separated string containing the intended audiences of the generated Kubernetes service account the token, e.g."custom-audience-0,custom-audience-1"
. If not set or set to""
, the token_default_audiences will be used.
Sample payload
Sample request
Sample response
Last updated