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.

Method	Path
POST	/kubernetes/config

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 variables KUBERNETES_SERVICE_HOST or KUBERNETES_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

{
  "kubernetes_host": "https://192.168.99.100:8443",
  "kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----\n.....\n-----END CERTIFICATE-----"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/kubernetes/config

Read configuration

Returns the config previously set, excluding credentials.

Method	Path
GET	/kubernetes/config

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/kubernetes/config

Sample response

{
  "data":{
    "kubernetes_host": "https://192.168.99.100:8443",
    "kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----.....-----END CERTIFICATE-----",
    "disable_local_ca_jwt": false
  }
}

Delete configuration

Deletes the config previously set.

Method	Path
DELETE	/kubernetes/config

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE
    http://127.0.0.1:8200/v1/kubernetes/config

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.

Method	Path
POST	/kubernetes/roles/:name

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 with allowed_kubernetes_namespace_selector, the conditions are ORed.

• 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 with allowed_kubernetes_namespaces, the conditions are ORed.

• 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 a Role or ClusterRole.

• 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 a rules 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:

{
  "allowed_kubernetes_namespaces": "*",
  "service_account_name": "default",
  "token_max_ttl": "24h"
}

Sample payload 2

To generate tokens for a pre-existing ClusterRole:

{
  "allowed_kubernetes_namespaces": "*",
  "kubernetes_role_type": "ClusterRole",
  "kubernetes_role_name": "vault-k8s-secrets-role"
}

Sample payload 3

To generate tokens for a defined set of Kubernetes role rules:

{
  "allowed_kubernetes_namespaces": "*",
  "generated_role_rules": "rules:\n- apiGroups: [\"\"]\n  resources: [\"pods\"]\n  verbs: [\"list\"]\n",
}

Or to define the same rules as JSON:

{
  "allowed_kubernetes_namespaces": "*",
  "generated_role_rules": "'rules': [{'apiGroups': [''],'resources': ['pods'],'verbs': ['list']}]"
}

Sample payload 4

To generate tokens in namespaces based on a label selector for the namespaces:

{
  "allowed_kubernetes_namespace_selector": "matchLabels:\n  stage: prod\n  sa-generator: vault",
  "service_account_name": "default",
}

Or to define the same selector as JSON:

{
  "allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'vault'}}",
  "service_account_name": "default",
}

Sample payload 5

To generate tokens in namespaces based on a label selector for the namespaces and via a normal namespace array:

{
  "allowed_kubernetes_namespaces": "vault-system,testing",
  "allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'vault'}}",
  "service_account_name": "default",
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/kubernetes/roles/default-role

Read role

Returns the previously configured role.

Method	Path
GET	/kubernetes/roles/:name

Parameters

• name (string: <required>) - Name of the role.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/kubernetes/role/default-role

Sample response

{
  "data": {
    "additional_metadata": {},
    "allowed_kubernetes_namespaces": [
      "*"
    ],
    "generated_role_rules": "",
    "kubernetes_role_name": "",
    "kubernetes_role_type": "Role",
    "name": "default-role",
    "name_template": "",
    "service_account_name": "default",
    "token_default_ttl": 0,
    "token_max_ttl": 86400
  }
}

List roles

Lists all the roles that are configured.

Method	Path
LIST	/kubernetes/roles
GET	/kubernetes/roles?list=true

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/kubernetes/roles

Sample response

{
  "data": {
    "keys": ["default-role", "prod-role"]
  }
}

Delete role

Deletes the previously configured role.

Method	Path
DELETE	/kubernetes/roles/:role

Parameters

• role (string: <required>) - Name of the role.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/kubernetes/role/default-role

Generate credentials

Generate a service account token.

Method	Path
POST	/kubernetes/creds/:role

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 have kubernetes_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

{
  "kubernetes_namespace": "default",
  "ttl": "1h"
}

Sample request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/kubernetes/creds/default-role

Sample response

{
  "request_id": "58fefc6c-5195-c17a-94f2-8f889f3df57c",
  "lease_id": "kubernetes/creds/default-role/aWczfcfJ7NKUdiirJrPXIs38",
  "renewable": false,
  "lease_duration": 3600,
  "data": {
    "service_account_name": "default",
    "service_account_namespace": "default",
    "service_account_token": "eyJhbG..."
  }
}