From 25fe403fdff9690283044ca36f0a03b137098e60 Mon Sep 17 00:00:00 2001
From: Mike Danese <mikedanese@gmail.com>
Date: Wed, 19 Sep 2018 16:07:04 -0700
Subject: [PATCH] TokenRequest feature documentation (#10295)

---
 .../configure-service-account.md              | 56 +++++++++++++++++--
 1 file changed, 51 insertions(+), 5 deletions(-)

diff --git a/content/en/docs/tasks/configure-pod-container/configure-service-account.md b/content/en/docs/tasks/configure-pod-container/configure-service-account.md
index 4065738187..6cd31372ac 100644
--- a/content/en/docs/tasks/configure-pod-container/configure-service-account.md
+++ b/content/en/docs/tasks/configure-pod-container/configure-service-account.md
@@ -250,12 +250,58 @@ spec:
 TODO: Test and explain how to use additional non-K8s secrets with an existing service account.
 -->
 
-## Service Account Volume Projection
+## Service Account Token Volume Projection
 
-Kubernetes 1.11 and higher supports a new way to project a service account token into a Pod.
-You can specify a token request with audiences, expirationSeconds. The service account token
-becomes invalid when the Pod is deleted. A Projected Volume named
-[ServiceAccountToken](/docs/concepts/storage/volumes/#projected) requests and stores the token.
+{{< feature-state for_k8s_version="v1.12" state="beta" >}}
+
+{{< note >}}
+**Note:** This ServiceAccountTokenVolumeProjection is __beta__ in 1.12 and
+enabled by passing all of the following flags to the API server:
+
+* `--service-account-issuer`
+* `--service-account-signing-key-file`
+* `--service-account-api-audiences`
+
+{{< /note >}}
+
+The kubelet can also project a service account token into a Pod. You can
+specify desired properties of the token, such as the audience and the validity
+duration. These properties are not configurable on the default service account
+token. The service account token will also become invalid against the API when
+the Pod or the ServiceAccount is deleted.
+
+This behavior is configured on a PodSpec using a ProjectedVolume type called
+[ServiceAccountToken](/docs/concepts/storage/volumes/#projected). To provide a
+pod with a token with an audience of "vault" and a validity duration of two
+hours, you would configure the following in your PodSpec:
+
+```yaml
+kind: Pod
+apiVersion: v1
+spec:
+  containers:
+  - image: nginx
+    name: nginx
+    volumeMounts:
+    - mountPath: /var/run/secrets/tokens
+      name: vault-token
+  volumes:
+  - name: vault-token
+    projected:
+      sources:
+      - serviceAccountToken:
+          path: vault-token
+          expirationSeconds: 7200
+          audience: vault
+```
+
+The kubelet will request and store the token on behalf of the pod, make the
+token avaialble to the pod at a configurable file path, and refresh the token as
+it approaches expiration. Kubelet proactively rotates the token if it is older
+than 80% of its total TTL, or if the token is older than 24 hours.
+
+The application is responsible for reloading the token when it rotates. Periodic
+reloading (e.g. once every 5 minutes) is sufficient for most usecases.
 
 {{% /capture %}}