vault/website/content/api-docs/secret/kubernetes.mdx

---
layout: api
page_title: Kubernetes - Secrets Engines - HTTP API
description: This is the API documentation for the Vault Kubernetes secrets engine.
---

# Kubernetes Secrets Engine (API)

@include 'x509-sha1-deprecation.mdx'

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](/vault/docs/secrets/kubernetes).

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

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

### Sample Request

```shell-session
$ 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

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

### Sample Response

```json
{
  "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

```shell-session
$ 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
  `OR`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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta)
  as illustrated in [Sample Payload 4](/vault/api-docs/secret/kubernetes#sample-payload-4) and
  [Sample Payload 5](/vault/api-docs/secret/kubernetes#sample-payload-5) below.
  If set with `allowed_kubernetes_namespaces`, the conditions are `OR`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](/vault/docs/configuration#max_lease_ttl) 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](/vault/docs/configuration#default_lease_ttl) 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](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/)
  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](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole)
  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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#policyrule-v1-rbac-authorization-k8s-io)
  objects, as illustrated in the
  [Kubernetes RBAC documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
  and [Sample Payload 3](/vault/api-docs/secret/kubernetes#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](/vault/docs/concepts/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](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)
  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](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
  for more details on labels.

### Sample Payload 1

To generate tokens for a pre-existing service account:

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

### Sample Payload 2

To generate tokens for a pre-existing ClusterRole:

```json
{
  "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:

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

Or to define the same rules as JSON:

```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:

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

Or to define the same selector as JSON:

```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:

```json
{
  "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

```shell-session
$ 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

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

### Sample Response

```json
{
  "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

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

### Sample Response

```json
{
  "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

```shell-session
$ 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](/vault/api-docs/secret/kubernetes#token_default_audiences) will be used.

### Sample Payload

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

### Sample Request

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

### Sample Response

```json
{
  "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..."
  }
}
```