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

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

[role="_abstract"]
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 CA certificates automatically created by the Cluster Operator, configure the validity period for certificates in the `kafka` resource using the following properties:

* `Kafka.spec.clusterCa.validityDays` for Cluster CA certificates
* `Kafka.spec.clientsCa.validityDays` for Clients CA certificates

The default validity period for both certificates is 365 days.
Manually-installed CA certificates should have their own validity periods defined.

When a CA certificate expires, components and clients that still trust that certificate do not accept connections from peers whose certificates 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 initiates certificate renewal before the old CA certificates expire.

Configure the renewal period of the certificates created by the Cluster Operator in the `kafka` resource using the following properties:

* `Kafka.spec.clusterCa.renewalDays` for Cluster CA certificates
* `Kafka.spec.clientsCa.renewalDays` for Clients CA certificates

The default renewal period for both certificates is 30 days.

The renewal period is measured backwards, from the expiry date of the current certificate.

.Validity period against renewal period
[source]
----
Not Before                                     Not After
    |                                              |
    |<--------------- validityDays --------------->|
                              <--- renewalDays --->|
----

To schedule the renewal period at a convenient time, use xref:con-maintenance-time-window-definition-{context}[maintenance time windows].

To make a change to the validity and renewal periods after creating the Kafka cluster, configure and apply the `Kafka` custom resource,
and xref:proc-renewing-ca-certs-manually-{context}[manually renew the CA certificates].
If you do not manually renew the certificates, the new periods will be used the next time the certificate is renewed automatically.

.Example Kafka configuration for certificate validity and renewal periods
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
# ...
spec:
# ...
  clusterCa:
    renewalDays: 30
    validityDays: 365
    generateCertificateAuthority: true
  clientsCa:
    renewalDays: 30
    validityDays: 365
    generateCertificateAuthority: true
# ...
----

The behavior of the Cluster Operator during the renewal period depends on the settings for the `generateCertificateAuthority` certificate generation properties for the cluster CA and clients CA.

`true`:: If the properties are set to `true`, a CA certificate is generated automatically by the Cluster Operator, and renewed automatically within the renewal period.
`false`:: If the properties are set to `false`, a CA certificate is not generated by the Cluster Operator. Use this option if you are xref:installing-your-own-ca-certificates-{context}[installing your own certificates].

== Renewing automatically generated CA Certificates

When it's time to renew CA certificates, the Cluster Operator follows these steps:

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

. Generates new client certificates (for Kafka nodes, Entity Operator, Kafka Exporter, and Cruise Control).
+
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.

. Restarts Kafka nodes to trust the new CA certificate and use the new client certificates.

. Restarts the Topic Operator and User Operator to trust the new CA certificate and use the new client certificates.

. Restarts Cruise Control to trust the new CA certificate and use the new client certificates.

. Restarts the Kafka Exporter to trust the new CA certificate and use the new client certificates.

+
User certificates are signed by the clients CA. 
The User Operator handles renewing user certificates when the client's CA is renewed. 

== Renewing client certificates

The Cluster Operator is not aware of the client applications using the Kafka cluster.
You must ensure clients continue to work after certificate renewal.
The renewal process depends on how the clients are configured.

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

* Truststore credentials from the `<cluster_name>-cluster-ca-cert` secret to verify the identity of the Kafka cluster.
* Keystore credentials from the `<user_name>` secret to connect to verify the user when connecting to the Kafka 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 an example of adding certificates to client configuration, see xref:proc-configuring-secure-kafka-user-str[].

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.

NOTE: 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].
