Merge pull request #92357 from mburke5678/mco-manage-ca-cert

OSDOCS:13709 Clarify any references to root-ca/Manage the MCS ignition-ca cert

Author: mburke5678

security/certificate_types_descriptions/machine-config-operator-certificates.adoc

@@ -12,9 +12,10 @@ This certificate authority is used to secure connections from nodes to Machine C
 
 There are two certificates:
 
-* A self-signed CA, the MCS CA
-* A derived certificate, the MCS cert
+. A self-signed CA, the `machine-config-server-ca` config map (MCS CA)
+. A derived certificate, the `machine-config-server-tls` secret (MCS cert)
 
+[id="cert-types-machine-config-operator-certificates-details"]
 === Provisioning details
 
 {product-title} installations that use {op-system-first} are installed by using Ignition. This process is split into two parts:
@@ -24,33 +25,46 @@ There are two certificates:
 
 include::snippets/mcs-endpoint-limitation.adoc[]
 
+[role="_additional-resources"]
 .Additional resources
 
 * xref:../../machine_configuration/index.adoc#machine-config-operator_machine-config-overview[Machine Config Operator].
 
 * xref:../../networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc#about-ovn-kubernetes[About the OVN-Kubernetes network plugin]
 
+[id="cert-types-machine-config-operator-certificates-trust"]
 === Provisioning chain of trust
 
 The MCS CA is injected into the Ignition configuration under the `security.tls.certificateAuthorities` configuration field. The MCS then provides the complete configuration using the MCS cert presented by the web server.
 
 The client validates that the MCS cert presented by the server has a chain of trust to an authority it recognizes. In this case, the MCS CA is that authority, and it signs the MCS cert. This ensures that the client is accessing the correct server. The client in this case is Ignition running on a machine in the initramfs.
 
+[id="cert-types-machine-config-operator-certificates-materials"]
 === Key material inside a cluster
 
-The MCS CA appears in the cluster as a config map in the `kube-system` namespace, `root-ca` object, with `ca.crt` key.  The private key is not stored in the cluster and is discarded after the installation completes.
+The following objects are stored in the `openshift-machine-config-operator` namespace:
 
-The MCS cert appears in the cluster as a secret in the `openshift-machine-config-operator` namespace and `machine-config-server-tls` object with the `tls.crt` and `tls.key` keys.
+* The MCS CA bundle is stored as the `machine-config-server-ca` config map. The MCS CA bundle stores all valid CAs for the `MachineConfigServer` TLS certificate.
+* The MCS CA signing key is stored as the `machine-config-server-ca` secret. The MCS CA signing key is used to sign the `MachineConfigServer` TLS certificate.
+* The MCS cert is stored as the `machine-config-server-tls` secret, which contains the `MachineConfigServer` TLS certificate and key.
 
+The `machine-config-server-ca` config map is used in the following ways:
+
+* The certificate controller updates the `*-user-data` secrets in the `openshift-machine-api` namespace any time the `machine-config-server-ca` configmap is updated.
+* The Machine Config Operator renders the `master-user-data-managed` and `worker-user-data-managed` secrets from the `machine-config-server-ca` configmap.
+
+[id="cert-types-machine-config-operator-certificates-mgmt"]
 == Management
 
 At this time, directly modifying either of these certificates is not supported.
 
+[id="cert-types-machine-config-operator-certificates-exp"]
 == Expiration
-The MCS CA is valid for 10 years.
+The MCS CA and MCS cert are valid for 10 years and are automatically rotated by the MCO at 8 years.
 
 The issued serving certificates are valid for 10 years.
 
+[id="cert-types-machine-config-operator-certificates-custom"]
 == Customization
 
 You cannot customize the Machine Config Operator certificates.