Docs/auth kubernetes 1.9.3

website/content/api-docs/auth/kubernetes.mdx

@@ -29,8 +29,10 @@ access the Kubernetes API.
 
 - `kubernetes_host` `(string: <required>)` - Host must be a host string, a host:port pair, or a URL to the base of the Kubernetes API server.
 - `kubernetes_ca_cert` `(string: "")` - PEM encoded CA cert for use by the TLS client used to talk with the Kubernetes API. NOTE: Every line must end with a newline: `\n`
+  If not set, the local CA cert will be used if running in a Kubernetes pod.
 - `token_reviewer_jwt` `(string: "")` - A service account JWT used to access the TokenReview
   API to validate other JWTs during login. If not set,
+  the local service account token is used if running in a Kubernetes pod, otherwise
   the JWT submitted in the login payload will be used to access the Kubernetes TokenReview API.
 - `pem_keys` `(array: [])` - Optional list of PEM-formatted public keys or certificates
   used to verify the signatures of Kubernetes service account

website/content/docs/auth/kubernetes.mdx

@@ -125,9 +125,8 @@ Kubernetes auth:
 * The value of the JWT's `"iss"` claim depends on the cluster's configuration.
 
 The changes to token lifetime are important when configuring the
-[`token_reviewer_jwt`](/api-docs/auth/kubernetes#token_reviewer_jwt) option. You
-must avoid using a short-lived token because Vault stores that token in Vault
-storage and does not automatically refresh it. If a short-lived token is used,
+[`token_reviewer_jwt`](/api-docs/auth/kubernetes#token_reviewer_jwt) option.
+If a short-lived token is used,
 Kubernetes will revoke it as soon as the pod or service account are deleted, or
 if the expiry time passes, and Vault will no longer be able to use the
 `TokenReview` API. See [How to work with short-lived Kubernetes tokens][short-lived-tokens]
@@ -155,6 +154,7 @@ table summarizes the options, each of which is explained in more detail below.
 
 | Option                               | All tokens are short-lived | Can revoke tokens early | Other considerations |
 | ------------------------------------ | -------------------------- | ----------------------- | -------------------- |
+| Use local token as reviewer JWT      | Yes                        | Yes                     | Requires Vault (1.9.3+) to be deployed on the Kubernetes cluster |
 | Use client JWT as reviewer JWT       | Yes                        | Yes                     | Operational overhead |
 | Use long-lived token as reviewer JWT | No                         | Yes                     |                      |
 | Use JWT auth instead                 | Yes                        | No                      |                      |
@@ -168,6 +168,25 @@ short-lived tokens. If you would like to disable this, set
 
 [k8s-extended-tokens]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/#options
 
+#### Use local service account token as the reviewer JWT
+
+When running Vault in a Kubernetes pod the recommended option is to use the pod's local
+service account token. Vault will periodically re-read the file to support
+short-lived tokens. To use the local token and CA certificate, omit
+`token_reviewer_jwt` and `kubernetes_ca_cert` when configuring the auth method.
+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 \
+    kubernetes_host=https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_PORT
+```
+
+!> **Note:** Requires Vault 1.9.3+. In earlier versions the service account
+token and CA certificate is read once and stored in Vault storage.
+When the service account token expires or is revoked, Vault will no longer be
+able to use the `TokenReview` API and client authentication will fail.
+
 #### Use the Vault client's JWT as the reviewer JWT
 
 When configuring Kubernetes auth, you can omit the `token_reviewer_jwt`, and Vault