docs: add templated policies workflow example to kubernetes auth (#25694)

--------- Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>
2026-05-04 12:01:23 +02:00 · 2024-03-01 15:11:14 -08:00 · 2024-03-01 15:11:14 -08:00 · 50aa6eea70
commit 50aa6eea70
parent 3229d546a1
2 changed files with 100 additions and 29 deletions
--- a/website/content/api-docs/auth/kubernetes.mdx
+++ b/website/content/api-docs/auth/kubernetes.mdx
@ -43,9 +43,13 @@ access the Kubernetes API.
  keys.
 - `disable_local_ca_jwt` `(bool: false)` - Disable defaulting to the local CA cert and service account JWT when running in a Kubernetes pod.
 - `use_annotations_as_alias_metadata` `(bool: false)` - Use annotations from the client token's associated service account
-  as alias metadata for the Vault entity. Only annotations with the prefix `vault.hashicorp.com/alias-metadata-` will be used.
-  For example, if an annotation "vault.hashicorp.com/alias-metadata-foo" is configured, "foo" with its value will be added
-  to the alias metadata. NOTE: Vault will need permission to read service accounts from the Kubernetes API.
+  as alias metadata for the Vault entity. Only annotations with the
+  `vault.hashicorp.com/alias-metadata-` key prefix are targeted as alias metadata and
+  your annotations must be 512 characters or less due to the Vault alias
+  metadata value limit. For example, if you configure the annotation
+  `vault.hashicorp.com/alias-metadata-foo`, Vault saves the string "foo" along
+  with the annotation value to the alias metadata. **To save alias metadata,
+  Vault must have permission to read service accounts from the Kubernetes API**.

 ### Deprecated parameters

@ -136,10 +140,10 @@ entities attempting to login.
 - `bound_service_account_namespaces` `(array: [])` - List of namespaces
  allowed to access this role. If set to "\*" all namespaces are allowed.
 - `bound_service_account_namespace_selector` `(string: "")` - A label selector for Kubernetes
-  namespaces allowed to acces this role. Accepts either a JSON or YAML object. The value
+  namespaces allowed to access this role. 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). Currently, label selectors with `matchExpressions` are not supported.
-  If this parameter is used, the Vault requires permissions to read namespaces on the Kubernetes
+  To use label selectors, **Vault must have permission to read namespaces** on the Kubernetes
  cluster. If set with `bound_service_account_namespaces`, the conditions are `OR`ed.
 - `audience` `(string: "")` - Optional Audience claim to verify in the JWT.
 - `alias_name_source` `(string: "serviceaccount_uid")` - Configures how identity aliases are generated.
--- a/website/content/docs/auth/kubernetes.mdx
+++ b/website/content/docs/auth/kubernetes.mdx
@ -76,8 +76,8 @@ management tool.

 1. Enable the Kubernetes auth method:

-  ```bash
-  vault auth enable kubernetes
+  ```shell-session
+  $ vault auth enable kubernetes
  ```

 1. Use the `/config` endpoint to configure Vault to talk to Kubernetes. Use
@ -85,8 +85,8 @@ management tool.
  For the list of available configuration options, please see the
  [API documentation](/vault/api-docs/auth/kubernetes).

-  ```bash
-  vault write auth/kubernetes/config \
+  ```shell-session
+  $ vault write auth/kubernetes/config \
      token_reviewer_jwt="<your reviewer service account JWT>" \
      kubernetes_host=https://192.168.99.100:<your TCP port or blank for 443> \
      kubernetes_ca_cert=@ca.crt
@ -102,8 +102,8 @@ management tool.

 1. Create a named role:

-  ```text
-  vault write auth/kubernetes/role/demo \
+  ```shell-session
+  $ vault write auth/kubernetes/role/demo \
      bound_service_account_names=myapp \
      bound_service_account_namespaces=default \
      policies=default \
@ -179,8 +179,8 @@ short-lived tokens. To use the local token and CA certificate, omit
 Vault will attempt to load them from `token` and `ca.crt` respectively inside
 the default mount folder `/var/run/secrets/kubernetes.io/serviceaccount/`.

-```bash
-vault write auth/kubernetes/config \
+```shell-session
+$ vault write auth/kubernetes/config \
    kubernetes_host=https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT
 ```

@ -201,12 +201,12 @@ everywhere but adds some operational overhead to maintain the cluster role
 bindings on the set of service accounts you want to be able to authenticate with
 Vault. Each client of Vault would need the `system:auth-delegator` ClusterRole:

