Update CSR docs with expirationSeconds field details

Signed-off-by: Monis Khan <mok@vmware.com>

content/en/docs/reference/access-authn-authz/certificate-signing-requests.md

@@ -32,6 +32,9 @@ The CertificateSigningRequest object includes a PEM-encoded PKCS#10 signing requ
 the `spec.request` field. The CertificateSigningRequest denotes the signer (the
 recipient that the request is being made to) using the `spec.signerName` field.
 Note that `spec.signerName` is a required key after API version `certificates.k8s.io/v1`.
+In Kubernetes v1.22 and later, clients may optionally set the `spec.expirationSeconds`
+field to request a particular lifetime for the issued certificate.  The minimum valid
+value for this field is `600`, i.e. ten minutes.
 
 Once created, a CertificateSigningRequest must be approved before it can be signed.
 Depending on the signer selected, a CertificateSigningRequest may be automatically approved
@@ -70,8 +73,8 @@ This includes:
 1. **Permitted subjects**: any restrictions on and behavior when a disallowed subject is requested.
 1. **Permitted x509 extensions**: including IP subjectAltNames, DNS subjectAltNames, Email subjectAltNames, URI subjectAltNames etc, and behavior when a disallowed extension is requested.
 1. **Permitted key usages / extended key usages**: any restrictions on and behavior when usages different than the signer-determined usages are specified in the CSR.
-1. **Expiration/certificate lifetime**: whether it is fixed by the signer, configurable by the admin, determined by the CSR object etc
-   and the behavior when an expiration is different than the signer-determined expiration that is specified in the CSR.
+1. **Expiration/certificate lifetime**: whether it is fixed by the signer, configurable by the admin, determined by the CSR `spec.expirationSeconds` field, etc
+   and the behavior when the signer-determined expiration is different from the CSR `spec.expirationSeconds` field.
 1. **CA bit allowed/disallowed**: and behavior if a CSR contains a request a for a CA certificate when the signer does not permit it.
 
 Commonly, the `status.certificate` field contains a single PEM-encoded X.509
@@ -81,15 +84,19 @@ that case, the documentation for the signer should specify the meaning of
 additional certificates; for example, this might be the certificate plus
 intermediates to be presented during TLS handshakes.
 
-The PKCS#10 signing request format does not allow to specify a certificate
-expiration or lifetime. The expiration or lifetime therefore has to be set
-through e.g. an annotation on the CSR object. While it's theoretically
-possible for a signer to use that expiration date, there is currently no
-known implementation that does. (The built-in signers all use the same
-`ClusterSigningDuration` configuration option, which defaults to 1 year,
-and can be changed with the `--cluster-signing-duration` command-line
-flag of the kube-controller-manager.)
+The PKCS#10 signing request format does not have a standard mechanism to specify a
+certificate expiration or lifetime. The expiration or lifetime therefore has to be set
+through the `spec.expirationSeconds` field of the CSR object. The built-in signers
+use the `ClusterSigningDuration` configuration option, which defaults to 1 year,
+(the `--cluster-signing-duration` command-line flag of the kube-controller-manager)
+as the default when no `spec.expirationSeconds` is specified.  When `spec.expirationSeconds`
+is specified, the minimum of `spec.expirationSeconds` and `ClusterSigningDuration` is
+used.
 
+{{< note >}}
+The `spec.expirationSeconds` field was added in Kubernetes v1.22.  Earlier versions of Kubernetes do not honor this field.
+Kubernetes API servers prior to v1.22 will silently drop this field when the object is created.
+{{< /note >}}
 
 ### Kubernetes signers
 
@@ -105,8 +112,8 @@ Kubernetes provides built-in signers that each have a well-known `signerName`:
        but it is often not the only cluster-admin subject in a cluster.
     1. Permitted x509 extensions - honors subjectAltName and key usage extensions and discards other extensions.
     1. Permitted key usages - must include `["client auth"]`. Must not include key usages beyond `["digital signature", "key encipherment", "client auth"]`.
-    1. Expiration/certificate lifetime - set by the `--cluster-signing-duration` option for the
-       kube-controller-manager implementation of this signer.
+    1. Expiration/certificate lifetime - for the kube-controller-manager implementation of this signer, set to the minimum
+       of the `--cluster-signing-duration` option or, if specified, the `spec.expirationSeconds` field of the CSR object.
     1. CA bit allowed/disallowed - not allowed.
 
 1. `kubernetes.io/kube-apiserver-client-kubelet`: signs client certificates that will be honored as client certificates by the
@@ -117,8 +124,8 @@ Kubernetes provides built-in signers that each have a well-known `signerName`:
     1. Permitted subjects - organizations are exactly `["system:nodes"]`, common name starts with "`system:node:`".
     1. Permitted x509 extensions - honors key usage extensions, forbids subjectAltName extensions and drops other extensions.
     1. Permitted key usages - exactly `["key encipherment", "digital signature", "client auth"]`.
-    1. Expiration/certificate lifetime - set by the `--cluster-signing-duration` option for the
-       kube-controller-manager implementation of this signer.
+    1. Expiration/certificate lifetime - for the kube-controller-manager implementation of this signer, set to the minimum
+       of the `--cluster-signing-duration` option or, if specified, the `spec.expirationSeconds` field of the CSR object.
     1. CA bit allowed/disallowed - not allowed.
 
 1. `kubernetes.io/kubelet-serving`: signs serving certificates that are honored as a valid kubelet serving certificate
@@ -130,8 +137,8 @@ Kubernetes provides built-in signers that each have a well-known `signerName`:
     1. Permitted x509 extensions - honors key usage and DNSName/IPAddress subjectAltName extensions, forbids EmailAddress and
        URI subjectAltName extensions, drops other extensions. At least one DNS or IP subjectAltName must be present.
     1. Permitted key usages - exactly `["key encipherment", "digital signature", "server auth"]`.
