Fix documentation about install and renew your own CA certificates

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.
+If you are generating the CA certificates for the first time, you can start from 0 (zero) as the incremental value (`strimzi.io/ca-cert-generation=0`). 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

documentation/modules/security/proc-renewing-your-own-ca-certificates.adoc

@@ -54,6 +54,13 @@ For example `ca-2018-09-27T17-32-00Z.crt`.
 +
 [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
++
+If you are using a different key to generate a new certificate, retain the current CA certificate by storing it in the Secret as described above.
+The CN (Common Name) of the new CA certificate must also be different from the current one.
+For example, when the Cluster Operator renews certificates automatically it adds a _v<version_number>_ suffix to identify a version.
+Do the same with your own CA certificate by adding a different suffix on each renewal.
+If you are using the same key for generate a new CA certificate, don't retain the old one in the Secret.
+Otherwise, the underlying trusting system will fail because it finds two valid CA certificates signed with the same key.
 
 . Copy your new CA certificate into the directory, naming it `ca.crt`:
 +
@@ -105,3 +112,17 @@ kubectl create secret generic _CA-KEY-SECRET_ --from-file=ca.key=_CA-KEY-SECRET-
 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_
 ----
+
+. Annotate the secrets with the generation annotations:
++
+[source,shell,subs="+quotes"]
+----
+kubectl annotate secret _CA-CERTIFICATE-SECRET_ strimzi.io/ca-cert-generation=_CA-CERTIFICATE-GENERATION_
+kubectl annotate secret _CA-KEY-SECRET_ strimzi.io/ca-key-generation=_CA-KEY-GENERATION_
+----
++
+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. For example, change `strimzi.io/ca-cert-generation=1` to `strimzi.io/ca-cert-generation=2`.
+The annotations need a value higher than the ones from the current secret so 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.
+The `strimzi.io/ca-key-generation` has to be incremented only if you are using a different key for generating the new CA certificate.