Chapter 11. Managing TLS certificates

Procedure

1. Put your CA certificate in the corresponding Secret.

   1. Delete the existing secret:

      oc delete secret CA-CERTIFICATE-SECRET

      CA-CERTIFICATE-SECRET is the name of the Secret, which is CLUSTER-NAME-cluster-ca-cert for the cluster CA certificate and CLUSTER-NAME-clients-ca-cert for the clients CA certificate.

      Ignore any "Not Exists" errors.

   2. Create and label the new secret

      oc create secret generic CA-CERTIFICATE-SECRET --from-file=ca.crt=CA-CERTIFICATE-FILENAME

2. Put your CA key in the corresponding Secret.

   1. Delete the existing secret:

      oc delete secret CA-KEY-SECRET

      CA-KEY-SECRET is the name of CA key, which is CLUSTER-NAME-cluster-ca for the cluster CA key and CLUSTER-NAME-clients-ca for the clients CA key.

   2. Create the new secret:

      oc create secret generic CA-KEY-SECRET --from-file=ca.key=CA-KEY-SECRET-FILENAME

3. Label the secrets with the labels strimzi.io/kind=Kafka and strimzi.io/cluster=CLUSTER-NAME:

   oc label secret CA-CERTIFICATE-SECRET strimzi.io/kind=Kafka strimzi.io/cluster=CLUSTER-NAME
   oc label secret CA-KEY-SECRET strimzi.io/kind=Kafka strimzi.io/cluster=CLUSTER-NAME

4. Create the Kafka resource for your cluster, configuring either the Kafka.spec.clusterCa or the Kafka.spec.clientsCa object to not use generated CAs:

   Example fragment Kafka resource configuring the cluster CA to use certificates you supply for yourself

   kind: Kafka
   version: kafka.strimzi.io/v1beta2
   spec:
     # ...
     clusterCa:
       generateCertificateAuthority: false

1. 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.
2. 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.
3. Restart ZooKeeper nodes so that they will trust the new CA certificate and use the new client certificates.
4. Restart Kafka brokers so that they will trust the new CA certificate and use the new client certificates.
5. Restart the Topic and User Operators so that they will trust the new CA certificate and use the new client certificates.

Procedure

1. Apply the strimzi.io/force-renew annotation to the Secret that contains the CA certificate that you want to renew.

   Table 11.8. Annotation for the Secret that forces renewal of certificates

   Certificate	Secret	Annotate command
   Cluster CA	KAFKA-CLUSTER-NAME-cluster-ca-cert	oc annotate secret KAFKA-CLUSTER-NAME-cluster-ca-cert strimzi.io/force-renew=true
   Clients CA	KAFKA-CLUSTER-NAME-clients-ca-cert	oc annotate secret KAFKA-CLUSTER-NAME-clients-ca-cert strimzi.io/force-renew=true

   At the next reconciliation the Cluster Operator will generate a new CA certificate for the Secret that you annotated. If maintenance time windows are configured, the Cluster Operator will generate the new CA certificate at the first reconciliation within the next maintenance time window.

   Client applications must reload the cluster and clients CA certificates that were renewed by the Cluster Operator.

2. Check the period the CA certificate is valid:

   For example, using an openssl command:

   oc get secret CA-CERTIFICATE-SECRET -o 'jsonpath={.data.CA-CERTIFICATE}' | base64 -d | openssl x509 -subject -issuer -startdate -enddate -noout

   CA-CERTIFICATE-SECRET is the name of the Secret, which is KAFKA-CLUSTER-NAME-cluster-ca-cert for the cluster CA certificate and KAFKA-CLUSTER-NAME-clients-ca-cert for the clients CA certificate.

   CA-CERTIFICATE is the name of the CA certificate, such as jsonpath={.data.ca\.crt}.

   The command returns a notBefore and notAfter date, which is the validity period for the CA certificate.

   For example, for a cluster CA certificate:

   subject=O = io.strimzi, CN = cluster-ca v0
   issuer=O = io.strimzi, CN = cluster-ca v0
   notBefore=Jun 30 09:43:54 2020 GMT
   notAfter=Jun 30 09:43:54 2021 GMT

3. Delete old certificates from the Secret.

   When components are using the new certificates, older certificates might still be active. Delete the old certificates to remove any potential security risk.

