// Module included in the following assemblies:
//
// assembly-security.adoc

[id='con-certificate-renewal-{context}']
= Certificate renewal

The cluster CA and clients CA certificates are only valid for a limited time period, known as the validity period.
This is usually defined as a number of days since the certificate was generated.
For auto-generated CA certificates, you can configure the validity period in `Kafka.spec.clusterCa.validityDays` and `Kafka.spec.clientsCa.validityDays`.
The default validity period for both certificates is 365 days.
Manually-installed CA certificates should have their own validity period defined.

When a CA certificate expires, components and clients which still trust that certificate will not accept TLS connections from peers whose certificate were signed by the CA private key.
The components and clients need to trust the _new_ CA certificate instead.

To allow the renewal of CA certificates without a loss of service, the Cluster Operator will initiate certificate renewal before the old CA certificates expire.
You can configure the renewal period in `Kafka.spec.clusterCa.renewalDays` and `Kafka.spec.clientsCa.renewalDays` (both default to 30 days).
The renewal period is measured backwards, from the expiry date of the current certificate.

[source]
----
Not Before                                     Not After
    |                                              |
    |<--------------- validityDays --------------->|
                              <--- renewalDays --->|
----

The behavior of the Cluster Operator during the renewal period depends on whether the relevant setting is enabled, in either `Kafka.spec.clusterCa.generateCertificateAuthority` or `Kafka.spec.clientsCa.generateCertificateAuthority`.

== Renewal process with generated CAs

The Cluster Operator performs the following process to renew CA certificates:

. Generate a new CA certificate, but retain the existing key. The new certificate replaces the old one with the name `ca.crt` within the corresponding `Secret`.

. Generate new client certificates (for ZooKeeper nodes, Kafka brokers, and the Entity Operator).
This is not strictly necessary because the signing key has not changed, but it keeps the validity period of the client certificate in sync with the CA certificate.

. Restart ZooKeeper nodes so that they will trust the new CA certificate and use the new client certificates.

. Restart Kafka brokers so that they will trust the new CA certificate and use the new client certificates.

. Restart the Topic and User Operators so that they will trust the new CA certificate and use the new client certificates.

== Client applications

The Cluster Operator is not aware of the client applications using the Kafka cluster.

When connecting to the cluster, and to ensure they operate correctly, client applications must:

* Trust the cluster CA certificate published in the _<cluster>_-cluster-ca-cert Secret.
* Use the credentials published in their _<user-name>_ Secret to connect to the cluster.
+
The User Secret provides credentials in PEM and PKCS #12 format, or it can provide a password when using SCRAM-SHA authentication.
The User Operator creates the user credentials when a user is created.

For workloads running inside the same Kubernetes cluster and namespace, Secrets can be mounted as a volume so the client Pods construct their keystores and truststores from the current state of the Secrets.
For more details on this procedure, see xref:configuring-internal-clients-to-trust-cluster-ca-{context}[Configuring internal clients to trust the cluster CA].

=== Client certificate renewal

You must ensure clients continue to work after certificate renewal.
The renewal process depends on how the clients are configured.

If you are provisioning client certificates and keys manually, you must generate new client certificates and ensure the new certificates are used by clients within the renewal period.
Failure to do this by the end of the renewal period could result in client applications being unable to connect to the cluster.
