Kubernetes secrets engine (API)

warning

Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround. See the deprecation FAQ for more information.

This is the API documentation for the OpenBao 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 OpenBao. 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 OpenBao'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": "openbao-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: openbao",
  "service_account_name": "default",
}

Or to define the same selector as JSON:

{
  "allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'openbao'}}",
  "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": "openbao-system,testing",
  "allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'openbao'}}",
  "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 openbao-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`

Parameters

after (string: "") - Optional entry to begin listing after for pagination; not required to exist.
limit (int: 0) - Optional number of entries to return; defaults to all entries.

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 OpenBao 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 OpenBao 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, OpenBao 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..."
  }
}

Write configuration​

Parameters​

Sample payload​

Sample request​

Read configuration​

Sample request​

Sample response​

Delete configuration​

Sample request​

Create role​

Parameters​

Sample payload 1​

Sample payload 2​

Sample payload 3​

Sample payload 4​

Sample payload 5​

Sample request​

Read role​

Parameters​

Sample request​

Sample response​

List roles​

Parameters​

Sample request​

Sample response​

Delete role​

Parameters​

Sample request​

Generate credentials​

Parameters​

Sample payload​

Sample request​

Sample response​

Write configuration

Parameters

Sample payload

Sample request

Read configuration

Sample request

Sample response

Delete configuration

Sample request

Create role

Parameters

Sample payload 1

Sample payload 2

Sample payload 3

Sample payload 4

Sample payload 5

Sample request

Read role

Parameters

Sample request

Sample response

List roles

Parameters

Sample request

Sample response

Delete role

Parameters

Sample request

Generate credentials

Parameters

Sample payload

Sample request

Sample response