address review comments

Author: Yuvaraj Kakaraparthi

docs/book/src/reference/labels_and_annotations.md

@@ -34,6 +34,7 @@
 |  cluster.x-k8s.io/skip-remediation  | It is used to mark the machines that should not be considered for remediation by MachineHealthCheck reconciler.   |
 |  cluster.x-k8s.io/managed-by  | It can be applied to InfraCluster resources to signify that some external system is managing the cluster infrastructure. Provider InfraCluster controllers will ignore resources with this annotation. An external controller must fulfill the contract of the InfraCluster resource. External infrastructure providers should ensure that the annotation, once set, cannot be removed.  |
 |  topology.cluster.x-k8s.io/dry-run  | It is an annotation that gets set on objects by the topology controller only during a server side dry run apply operation. It is used for validating update webhooks for objects which get updated by template rotation (e.g. InfrastructureMachineTemplate). When the annotation is set and the admission request is a dry run, the webhook should deny validation due to immutability. By that the request will succeed (without any changes to the actual object because it is a dry run) and the topology controller will receive the resulting object. |
+|  machine.cluster.x-k8s.io/certificates-expiry    | It captures the expiry date of the machine certificates in RFC3339 format. It is used to trigger rollout of control plane machines before certificates expire. It can be set on BootstrapConfig and Machine objects. The value set on Machine object takes precedence. The annotation is only used by control plane machines. |
 |  machine.cluster.x-k8s.io/exclude-node-draining  | It explicitly skips node draining if set.  |
 |  machine.cluster.x-k8s.io/exclude-wait-for-node-volume-detach  | It explicitly skips the waiting for node volume detaching if set. |
 |  pre-drain.delete.hook.machine.cluster.x-k8s.io  | It specifies the prefix we search each annotation for during the pre-drain.delete lifecycle hook to pause reconciliation of deletion. These hooks will prevent removal of draining the associated node until all are removed. |

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

@@ -46,19 +46,20 @@ The annotation value is a [RFC3339] format timestamp. The annotation value on th
 
 <aside class="note warning">
 
-<h1> Approximate Certificate Expiry Time </h1>
+<h1>Certificate Expiry Time</h1>
 
-The time captured in the Bootstrap Config annotation is an approximate time at which the machine certificates will expire (1 year from creation). The time captured in the annotation will be a little earlier than the actual certificate expiry time.
-
-It is assumed that all the certificates has the same expiration time. If not, it is assumed that the kube-apiserver certificate expires before other certificates.
+It is assumed that all certificates on a control plane node have roughly the same expiration time (+/- a few minutes). KCP decides when a rotation is needed based on the expiry of the kube-apiserver certificate.
 
 </aside>
 
 <aside class="note warning">
 
-<h1> Deleting the machine.cluster.x-k8s.io/certificates-expiry annotation </h1>
+<h1>Manual certificate rotation</h1>
 
-If the annotation is delete from the object, the certificate expiry information will be cleared form the Machine's status leading to certificate renewal being effectively disabled. It is recommended to be highly cautions when deleting this annotation from the object.
+If certificates on control plane nodes are rotated manually (e.g. via `kubeadm certs renew`), please be aware that the rotation is only
+complete after all components including the kube-apiserver are using the new certificates. Thus, kube-apiserver, kube-controller-manager, kube-scheduler and etcd have to be restarted after certificate renewal.
+To allow KCP to re-discover the expiry date please remove the `machine.cluster.x-k8s.io/certificates-expiry` annotation from the
+KubeadmConfig corresponding to the current machine.
 
 </aside>