Add API docs for Kubernetes secrets engine (#15564)
* Add API docs for Kubernetes secret engine * alphabetical ordering for K-items in docs sidebar Co-authored-by: Theron Voran <tvoran@users.noreply.github.com> Co-authored-by: Christopher Swenson <swenson@swenson.io>
This commit is contained in:
Tom Proctor
GitHub
parent
5f9386abad
commit
46b1a119dd
|
|
@ -83,7 +83,7 @@ $ curl \
|
|||
|
||||
## Read Config
|
||||
|
||||
Returns the previously configured config, including credentials.
|
||||
Returns the previously configured config, excluding credentials.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :------------------------ |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,368 @@
|
|||
---
|
||||
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)
|
||||
|
||||
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](/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")` -
|
||||
Kubernetes API URL to connect to. Must be specified if the standard pod environment
|
||||
variables `KUBERNETES_SERVICE_HOST` or `KUBERNETES_SERVICE_PORT` 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: <required>)` - The list of Kubernetes
|
||||
namespaces this role can generate credentials for. If set to `"*"` all
|
||||
namespaces are allowed.
|
||||
- `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](/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](/docs/configuration#default_lease_ttl) 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](/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](https://www.vaultproject.io/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 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: <required>)` - The name of the Kubernetes
|
||||
namespace in which to generate the credentials.
|
||||
- `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.
|
||||
|
||||
### 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..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -119,48 +119,6 @@
|
|||
"title": "Google Cloud KMS",
|
||||
"path": "secret/gcpkms"
|
||||
},
|
||||
{
|
||||
"title": "Key Management <sup>ENTERPRISE</sup>",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "secret/key-management"
|
||||
},
|
||||
{
|
||||
"title": "Azure Key Vault",
|
||||
"path": "secret/key-management/azurekeyvault"
|
||||
},
|
||||
{
|
||||
"title": "AWS KMS",
|
||||
"path": "secret/key-management/awskms"
|
||||
},
|
||||
{
|
||||
"title": "GCP Cloud KMS",
|
||||
"path": "secret/key-management/gcpkms"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "KMIP <sup>ENTERPRISE</sup>",
|
||||
"path": "secret/kmip"
|
||||
},
|
||||
{
|
||||
"title": "Key/Value",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "secret/kv"
|
||||
},
|
||||
{
|
||||
"title": "K/V Version 1",
|
||||
"path": "secret/kv/kv-v1"
|
||||
},
|
||||
{
|
||||
"title": "K/V Version 2",
|
||||
"path": "secret/kv/kv-v2"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Identity",
|
||||
"routes": [
|
||||
|
|
@ -227,6 +185,52 @@
|
|||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Key Management <sup>ENTERPRISE</sup>",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "secret/key-management"
|
||||
},
|
||||
{
|
||||
"title": "Azure Key Vault",
|
||||
"path": "secret/key-management/azurekeyvault"
|
||||
},
|
||||
{
|
||||
"title": "AWS KMS",
|
||||
"path": "secret/key-management/awskms"
|
||||
},
|
||||
{
|
||||
"title": "GCP Cloud KMS",
|
||||
"path": "secret/key-management/gcpkms"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Key/Value",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "secret/kv"
|
||||
},
|
||||
{
|
||||
"title": "K/V Version 1",
|
||||
"path": "secret/kv/kv-v1"
|
||||
},
|
||||
{
|
||||
"title": "K/V Version 2",
|
||||
"path": "secret/kv/kv-v2"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "KMIP <sup>ENTERPRISE</sup>",
|
||||
"path": "secret/kmip"
|
||||
},
|
||||
{
|
||||
"title": "Kubernetes",
|
||||
"path": "secret/kubernetes"
|
||||
},
|
||||
{
|
||||
"title": "MongoDB Atlas",
|
||||
"path": "secret/mongodbatlas"
|
||||
|
|
|
|||
|
|
@ -1014,6 +1014,23 @@
|
|||
"title": "Google Cloud KMS",
|
||||
"path": "secrets/gcpkms"
|
||||
},
|
||||
{
|
||||
"title": "Identity",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "secrets/identity"
|
||||
},
|
||||
{
|
||||
"title": "Identity Tokens",
|
||||
"path": "secrets/identity/identity-token"
|
||||
},
|
||||
{
|
||||
"title": "OIDC Identity Provider",
|
||||
"path": "secrets/identity/oidc-provider"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Key Management <sup>ENTERPRISE</sup>",
|
||||
"routes": [
|
||||
|
|
@ -1035,10 +1052,6 @@
|
|||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "KMIP <sup>ENTERPRISE</sup>",
|
||||
"path": "secrets/kmip"
|
||||
},
|
||||
{
|
||||
"title": "Key/Value",
|
||||
"routes": [
|
||||
|
|
@ -1057,25 +1070,12 @@
|
|||
]
|
||||
},
|
||||
{
|
||||
"title": "Kubernetes",
|
||||
"path": "secrets/kubernetes"
|
||||
"title": "KMIP <sup>ENTERPRISE</sup>",
|
||||
"path": "secrets/kmip"
|
||||
},
|
||||
{
|
||||
"title": "Identity",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "secrets/identity"
|
||||
},
|
||||
{
|
||||
"title": "Identity Tokens",
|
||||
"path": "secrets/identity/identity-token"
|
||||
},
|
||||
{
|
||||
"title": "OIDC Identity Provider",
|
||||
"path": "secrets/identity/oidc-provider"
|
||||
}
|
||||
]
|
||||
"title": "Kubernetes",
|
||||
"path": "secrets/kubernetes"
|
||||
},
|
||||
{
|
||||
"title": "MongoDB Atlas",
|
||||
|
|
|
|||
Loading…
Reference in New Issue