Merge pull request #96169 from ShaunaDiaz/OSDOCS-13052

OSDOCS-13052: updates and clarifies API server custom CAs MicroShift

Author: ShaunaDiaz

microshift_configuring/microshift_auth_security/microshift-custom-ca.adoc

@@ -6,7 +6,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-You can encrypt connections by using custom certificate authorities (CAs) with the {microshift-short} service.
+Allow and encrypt connections with external clients by replacing the {microshift-short} default API server certificate with a custom server certificate issued by a certificate authority (CA).
 
 include::modules/microshift-custom-ca-con.adoc[leveloffset=+1]
 
@@ -20,10 +20,11 @@ include::modules/microshift-custom-ca-cert-cleaning.adoc[leveloffset=+1]
 
 [id="Additional-resources_microshift-custom-ca_{context}"]
 == Additional resources
-* link:https://docs.openshift.com/container-platform/{ocp-version}/security/certificates/api-server.html#customize-certificates-api-add-named_api-server-certificates[OpenShift: Add an API server named certificate]
 
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/securing_networks/creating-and-managing-tls-keys-and-certificates_securing-networks#doc-wrapper[RHEL: Creating and managing TLS keys and certificates]
+* https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/security_and_compliance/configuring-certificates#customize-certificates-api-add-named_api-server-certificates[OpenShift: Add an API server named certificate]
 
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#the-system-wide-trust-store_using-shared-system-certificates[The system-wide truststore]
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/creating-and-managing-tls-keys-and-certificates_securing-networks#doc-wrapper[RHEL: Creating and managing TLS keys and certificates]
 
-* link:https://docs.openshift.com/container-platform/{ocp-version}/cli_reference/openshift_cli/managing-cli-profiles.html[OpenShift CLI Reference: oc login]
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#the-system-wide-trust-store_using-shared-system-certificates[The system-wide truststore]
+
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/cli_tools/openshift-cli-oc#managing-cli-profiles[OpenShift CLI Reference: oc login]

modules/microshift-custom-ca-con.adoc

@@ -4,42 +4,43 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="microshift-custom-cas_{context}"]
-= How custom certificate authorities work in {microshift-short}
+= Using custom certificate authorities for the {microshift-short} API server
 
-The default API server certificate is issued by an internal {microshift-short} cluster certificate authority (CA). Clients outside of the cluster cannot verify the API server certificate by default. This certificate can be replaced by a custom server certificate that is issued externally by a custom CA that clients trust. The following steps illustrate the workflow in {microshift-short}:
+When {microshift-short} starts, an internal {microshift-short} cluster certificate authority (CA) issues the default API server certificate. By default, clients outside of the cluster cannot verify the {microshift-short}-issued API server certificate. You can grant secure access and encrypt connections between the {microshift-short} API server and external clients. Replace the default certificate with a custom server certificate issued externally by a CA that clients trust.
 
-. Copy the certificates and keys to the preferred directory in the host operating system. Ensure that the files are accessible by root only.
+The following steps illustrate the workflow for customizing the API server certificate configuration in {microshift-short}:
+
+. Copy the certificates and keys to the preferred directory in the host operating system. Ensure that the files are accessible only with root access.
 
 . Update the {microshift-short} configuration for each custom CA by specifying the certificate names and new fully qualified domain name (FQDN) in the {microshift-short} `/etc/microshift/config.yaml` configuration file.
 +
 Each certificate configuration can contain the following values:
 
-** The certificate file location is a required value.
-** A single common name containing the API server DNS and IP address or IP address range.
+* The certificate file location is a required value.
+* A single common name containing the API server DNS and IP address or IP address range.
 +
 --
 [TIP]
 ====
-In most cases, {microshift-short} generates a new `kubeconfig` for your custom CA that includes the IP address or range that you specify. The exception is when wildcards are specified for the IP address. In this case, {microshift-short} generates a `kubeconfig` with the public IP address of the server. To use wildcards, you must update the `kubeconfig` file with your specific details.
+In most cases, {microshift-short} generates a new `kubeconfig` file for your custom CA that includes the IP address or range that you specify. The exception is when you specify wildcards for the IP address. In this case, {microshift-short} generates a `kubeconfig` file with the public IP address of the server. To use wildcards, you must update the `kubeconfig` file with your specific details.
 ====
 --