Procedure

1. Check the details of the current CA certificates in the Secret:

   oc describe secret CA-CERTIFICATE-SECRET

   CA-CERTIFICATE-SECRET is the name of the Secret, which is KAFKA-CLUSTER-NAME-cluster-ca-cert for the cluster CA certificate and KAFKA-CLUSTER-NAME-clients-ca-cert for the clients CA certificate.

2. Create a directory to contain the existing CA certificates in the secret.

   mkdir new-ca-cert-secret
   cd new-ca-cert-secret

3. Fetch the secret for each CA certificate you wish to renew:

   oc get secret CA-CERTIFICATE-SECRET -o 'jsonpath={.data.CA-CERTIFICATE}' | base64 -d > CA-CERTIFICATE

   Replace CA-CERTIFICATE with the name of each CA certificate.

4. Rename the old ca.crt file as ca-DATE.crt, where DATE is the certificate expiry date in the format YEAR-MONTH-DAYTHOUR-MINUTE-SECONDZ.

   For example ca-2018-09-27T17-32-00Z.crt.

   mv ca.crt ca-$(date -u -d$(openssl x509 -enddate -noout -in ca.crt | sed 's/.*=//') +'%Y-%m-%dT%H-%M-%SZ').crt

5. Copy your new CA certificate into the directory, naming it ca.crt:

   cp PATH-TO-NEW-CERTIFICATE ca.crt

6. Put your CA certificate in the corresponding Secret.

   1. Delete the existing secret:

      oc delete secret CA-CERTIFICATE-SECRET

      CA-CERTIFICATE-SECRET is the name of the Secret, as returned in the first step.

      Ignore any "Not Exists" errors.

   2. Recreate the secret:

      oc create secret generic CA-CERTIFICATE-SECRET --from-file=.

7. Delete the directory you created:

   cd ..
   rm -r new-ca-cert-secret

8. Put your CA key in the corresponding Secret.

   1. Delete the existing secret:

      oc delete secret CA-KEY-SECRET

      CA-KEY-SECRET is the name of CA key, which is KAFKA-CLUSTER-NAME-cluster-ca for the cluster CA key and KAFKA-CLUSTER-NAME-clients-ca for the clients CA key.

   2. Recreate the secret with the new CA key:

      oc create secret generic CA-KEY-SECRET --from-file=ca.key=CA-KEY-SECRET-FILENAME

9. Label the secrets with the labels strimzi.io/kind=Kafka and strimzi.io/cluster=KAFKA-CLUSTER-NAME:

   oc label secret CA-CERTIFICATE-SECRET strimzi.io/kind=Kafka strimzi.io/cluster=KAFKA-CLUSTER-NAME
   oc label secret CA-KEY-SECRET strimzi.io/kind=Kafka strimzi.io/cluster=KAFKA-CLUSTER-NAME

Procedure

1. Create a Secret containing your private key and server certificate:

   oc create secret generic my-secret --from-file=my-listener-key.key --from-file=my-listener-certificate.crt

2. Edit the Kafka resource for your cluster. Configure the listener to use your Secret, certificate file, and private key file in the configuration.brokerCertChainAndKey property.

   Example configuration for a loadbalancer external listener with TLS encryption enabled

   # ...
   listeners:
     - name: plain
       port: 9092
       type: internal
       tls: false
     - name: external
       port: 9094
       type: loadbalancer
       tls: true
       authentication:
         type: tls
       configuration:
         brokerCertChainAndKey:
           secretName: my-secret
           certificate: my-listener-certificate.crt
           key: my-listener-key.key
   # ...

   Example configuration for a TLS listener

   # ...
   listeners:
     - name: plain
       port: 9092
       type: internal
       tls: false
     - name: tls
       port: 9093
       type: internal
       tls: true
       authentication:
         type: tls
       configuration:
         brokerCertChainAndKey:
           secretName: my-secret
           certificate: my-listener-certificate.crt
           key: my-listener-key.key
   # ...

3. Apply the new configuration to create or update the resource:

   oc apply -f kafka.yaml

   The Cluster Operator starts a rolling update of the Kafka cluster, which updates the configuration of the listeners.

   Note

   A rolling update is also started if you update a Kafka listener certificate in a Secret that is already used by a TLS or external listener.