Merge pull request #77406 from tmalove/etcd-osdocs-10055-tlove

[OSDOCS#10055]: Document manual rotation of etcd signer certificates

modules/etcd-cert-alerts-metrics-signer.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * security/certificate_types_descriptions/etcd-certificates.adoc
+
+:_mod-docs-content-type: CONCEPT    
+[id="etcd-cert-alerts-metrics-signer_{context}"]
+= etcd certificate rotation alerts and metrics signer certificates
+
+Two alert types inform users about pending `etcd` certificate expiration:
+[horizontal]
+`etcdSignerCAExpirationWarning`:: Occurs 730 days until the signer expires.
+`etcdSignerCAExpirationCritical`:: Occurs 365 days until the signer expires.
+
+You can rotate the certificate for the following reasons:
+
+* You receive an expiration alert.
+* The private key is leaked.
+
+[IMPORTANT]
+====
+When a private key is leaked, you must rotate all of the certificates.
+====
+
+There is an `etcd` signer for the {product-title} metrics system. Substitute the following metrics parameters in _Rotating the etcd certificate_.
+
+* `etcd-metric-signer` instead of `etcd-signer`
+* `etcd-metrics-ca-bundle` instead of `etcd-ca-bundle`

modules/rotating-certificate-authority.adoc

@@ -0,0 +1,47 @@
+// Module included in the following assemblies:
+//
+// security/certificate_types_descriptions/etcd-certificates.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="rotating-certificate-authority_{context}"]
+= Rotating the etcd certificate
+
+Rotate the `etcd` certificate before it expires.
+
+.Procedure
+
+. Verify the remaining lifetime of the new signer certificate by running the following command:
++
+[source,terminal]
+----
+$ oc get secret -n openshift-etcd etcd-signer -ojsonpath='{.metadata.annotations.auth\.openshift\.io/certificate-not-after}'
+----
+
+. If the remaining lifetime is close to the current date, re-create the signer by deleting the signer and wait for the static pod roll out.
+* Delete the signer by running the following command:
++
+[source,terminal]
+----
+$ oc delete secret -n openshift-etcd etcd-signer
+----
+
+* Wait for the static pod roll out by running the following command:
++
+[source,terminal]
+----
+$ oc wait --for=condition=Progressing=False --timeout=15m clusteroperator/etcd
+----
+
+. After `etcd` restarts, switch the original CA in the `openshift-config` namespace with the new, rotated one in `openshift-etcd` by running the following command:
++
+[source,terminal]
+----
+$ oc get secret etcd-signer -n openshift-etcd -ojson | jq 'del(.metadata["namespace","creationTimestamp","resourceVersion","selfLink","uid"])' | oc apply -n openshift-config -f -
+----
+
+. Wait for the cluster Operators to roll out and stabilize by running the following command:
++
+[source,terminal]
+----
+$ oc adm wait-for-stable-cluster --minimum-stable-period 2m
+----

security/certificate_types_descriptions/etcd-certificates.adoc

@@ -14,13 +14,20 @@ etcd certificates are signed by the etcd-signer; they come from a certificate au
 
 The CA certificates are valid for 10 years. The peer, client, and server certificates are valid for three years.
 
+include::modules/rotating-certificate-authority.adoc[leveloffset=+1]
+include::modules/etcd-cert-alerts-metrics-signer.adoc[leveloffset=+1]
+
+.Additional resources
+
+* xref:../../security/certificate_types_descriptions/etcd-certificates.adoc#rotating-certificate-authority_cert-types-etcd-certificates[Rotating the etcd certificate]
+
 == Management
 
 These certificates are only managed by the system and are automatically rotated.
 
 == Services
 
-etcd certificates are used for encrypted communication between etcd member peers, as well as encrypted client traffic. The following certificates are generated and used by etcd and other processes that communicate with etcd:
+etcd certificates are used for encrypted communication between etcd member peers and encrypted client traffic. The following certificates are generated and used by etcd and other processes that communicate with etcd:
 
 * Peer certificates: Used for communication between etcd members.
 * Client certificates: Used for encrypted server-client communication. Client certificates are currently used by the API server only, and no other service should connect to etcd directly except for the proxy. Client secrets (`etcd-client`, `etcd-metric-client`, `etcd-metric-signer`, and `etcd-signer`) are added to the `openshift-config`, `openshift-monitoring`, and `openshift-kube-apiserver` namespaces.