-** Multiple Subject Alternative Names (SANs) containing the API server DNS and IP addresses or a wildcard certificate.
-** You can provide additional DNS names for each certificate.
+* Multiple Subject Alternative Names (SANs) containing the API server DNS and IP addresses or a wildcard certificate.
+* You can list additional DNS names for each certificate.
 
 . After the {microshift-short} service restarts, you must copy the generated `kubeconfig` files to the client.
 
 . Configure additional CAs on the client system. For example, you can update CA bundles in the {op-system-base-full} truststore.
++
+[IMPORTANT]
+====
+Custom server certificates must be validated against CA data configured in the trust root of the host operating system. For more information, read the following documentation:
 
-. The certificates and keys are read from the specified file location on the host. Testing and validation of configuration is done from the client.
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#the-system-wide-trust-store_using-shared-system-certificates[The system-wide truststore]
+====
 
-. External server certificates are not automatically renewed. You must manually rotate your external certificates.
+. The certificates and keys are read from the specified file location on the host. You can test and validate configuration from the client.
 
-[NOTE]
-====
-If any validation fails, the {microshift-short} service skips the custom configuration and uses the default certificate to start. The priority is to continue the service uninterrupted. {microshift-short} logs errors when the service starts. Common errors include expired certificates, missing files, or incorrect IP addresses.
-====
+* If any validation fails, {microshift-short} skips the custom configuration and uses the default certificate to start. The priority is to continue the service uninterrupted. {microshift-short} logs errors when the service starts. Common errors include expired certificates, missing files, or wrong IP addresses.
 
-[IMPORTANT]
-====
-Custom server certificates have to be validated against CA data configured in the trust root of the host operating system. For information, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#the-system-wide-trust-store_using-shared-system-certificates[The system-wide truststore].
-====
+. External server certificates are not automatically renewed. You must manually rotate your external certificates.

modules/microshift-custom-ca-proc.adoc

@@ -6,15 +6,16 @@
 [id="microshift-custom-cas-configuring_{context}"]
 = Configuring custom certificate authorities
 
-To configure externally generated certificates and domain names using custom certificate authorities (CAs), add them to the {microshift-short} `/etc/microshift/config.yaml` configuration file. You must also configure the host operating system trust root.
+To configure externally generated certificates and domain names by using custom certificate authorities (CAs), add them to the {microshift-short} `/etc/microshift/config.yaml` configuration file. You must also configure the host operating system trust root.
 
 [NOTE]
 ====
 Externally generated `kubeconfig` files are created in the `/var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig` directory. If you need to use `localhost` in addition to externally generated configurations, retain the original `kubeconfig` file in its default location. The `localhost` `kubeconfig` file uses the self-signed certificate authority.
 ====
 
 .Prerequisites
-* The OpenShift CLI (`oc`) is installed.
+
+* The {oc-first} is installed.
 * You have access to the cluster as a user with the cluster administration role.
 * The certificate authority has issued the custom certificates.
 * A {microshift-short} `/etc/microshift/config.yaml` configuration file exists.
@@ -40,7 +41,7 @@ apiServer:
 ----
 <1> Add the full path to the certificate.
 <2> Add the full path to the certificate key.
-<3> Optional. Add a list of explicit DNS names. Leading wildcards are allowed. If no names are provided, the implicit names are extracted from the certificates.
+<3> Optional. Add a list of explicit DNS names. Leading wildcards are allowed. If no names are listed, the implicit names are extracted from the certificates.
 
 . Restart the {microshift-short} to apply the certificates by running the following command:
 +
@@ -136,6 +137,6 @@ Server certificate:
 Either replace the `certificate-authority-data` in the generated `kubeconfig` file with the new `rootCA` or add the `certificate-authority-data` to the trust root of the operating system. Do not use both methods.
 ====
 
-.. Configure additional CAs in the trust root of the operating system. For example, in the RHEL Client truststore on the client system. See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#the-system-wide-trust-store_using-shared-system-certificates[The system-wide truststore] for details.
+.. Configure additional CAs in the trust root of the operating system. For example, in the RHEL Client truststore on the client system. link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#the-system-wide-trust-store_using-shared-system-certificates[The system-wide truststore].
 ** Updating the certificate bundle with the configuration that contains the CA is recommended.
 ** If you do not want to configure your certificate bundles, you can alternately use the `oc login localhost:8443 --certificate-authority=/path/to/cert.crt` command, but this method is not preferred.