Rotating CA certificates in your cluster

Revoke existing certificate authority (CA) certificates in your cluster and issue new CA certificates.

By default, certificate authority (CA) certificates are administered to secure access to various components of your cluster, such as the master API server. As you use your cluster, you might want to revoke the certificates issued by the existing CA. For example, the administrators of your team might use a certificate signing request (CSR) to manually generate certificates that are signed by the cluster's CA for worker nodes in the cluster. If an administrator leaves your organization, you can ensure that they no longer have admin access to your cluster by creating a new CA and certificates for your cluster, and removing the old CA and certificates.

Create a CA for your cluster. Certificates that are signed by this new CA are issued for the cluster master components, and the API server is refreshed.
```
ibmcloud ks cluster ca create -c CLUSTER
```
Ensure that your cluster's master health is normal, the API server refresh is complete, and any master updates are complete. It might take several minutes for the master API server to refresh.
```
ibmcloud ks cluster get --cluster CLUSTER
```

Check the status of the CA creation. In the output, note the timestamp in the Action Completed field.

ibmcloud ks cluster ca status -c CLUSTER

Example output

Status:             CA certificate creation complete. Ensure that your worker nodes are reloaded before you start a CA certificate rotation.
Action Started:     2024-08-30T16:17:56+0000
Action Completed:   2024-08-30T16:21:13+0000

Download the updated Kubernetes configuration data and certificates in your cluster's kubeconfig file.
```
ibmcloud ks cluster config -c CLUSTER --admin --network
```
Verify that the timestamps in your new certificates are later than the timestamp that you found in step 3. To check the date on your certificates, you can use a tool such as KeyCDN.
Update any tooling or webhooks that rely on the previous certificates. For example, you might need to update one or more of the following.
- If you use the certificate from your cluster's kubeconfig file in your own service, such as Jenkins.
- If you use calicoctl to manage Calico network policies, update your services and automation to use the new certificates.
- If you forward audit logs to IBM Cloud Logs, update the certificates for your master audit webhook.
- If you forward audit logs over the private network, update the certificates for your master audit webhook.
Reload your classic worker nodes or replace your VPC worker nodes to pick up the certificates that are signed by the new CA.
Rotate the old certificates with the new certificates. The old CA certificates in your cluster are removed.
```
ibmcloud ks cluster ca rotate -c CLUSTER
```

Check the status of the CA certificate rotation.

ibmcloud ks cluster ca status -c CLUSTER

Example output

Status:             CA certificate rotation complete.
Action Started:     2024-08-30T16:37:56+0000
Action Completed:   2024-08-30T16:41:13+0000

Because some clients might not allow expired CA certificates in the certificate bundle, download the updated Kubernetes configuration and certificates in your cluster's kubeconfig file.
```
ibmcloud ks cluster config -c CLUSTER --admin --network
```
Update any tooling that relies on the previous certificates. If you use the certificate from your cluster's kubeconfig file in your own service such as Travis or Jenkins, or if you use calicoctl to manage Calico network policies, update your services and automation to use the new certificates.

Certificate rotation states

Review the following table for information on each state of the certificate rotation process.

Certificate rotation states
State	Description
CA certificate creation in progress.	New certificates are being created for the rotation process and being put into the certificate chain.
CA certificate creation complete. Ensure that your worker nodes are reloaded before you start a CA certificate rotation.	New certificates have been created and put into the certificate chain.
CA certificate rotation in progress.	The certificate rotation is in progress. The old certificates are being removed from the certificate chain.
CA certificate rotation complete.	The old certificates have been removed from the certificate chain.

FAQ about certificate rotation

Does IBM perform automatic CA rotation for clusters?: No, IBM does not perform automatic CA rotations. Users are responsible for executing the CA rotation process.
When should CA certificates be rotated?: When existing access to the cluster needs to be revoked. Specifically, if a cluster administrator should no longer have access to the cluster as they may have generated certificates signed by the current CA to access the cluster.
Does IBM automatically extend the expiration of CA certificates?: Yes, new CA certificates are generated using the existing private key. This enables the certificates to have a new expiry date while still allowing the existing intermediate and end-entity certificates to be successfully validated.
My cluster's CA status has a state of CA certificate creation complete, what actions are expected in this case?: The expectation is that once the CA rotation processes has been started, it is completed. This ensures that intermediate and end-entity certificates generated with the prior CA are invalidated.
My cluster's CA status shows Action Started and Action Completed timestamps from several years ago. What actions are expected in this case?: None. This indicates that a CA rotation was started and completed as the timestamps indiciate.
Does performing CA rotation result in a shorter validity period than the current certificate?: Yes, it is possible that performing a rotation can result in the validity period of the new certificate being shorter than the previous certificate. This is due to a shortening of the default certificate expiry length.