-```bash
-kubectl create clusterrolebinding vault-client-auth-delegator \
-  --clusterrole=system:auth-delegator \
-  --group=group1 \
-  --serviceaccount=default:svcaccount1 \
-  ...
+```shell-session
+$ kubectl create clusterrolebinding vault-client-auth-delegator \
+    --clusterrole=system:auth-delegator \
+    --group=group1 \
+    --serviceaccount=default:svcaccount1 \
+    ...
 ```

 #### Continue using long-lived tokens
@ -215,8 +215,8 @@ You can create a long-lived secret using the instructions [here][k8s-create-secr
 and use that as the `token_reviewer_jwt`. In this example, the `vault` service
 account would need the `system:auth-delegator` ClusterRole:

-```bash
-kubectl apply -f - <<EOF
+```shell-session
+$ kubectl apply -f - <<EOF
 apiVersion: v1
 kind: Secret
 metadata:
@ -263,8 +263,8 @@ itself, instead of the old default of `kubernetes/serviceaccount`. If you are
 unable to check this value directly, you can run the following and look for the
 `"iss"` field to find the required value:

-```bash
-echo '{"apiVersion": "authentication.k8s.io/v1", "kind": "TokenRequest"}' \
+```shell-session
+$ echo '{"apiVersion": "authentication.k8s.io/v1", "kind": "TokenRequest"}' \
  | kubectl create -f- --raw /api/v1/namespaces/default/serviceaccounts/default/token \
  | jq -r '.status.token' \
  | cut -d . -f2 \
@ -274,16 +274,16 @@ echo '{"apiVersion": "authentication.k8s.io/v1", "kind": "TokenRequest"}' \
 Most clusters will also have that information available at the
 `.well-known/openid-configuration` endpoint:

-```bash
-kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
+```shell-session
+$ kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
 ```

 This value is then used when configuring Kubernetes auth, e.g.:

-```bash
-vault write auth/kubernetes/config \
-  kubernetes_host="https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT" \
-  issuer="\"test-aks-cluster-dns-d6cbb78e.hcp.uksouth.azmk8s.io\""
+```shell-session
+$ vault write auth/kubernetes/config \
+    kubernetes_host="https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT" \
+    issuer="\"test-aks-cluster-dns-d6cbb78e.hcp.uksouth.azmk8s.io\""
 ```

 ## Configuring kubernetes
@ -322,6 +322,73 @@ The Kubernetes Auth Plugin has a full HTTP API. Please see the

 [k8s-tokenreview]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#tokenreview-v1-authentication-k8s-io

+## Workflows
+
+Refer to the following workflow examples for Kubernetes auth method usage:
+
+### Working with templated policies
+
+Set `use_annotations_as_alias_metadata=true` in your Kubernetes auth
+configuration to use Kubernetes Service Account annotations for
+[Vault alias](/vault/docs/concepts/identity#entities-and-aliases) metadata.
+
+When `use_annotations_as_alias_metadata` is true, you can use the
+`identity.entity.aliases.<mount accessor>.metadata.<metadata key>` template
+parameter when you create [templated policies](/vault/docs/concepts/policies#templated-policies).
+
+To use annotations as alias metadata, you must give Vault permission to read
+service accounts from the Kubernetes API.
+
+#### Scenario Introduction
+
+Assume you have the following policy requirement:
+
+Applications can perform read operations on their allocated key/value secret path:
+`(env-kv/data/<env>)`
+
+#### Annotate Kubernetes Service Accounts with their dedicated secret paths
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: app
+  namespace: demo
+  annotations:
+    vault.hashicorp.com/alias-metadata-env: demo/app
+```
+
+When the application, `app`, logs in with JWT for the service account, Vault
+renders the alias metadata as `env : demo/app`.
+
+#### Create a templated ACL policy
+
+The `env-tmpl` policy lets applications read their secrets defined in KV v2
+secret engine. Use the mount accessor value
+(`auth_kubernetes_bcecb1e1`) from the [`sys/auth`](/vault/api-docs/system/auth) endpoint or the [`vault auth list`](/vault/docs/commands/auth/list) command.
+
+```shell-session
+$ tee env-tmpl.hcl <<EOF
+path "env-kv/data/{{identity.entity.aliases.auth_kubernetes_bcecb1e1.metadata.env}}" {
+  capabilities = [ "read" ]
+}
+EOF
+$ vault policy write env-tmpl env-tmpl.hcl
+```
+
+#### Create a Kubernetes role with the templated ACL policy
+
+The Kubernetes role lets users login as the `env-reader` role to read from the
+secret path described in the `env-tmpl` policy.
+
+```shell-session
+$ vault write auth/kubernetes/role/env-reader \
+    bound_service_account_names=app \
+    bound_service_account_namespaces=demo \
+    policies=default,env-tmpl \
+    ttl=1h
+```
+
 ## Code example

 The following example demonstrates the Kubernetes auth method to authenticate