-    1. Expiration/certificate lifetime - set by the `--cluster-signing-duration` option for the
-       kube-controller-manager implementation of this signer.
+    1. Expiration/certificate lifetime - for the kube-controller-manager implementation of this signer, set to the minimum
+       of the `--cluster-signing-duration` option or, if specified, the `spec.expirationSeconds` field of the CSR object.
     1. CA bit allowed/disallowed - not allowed.
 
 1. `kubernetes.io/legacy-unknown`:  has no guarantees for trust at all. Some third-party distributions of Kubernetes
@@ -142,14 +149,19 @@ Kubernetes provides built-in signers that each have a well-known `signerName`:
     1. Permitted subjects - any
     1. Permitted x509 extensions - honors subjectAltName and key usage extensions and discards other extensions.
     1. Permitted key usages - any
-    1. Expiration/certificate lifetime - set by the `--cluster-signing-duration` option for the
-       kube-controller-manager implementation of this signer.
+    1. Expiration/certificate lifetime - for the kube-controller-manager implementation of this signer, set to the minimum
+       of the `--cluster-signing-duration` option or, if specified, the `spec.expirationSeconds` field of the CSR object.
     1. CA bit allowed/disallowed - not allowed.
 
 {{< note >}}
 Failures for all of these are only reported in kube-controller-manager logs.
 {{< /note >}}
 
+{{< note >}}
+The `spec.expirationSeconds` field was added in Kubernetes v1.22.  Earlier versions of Kubernetes do not honor this field.
+Kubernetes API servers prior to v1.22 will silently drop this field when the object is created.
+{{< /note >}}
+
 Distribution of trust happens out of band for these signers.  Any trust outside of those described above are strictly
 coincidental. For instance, some distributions may honor `kubernetes.io/legacy-unknown` as client certificates for the
 kube-apiserver, but this is not a standard.
@@ -215,6 +227,7 @@ metadata:
 spec:
   request: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ1ZqQ0NBVDRDQVFBd0VURVBNQTBHQTFVRUF3d0dZVzVuWld4aE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRgpBQU9DQVE4QU1JSUJDZ0tDQVFFQTByczhJTHRHdTYxakx2dHhWTTJSVlRWMDNHWlJTWWw0dWluVWo4RElaWjBOCnR2MUZtRVFSd3VoaUZsOFEzcWl0Qm0wMUFSMkNJVXBGd2ZzSjZ4MXF3ckJzVkhZbGlBNVhwRVpZM3ExcGswSDQKM3Z3aGJlK1o2MVNrVHF5SVBYUUwrTWM5T1Nsbm0xb0R2N0NtSkZNMUlMRVI3QTVGZnZKOEdFRjJ6dHBoaUlFMwpub1dtdHNZb3JuT2wzc2lHQ2ZGZzR4Zmd4eW8ybmlneFNVekl1bXNnVm9PM2ttT0x1RVF6cXpkakJ3TFJXbWlECklmMXBMWnoyalVnald4UkhCM1gyWnVVV1d1T09PZnpXM01LaE8ybHEvZi9DdS8wYk83c0x0MCt3U2ZMSU91TFcKcW90blZtRmxMMytqTy82WDNDKzBERHk5aUtwbXJjVDBnWGZLemE1dHJRSURBUUFCb0FBd0RRWUpLb1pJaHZjTgpBUUVMQlFBRGdnRUJBR05WdmVIOGR4ZzNvK21VeVRkbmFjVmQ1N24zSkExdnZEU1JWREkyQTZ1eXN3ZFp1L1BVCkkwZXpZWFV0RVNnSk1IRmQycVVNMjNuNVJsSXJ3R0xuUXFISUh5VStWWHhsdnZsRnpNOVpEWllSTmU3QlJvYXgKQVlEdUI5STZXT3FYbkFvczFqRmxNUG5NbFpqdU5kSGxpT1BjTU1oNndLaTZzZFhpVStHYTJ2RUVLY01jSVUyRgpvU2djUWdMYTk0aEpacGk3ZnNMdm1OQUxoT045UHdNMGM1dVJVejV4T0dGMUtCbWRSeEgvbUNOS2JKYjFRQm1HCkkwYitEUEdaTktXTU0xMzhIQXdoV0tkNjVoVHdYOWl4V3ZHMkh4TG1WQzg0L1BHT0tWQW9FNkpsYWFHdTlQVmkKdjlOSjVaZlZrcXdCd0hKbzZXdk9xVlA3SVFjZmg3d0drWm89Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=
   signerName: kubernetes.io/kube-apiserver-client
+  expirationSeconds: 86400  # one day
   usages:
   - client auth
 EOF
@@ -223,6 +236,7 @@ EOF
 Some points to note:
 
 - `usages` has to be '`client auth`'
+- `expirationSeconds` could be made longer (i.e. `864000` for ten days) or shorter (i.e. `3600` for one hour)
 - `request` is the base64 encoded value of the CSR file content.
   You can get the content using this command: ```cat myuser.csr | base64 | tr -d "\n"```
 
@@ -384,6 +398,11 @@ Prior to Kubernetes v1.18, the kube-controller-manager would sign any CSRs that
 were marked as approved.
 {{< /note >}}
 
+{{< note >}}
+The `spec.expirationSeconds` field was added in Kubernetes v1.22.  Earlier versions of Kubernetes do not honor this field.
+Kubernetes API servers prior to v1.22 will silently drop this field when the object is created.
+{{< /note >}}
+
 ### API-based signers {#signer-api}
 
 Users of the REST API can sign CSRs by submitting an UPDATE request to the `status`