Improve documentation for kubernetes.io/enforce-mountable-secrets annotation on ServiceAccount

Author: chansuke

content/en/docs/concepts/configuration/secret.md

@@ -677,6 +677,13 @@ There may be Secrets for several Pods on the same node. However, only the
 Secrets that a Pod requests are potentially visible within its containers.
 Therefore, one Pod does not have access to the Secrets of another Pod.
 
+### Configure least-privilege access to Secrets
+
+To enhance the security measures around Secrets, Kubernetes provides a mechanism: you can
+annotate a ServiceAccount as `kubernetes.io/enforce-mountable-secrets: "true"`.
+
+For more information, you can refer to the [documentation about this annotation](/docs/concepts/security/service-accounts/#enforce-mountable-secrets).
+
 {{< warning >}}
 Any containers that run with `privileged: true` on a node can access all
 Secrets used on that node.

content/en/docs/concepts/security/secrets-good-practices.md

@@ -62,6 +62,12 @@ recommendations include:
 *  Implement audit rules that alert on specific events, such as concurrent
    reading of multiple Secrets by a single user
 
+#### Additional ServiceAccount annotations for Secret management
+
+You can also use the `kubernetes.io/enforce-mountable-secrets` annotation on
+a ServiceAccount to enforce specific rules on how Secrets are used in a Pod.
+For more details, see the [documentation on this annotation](/docs/reference/labels-annotations-taints/#enforce-mountable-secrets).
+
 ### Improve etcd management policies
 
 Consider wiping or shredding the durable storage used by `etcd` once it is

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

@@ -196,6 +196,36 @@ or using a custom mechanism such as an [authentication webhook](/docs/reference/
 You can also use TokenRequest to obtain short-lived tokens for your external application.
 {{< /note >}}
 
+### Restricting access to Secrets {#enforce-mountable-secrets}
+
+Kubernetes provides an annotation called `kubernetes.io/enforce-mountable-secrets`
+that you can add to your ServiceAccounts. When this annotation is applied,
+the ServiceAccount's secrets can only be mounted on specified types of resources,
+enhancing the security posture of your cluster.
+
+You can add the annotation to a ServiceAccount using a manifest:
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  annotations:
+    kubernetes.io/enforce-mountable-secrets: "true"
+  name: my-serviceaccount
+  namespace: my-namespace
+```
+When this annotation is set to "true", the Kubernetes control plane ensures that
+the Secrets from this ServiceAccount are subject to certain mounting restrictions.
+
+1. The name of each Secret that is mounted as a volume in a Pod must appear in the `secrets` field of the
+   Pod's ServiceAccount.
+1. The name of each Secret referenced using `envFrom` in a Pod must also appear in the `secrets`
+   field of the Pod's ServiceAccount.
+1. The name of each Secret referenced using `imagePullSecrets` in a Pod must also appear in the `secrets`
+   field of the Pod's ServiceAccount.
+
+By understanding and enforcing these restrictions, cluster administrators can maintain a tighter security profile and ensure that secrets are accessed only by the appropriate resources.
+
 ## Authenticating service account credentials {#authenticating-credentials}
 
 ServiceAccounts use signed

content/en/docs/reference/access-authn-authz/admission-controllers.md

@@ -845,6 +845,10 @@ The Kubernetes project strongly recommends enabling this admission controller.
 You should enable this admission controller if you intend to make any use of Kubernetes
 `ServiceAccount` objects.
 
+Regarding the annotation `kubernetes.io/enforce-mountable-secrets`: While the annotation's name suggests it only concerns the mounting of Secrets,
+its enforcement also extends to other ways Secrets are used in the context of a Pod.
+Therefore, it is crucial to ensure that all the referenced secrets are correctly specified in the ServiceAccount.
+
 ### StorageObjectInUseProtection
 
 **Type**: Mutating.

content/en/docs/reference/labels-annotations-taints/_index.md

@@ -548,8 +548,23 @@ Example: `kubernetes.io/enforce-mountable-secrets: "true"`
 Used on: ServiceAccount
 
 The value for this annotation must be **true** to take effect.
-This annotation indicates that Pods running as this ServiceAccount may only reference
-Secret API objects specified in the ServiceAccount's `secrets` field.
+When you set this annotation  to "true", Kubernetes enforces the following rules for
+Pods running as this ServiceAccount:
+
+1. Secrets mounted as volumes must be listed in the ServiceAccount's `secrets` field.
+1. Secrets referenced in `envFrom` for containers (including sidecar containers and init containers)
+   must also be listed in the ServiceAccount's secrets field.
+   If any container in a Pod references a Secret not listed in the ServiceAccount's `secrets` field
+   (and even if the reference is marked as `optional`), then the Pod will fail to start,
+   and an error indicating the non-compliant secret reference will be generated.
+1. Secrets referenced in a Pod's `imagePullSecrets` must be present in the
+   ServiceAccount's `imagePullSecrets` field, the Pod will fail to start,
+   and an error indicating the non-compliant image pull secret reference will be generated.
+
+When you create or update a Pod, these rules are checked. If a Pod doesn't follow them, it won't start and you'll see an error message.
+If a Pod is already running and you change the `kubernetes.io/enforce-mountable-secrets` annotation
+to true, or you edit the associated ServiceAccount to remove the reference to a Secret
+that the Pod is already using, the Pod continues to run.
 
 ### node.kubernetes.io/exclude-from-external-load-balancers