sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/tasks/certs/auto-rotate-certificates-in-kcp.md (about)

     1  ## Automatically rotating certificates using Kubeadm Control Plane provider
     2  
     3  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 control plane machines are about to expire.
     4  
     5  If configured, the certificate rollout feature is available for all new and existing control plane machines.
     6  
     7  ### Configuring Machine Rollout
     8  
     9  To configure a rollout on the KCP machines you need to set `.rolloutBefore.certificatesExpiryDays` (minimum of 7 days).  
    10  
    11  Example: 
    12  ```yaml
    13  apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    14  kind: KubeadmControlPlane
    15  metadata:
    16    name: example-control-plane
    17  spec:
    18    rolloutBefore:
    19      certificatesExpiryDays: 21 # trigger a rollout if certificates expire within 21 days
    20    kubeadmConfigSpec:
    21      clusterConfiguration:
    22        ...
    23      initConfiguration:
    24        ...
    25      joinConfiguration:
    26        ...
    27    machineTemplate:
    28      infrastructureRef:
    29        ...
    30    replicas: 1
    31    version: v1.23.3
    32  ``` 
    33  
    34  It is strongly recommended to set the `certificatesExpiryDays` to a large enough value so that all the machines will have time to complete rollout well in advance before the certificates expire.
    35  
    36  ### Triggering Machine Rollout for Certificate Expiry
    37  
    38  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.  
    39  
    40  `Machine.Status.CertificatesExpiryDate` gets its value from one of the following 2 places:
    41  
    42  * `machine.cluster.x-k8s.io/certificates-expiry` annotation value on the Machine object. This annotation is not applied by default and it can be set by users to manually override the certificate expiry information.
    43  * `machine.cluster.x-k8s.io/certificates-expiry` annotation value on the Bootstrap Config object referenced by the machine. This value is automatically set for machines bootstrapped with CABPK that are owned by the KCP resource.
    44  
    45  The annotation value is a [RFC3339] format timestamp. The annotation value on the machine object, if provided, will take precedence.  
    46  
    47  <aside class="note warning">
    48  
    49  <h1>Certificate Expiry Time</h1>
    50  
    51  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.
    52  
    53  </aside>
    54  
    55  <aside class="note warning">
    56  
    57  <h1>Manual certificate rotation</h1>
    58  
    59  If certificates on control plane nodes are rotated manually (e.g. via `kubeadm certs renew`), please be aware that the rotation is only
    60  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.
    61  To allow KCP to re-discover the expiry date please remove the `machine.cluster.x-k8s.io/certificates-expiry` annotation from the
    62  KubeadmConfig corresponding to the current machine.
    63  
    64  </aside>
    65  
    66  <!-- links -->
    67  [RFC3339]: https://www.ietf.org/rfc/rfc3339.txt