diff --git a/website/content/api-docs/auth/kubernetes.mdx b/website/content/api-docs/auth/kubernetes.mdx index 7641d9ffb3..4d79630c21 100644 --- a/website/content/api-docs/auth/kubernetes.mdx +++ b/website/content/api-docs/auth/kubernetes.mdx @@ -83,7 +83,7 @@ $ curl \ ## Read Config -Returns the previously configured config, including credentials. +Returns the previously configured config, excluding credentials. | Method | Path | | :----- | :------------------------ | diff --git a/website/content/api-docs/secret/kubernetes.mdx b/website/content/api-docs/secret/kubernetes.mdx new file mode 100644 index 0000000000..f52bca4cfe --- /dev/null +++ b/website/content/api-docs/secret/kubernetes.mdx @@ -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: )` - 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. +- `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: 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: 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: )` - 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: )` - 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: )` - Name of the role to generate credentials for. +- `kubernetes_namespace` `(string: )` - 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..." + } +} +``` diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index b9f376278d..52b3db9bfb 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -119,48 +119,6 @@ "title": "Google Cloud KMS", "path": "secret/gcpkms" }, - { - "title": "Key Management ENTERPRISE", - "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 ENTERPRISE", - "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 ENTERPRISE", + "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 ENTERPRISE", + "path": "secret/kmip" + }, + { + "title": "Kubernetes", + "path": "secret/kubernetes" + }, { "title": "MongoDB Atlas", "path": "secret/mongodbatlas" diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 06009836dd..9c296192c1 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -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 ENTERPRISE", "routes": [ @@ -1035,10 +1052,6 @@ } ] }, - { - "title": "KMIP ENTERPRISE", - "path": "secrets/kmip" - }, { "title": "Key/Value", "routes": [ @@ -1057,25 +1070,12 @@ ] }, { - "title": "Kubernetes", - "path": "secrets/kubernetes" + "title": "KMIP ENTERPRISE", + "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",