document automatic certificate renewal

Author: Yuvaraj Kakaraparthi

docs/book/src/tasks/certs/auto-rotate-certificates-in-kcp.md

@@ -0,0 +1,59 @@
+## Automatically rotating certificates using Kubeadm Control Plane provider
+
+When using Kubeadm Control Plane provider (KCP) it is possible to configure automatic certificate rotations. KCP does this by triggering a rollout when the certificates on the machines are about to expire.
+
+### Configuring Machine Rollout
+
+To configure a rollout on the KCP machines you need to set `.rolloutBefore.certificatesExpiryDays` (minimum of 7 days).  
+
+Example: 
+```yaml
+apiVersion: controlplane.cluster.x-k8s.io/v1beta1
+kind: KubeadmControlPlane
+metadata:
+  name: example-control-plane
+spec:
+  rolloutBefore:
+    certificatesExpiryDays: 21 # trigger a rollout if certificates expire within 21 days
+  kubeadmConfigSpec:
+    clusterConfiguration:
+      ...
+    initConfiguration:
+      ...
+    joinConfiguration:
+      ...
+  machineTemplate:
+    infrastructureRef:
+      ...
+  replicas: 1
+  version: v1.23.3
+``` 
+
+TODO: Add a few lines on recommendations to set the `certificatesExpiryDays` to a big value so that all the machines will have time to completely rollout.
+
+### Calculating Certificate Expiry
+
+KCP uses the value in the corresponding Control Plane machine's `Machine.Status.CertificatesExpiryDate` to check if a machine's certificates are going to expire and if it needs to be rolled out.  
+
+`Machine.Status.CertificatesExpiryDate` get its value from one of the following 2 places:
+
+* `machine.cluster.x-k8s.io/certificates-expiry` annotation value on the Machine object
+* `machine.cluster.x-k8s.io/certificates-expiry` annotation value on the Bootstrap Config object of the corresponding object
+
+The annotation value is a [RFC3339] format timestamp. The annotation value on the machine object, if provided, will take precedence.  
+
+#### Certificate Expiry from Kubeadm Bootstrap Config
+
+When KubeadmConfig creates the bootstrap data secret for the first time it captures 1 year from the reconciliation time and store it as the `machine.cluster.x-k8s.io/certificates-expiry` annotation value on the KubeadmConfig object. We chose 1 year from the reconciliation time because kubeadm is hard-coded to generate machine certificates that are valid for one year.
+
+<aside class="note warning">
+
+<h1> Approximate Certificate Expiry Time </h1>
+
+The time captured in the KubeadmConfig annotation is an approximate time at which the machine certificates will expire. Since the Kubeadm data secret is generated before is is used by kubeadm to generate the certificates the time captured in the annotation will be a little early than the actual certificate expiry time.
+Since the difference in this time will be very small compared to the lifetime of the certificate it should not affect the certificate renewal rollout in any significant way.
+
+</aside>
+
+<!-- links -->
+[RFC3339]: https://www.ietf.org/rfc/rfc3339.txt