strimzi · ppatierno · Jan 27, 2022 · Jan 21, 2022 · Jan 21, 2022 · Jan 21, 2022
diff --git a/documentation/assemblies/security/assembly-security.adoc b/documentation/assemblies/security/assembly-security.adoc
@@ -40,6 +40,8 @@ include::modules/proc-replacing-private-keys.adoc[leveloffset=+2]
 
 include::modules/proc-renewing-your-own-ca-certificates.adoc[leveloffset=+2]
 
+include::modules/proc-replacing-your-own-private-keys.adoc[leveloffset=+2]
+
 include::modules/con-tls-connections.adoc[leveloffset=+1]
 
 include::modules/proc-configuring-internal-clients-to-trust-cluster-ca.adoc[leveloffset=+1]

diff --git a/documentation/modules/security/proc-installing-your-own-ca-certificates.adoc b/documentation/modules/security/proc-installing-your-own-ca-certificates.adoc
@@ -122,6 +122,24 @@ kubectl label secret _CA-KEY-SECRET_ strimzi.io/kind=Kafka strimzi.io/cluster=_C
 * Label `strimzi.io/kind=Kafka` identifies the Kafka custom resource.
 * Label `strimzi.io/cluster=_CLUSTER-NAME_` identifies the Kafka cluster.
 
+. Annotate the secrets
++
+[source,shell,subs="+quotes"]
+----
+kubectl annotate secret _CA-CERTIFICATE-SECRET_ strimzi.io/ca-cert-generation=_CA-CERTIFICATE-GENERATION_
+----
++
+[source,shell,subs="+quotes"]
+----
+kubectl annotate secret _CA-KEY-SECRET_ strimzi.io/ca-key-generation=_CA-KEY-GENERATION_
+----
++
+* Annotation `strimzi.io/ca-cert-generation=_CA-CERTIFICATE-GENERATION_` defines the generation of a new CA certificate.
+* Annotation `strimzi.io/ca-key-generation=_CA-KEY-GENERATION_` defines the generation of a new CA key.
++
+If you are replacing CA certificates automatically generated by the Cluster Operator, use the next higher incremental value from the existing annotation and follow the xref:proc-replacing-your-own-private-keys-{context}[replacing CA keys procedure].
+If there are no CA certificates automatically generated by the Cluster Operator, start from 0 (zero) as the incremental value (`strimzi.io/ca-cert-generation=0`) for your own CA certificate. Set a higher incremental value when you renew the certificates.
+
 . 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
@@ -139,4 +157,5 @@ spec:
 .Additional resources
 
 * To renew CA certificates you have previously installed, see xref:renewing-your-own-ca-certificates-{context}[].
+* To replace the private keys of CA certificates you have previously installed, see xref:proc-replacing-your-own-private-keys-{context}[].
 * xref:proc-installing-certs-per-listener-{context}[].
diff --git a/documentation/modules/security/proc-renewing-your-own-ca-certificates.adoc b/documentation/modules/security/proc-renewing-your-own-ca-certificates.adoc
@@ -5,7 +5,11 @@
 [id='renewing-your-own-ca-certificates-{context}']
 = Renewing your own CA certificates
 
-This procedure describes how to renew CA certificates and keys you installed yourself, instead of using the certificates generated by the Cluster Operator.
+[role="_abstract"]
+This procedure describes how to renew CA certificates that you are using instead of the certificates generated by the Cluster Operator.
+
+*Perform the steps in this procedure when you are not also changing the corresponding CA keys.
+Otherwise, perform the steps to xref:proc-replacing-your-own-private-keys-{context}[replace private keys used by your own CA certificates].*
 
 If you are using your own certificates, the Cluster Operator will not renew them automatically.
 Therefore, it is important that you follow this procedure during the renewal period of the certificate in order to replace CA certificates that will soon expire.
@@ -16,92 +20,83 @@ The procedure describes the renewal of CA certificates in PEM format.
 
 * The Cluster Operator is running.
 * xref:installing-your-own-ca-certificates-{context}[Your own CA certificates and private keys are installed].
-* You have new cluster and clients X.509 certificates and keys in PEM format.
-
-These could be generated using an `openssl` command, such as:
-
-[source,shell,subs="+quotes"]
-openssl req -x509 -new -days _NUMBER-OF-DAYS-VALID_ --nodes -out ca.crt -keyout ca.key
+* You have new cluster or clients X.509 certificates in PEM format.
 
 .Procedure
 
-. Check the details of the current CA certificates in the `Secret`:
-+
-[source,shell,subs="+quotes"]
-kubectl 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.
-
-. Create a directory to contain the existing CA certificates in the secret.
+. Update the `Secret` for the CA certificate.
 +
-[source,shell,subs="+quotes"]
-----
-mkdir new-ca-cert-secret
-cd new-ca-cert-secret
-----
-
-. Fetch the secret for each CA certificate you wish to renew:
+Edit the existing secret to add the new CA certificate and update the certificate generation annotation value.
 +
 [source,shell,subs="+quotes"]
