Merge pull request #43958 from enj/enj/d/sa_node_ref

KEP-4193: bound service account token improvements

content/en/docs/concepts/security/service-accounts.md

@@ -217,7 +217,8 @@ request. The API server checks the validity of that bearer token as follows:
 
 The TokenRequest API produces _bound tokens_ for a ServiceAccount. This
 binding is linked to the lifetime of the client, such as a Pod, that is acting
-as that ServiceAccount.
+as that ServiceAccount.  See [Token Volume Projection](/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection)
+for an example of a bound pod service account token's JWT schema and payload.
 
 For tokens issued using the `TokenRequest` API, the API server also checks that
 the specific object reference that is using the ServiceAccount still exists,
@@ -239,7 +240,7 @@ account credentials, you can use the following methods:
 
 The Kubernetes project recommends that you use the TokenReview API, because
 this method invalidates tokens that are bound to API objects such as Secrets,
-ServiceAccounts, and Pods when those objects are deleted. For example, if you
+ServiceAccounts, Pods or Nodes when those objects are deleted. For example, if you
 delete the Pod that contains a projected ServiceAccount token, the cluster
 invalidates that token immediately and a TokenReview immediately fails.
 If you use OIDC validation instead, your clients continue to treat the token

content/en/docs/reference/access-authn-authz/service-accounts-admin.md

@@ -1,9 +1,7 @@
 ---
 reviewers:
-  - bprashanth
-  - davidopp
-  - lavalamp
   - liggitt
+  - enj
 title: Managing Service Accounts
 content_type: concept
 weight: 50

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -184,6 +184,10 @@ For a reference to old feature gates that are removed, please refer to
 | `SELinuxMountReadWriteOncePod` | `true` | Beta | 1.28 | |
 | `SchedulerQueueingHints` | `true` | Beta | 1.28 | |
 | `SecurityContextDeny` | `false` | Alpha | 1.27 | |
+| `ServiceAccountTokenJTI` | `false` | Alpha | 1.29 | |
+| `ServiceAccountTokenNodeBinding` | `false` | Alpha | 1.29 | |
+| `ServiceAccountTokenNodeBindingValidation` | `false` | Alpha | 1.29 | |
+| `ServiceAccountTokenPodNodeInfo` | `false` | Alpha | 1.29 | |
 | `SidecarContainers` | `false` | Alpha | 1.28 | 1.28 |
 | `SidecarContainers` | `true` | Beta | 1.29 | |
 | `SizeMemoryBackedVolumes` | `false` | Alpha | 1.20 | 1.21 |
@@ -727,6 +731,12 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `ServerSideFieldValidation`: Enables server-side field validation. This means the validation
   of resource schema is performed at the API server side rather than the client side
   (for example, the `kubectl create` or `kubectl apply` command line).
+- `ServiceAccountTokenJTI`: Controls whether JTIs (UUIDs) are embedded into generated service account tokens,
+  and whether these JTIs are recorded into the Kubernetes audit log for future requests made by these tokens.
+- `ServiceAccountTokenNodeBinding`: Controls whether the apiserver allows binding service account tokens to Node objects.
+- `ServiceAccountTokenNodeBindingValidation`: Controls whether the apiserver will validate a Node reference in service account tokens.
+- `ServiceAccountTokenPodNodeInfo`: Controls whether the apiserver embeds the node name and uid
+  for the associated node when issuing service account tokens bound to Pod objects.
 - `SidecarContainers`: Allow setting the `restartPolicy` of an init container to
   `Always` so that the container becomes a sidecar container (restartable init containers).
   See

content/en/docs/tasks/configure-pod-container/configure-service-account.md

@@ -1,6 +1,6 @@
 ---
 reviewers:
-- bprashanth
+- enj
 - liggitt
 - thockin
 title: Configure Service Accounts for Pods
@@ -184,6 +184,16 @@ ServiceAccount. You can request a specific token duration using the `--duration`
 command line argument to `kubectl create token` (the actual duration of the issued
 token might be shorter, or could even be longer).
 
+When the `ServiceAccountTokenNodeBinding` and `ServiceAccountTokenNodeBindingValidation`
+features are enabled and the `KUBECTL_NODE_BOUND_TOKENS` enviroment variable is set to `true`,
+it is possible to create a service account token that is directly bound to a `Node`:
+
+```shell
+KUBECTL_NODE_BOUND_TOKENS=true kubectl create token build-robot --bound-object-kind Node --bound-object-name node-001 --bound-object-uid 123...456
+```
+
+The token will be valid until it expires or either the assocaited `Node` or service account are deleted.
+
 {{< note >}}
 Versions of Kubernetes before v1.22 automatically created long term credentials for
 accessing the Kubernetes API. This older mechanism was based on creating token Secrets
@@ -408,6 +418,39 @@ You can configure this behavior for the `spec` of a Pod using a
 [projected volume](/docs/concepts/storage/volumes/#projected) type called
 `ServiceAccountToken`.
 
+The token from this projected volume is a {{<glossary_tooltip term_id="jwt" text="JSON Web Token">}}  (JWT).
+The JSON payload of this token follows a well defined schema - an example payload for a pod bound token:
+
+```yaml
+{
+  "aud": [  # matches the requested audiences, or the API server's default audiences when none are explicitly requested
+    "https://kubernetes.default.svc"
+  ],
+  "exp": 1731613413,
+  "iat": 1700077413,
+  "iss": "https://kubernetes.default.svc",  # matches the first value passed to the --service-account-issuer flag
+  "jti": "ea28ed49-2e11-4280-9ec5-bc3d1d84661a",  # ServiceAccountTokenJTI feature must be enabled for the claim to be present
+  "kubernetes.io": {
+    "namespace": "kube-system",
+    "node": {  # ServiceAccountTokenPodNodeInfo feature must be enabled for the API server to add this node reference claim
+      "name": "127.0.0.1",
+      "uid": "58456cb0-dd00-45ed-b797-5578fdceaced"
+    },
+    "pod": {
+      "name": "coredns-69cbfb9798-jv9gn",
+      "uid": "778a530c-b3f4-47c0-9cd5-ab018fb64f33"
+    },
+    "serviceaccount": {
+      "name": "coredns",
+      "uid": "a087d5a0-e1dd-43ec-93ac-f13d89cd13af"
+    },
+    "warnafter": 1700081020
+  },
+  "nbf": 1700077413,
+  "sub": "system:serviceaccount:kube-system:coredns"
+}
+```
+
 ### Launch a Pod using service account token projection
 
 To provide a Pod with a token with an audience of `vault` and a validity duration