-kubectl get secret _CA-CERTIFICATE-SECRET_ -o 'jsonpath={.data._CA-CERTIFICATE_}' | base64 -d > _CA-CERTIFICATE_
+kubectl edit secret _<ca_certificate_secret_name>_
 +
-Replace _CA-CERTIFICATE_ with the name of each CA certificate.
-
-. 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_.
+_<ca_certificate_secret_name>_ 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.
 +
-For example `ca-2018-09-27T17-32-00Z.crt`.
+The following example shows a secret for a cluster CA certificate that's associated with a Kafka cluster named `my-cluster`.
 +
-[source,shell,subs="+quotes"]
-mv ca.crt ca-$(date -u -d"$(openssl x509 -enddate -noout -in ca.crt | sed 's/.*=//')" +'%Y-%m-%dT%H-%M-%SZ').crt
+.Example secret configuration for a cluster CA certificate
+[source,yaml,subs=attributes+]
+----
+apiVersion: v1
+kind: Secret
+data:
+  ca.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0F... <1>
+metadata:
+  annotations:
+    strimzi.io/ca-cert-generation: "0" <2>
+  labels:
+    strimzi.io/cluster: my-cluster
+    strimzi.io/kind: Kafka
+  name: my-cluster-cluster-ca-cert
+  #...
+type: Opaque
+----
+<1> Current base64-encoded CA certificate
+<2> Current CA certificate generation annotation value
 
-. Copy your new CA certificate into the directory, naming it `ca.crt`:
+. Encode your new CA certificate into base64.
 +
 [source,shell,subs="+quotes"]
-cp _PATH-TO-NEW-CERTIFICATE_ ca.crt
+cat _<path_to_new_certificate>_ | base64
 
-. Put your CA certificate in the corresponding `Secret`.
+. Update the CA certificate.
 +
-.. Delete the existing secret:
+Copy the base64-encoded CA certificate from the previous step as the value for the `ca.crt` property under `data`.
 +
-[source,shell,subs="+quotes"]
-kubectl delete secret _CA-CERTIFICATE-SECRET_
-+
-_CA-CERTIFICATE-SECRET_ is the name of the `Secret`, as returned in the first step.
+. Increase the value of the CA certificate generation annotation.
 +
-Ignore any "Not Exists" errors.
-
-.. Recreate the secret:
+Update the `strimzi.io/ca-cert-generation` annotation with a higher incremental value.
+For example, change `strimzi.io/ca-cert-generation=0` to `strimzi.io/ca-cert-generation=1`.
+If the `Secret` is missing the annotation, the value is treated as `0`, so add the annotation with a value of `1`.
 +
-[source,shell,subs="+quotes"]
-kubectl create secret generic _CA-CERTIFICATE-SECRET_ --from-file=.
+When Strimzi generates certificates, the certificate generation annotation is automatically incremented by the Cluster Operator.
+For manual renewal of your own CA certificates, set the annotations with a higher incremental value.
+The annotation needs a higher value than the one from the current secret so that the Cluster Operator can roll the pods and update the certificates.
+The `strimzi.io/ca-cert-generation` has to be incremented on each CA certificate renewal.
 
-. Delete the directory you created:
+. Save the secret with the new CA certificate and certificate generation annotation value.
 +
-[source,shell,subs="+quotes"]
+.Example secret configuration updated with a new CA certificate
+[source,yaml,subs=attributes+]
 ----
-cd ..
-rm -r new-ca-cert-secret
+apiVersion: v1
+kind: Secret
+data:
+  ca.crt: GCa6LS3RTHeKFiFDGBOUDYFAZ0F... <1>
+metadata:
+  annotations:
+    strimzi.io/ca-cert-generation: "1" <2>
+  labels:
+    strimzi.io/cluster: my-cluster
+    strimzi.io/kind: Kafka
+  name: my-cluster-cluster-ca-cert
+  #...
+type: Opaque
 ----
+<1> New base64-encoded CA certificate
+<2> New CA certificate generation annotation value
 
-. Put your CA key in the corresponding `Secret`.
-
-.. Delete the existing secret:
-+
-[source,shell,subs="+quotes"]
-kubectl 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.
-
-.. Recreate the secret with the new CA key:
-+
-[source,shell,subs="+quotes"]
-kubectl create secret generic _CA-KEY-SECRET_ --from-file=ca.key=_CA-KEY-SECRET-FILENAME_
+On the next reconciliation, the Cluster Operator performs a rolling update of ZooKeeper, Kafka, and other components to trust the new CA certificate.
 
-. Label the secrets with the labels `strimzi.io/kind=Kafka` and `strimzi.io/cluster=_KAFKA-CLUSTER-NAME_`:
-+
-[source,shell,subs="+quotes"]
-----
-kubectl label secret _CA-CERTIFICATE-SECRET_ strimzi.io/kind=Kafka strimzi.io/cluster=_KAFKA-CLUSTER-NAME_
-kubectl label secret _CA-KEY-SECRET_ strimzi.io/kind=Kafka strimzi.io/cluster=_KAFKA-CLUSTER-NAME_
-----
+If maintenance time windows are configured, the Cluster Operator will roll the pods at the first reconciliation within the next maintenance time window.