diff --git a/microshift_configuring/microshift_auth_security/microshift-custom-ca.adoc b/microshift_configuring/microshift_auth_security/microshift-custom-ca.adoc index 8b7961218cac..405df75a3182 100644 --- a/microshift_configuring/microshift_auth_security/microshift-custom-ca.adoc +++ b/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] \ No newline at end of file +* 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] \ No newline at end of file diff --git a/modules/microshift-custom-ca-con.adoc b/modules/microshift-custom-ca-con.adoc index d4b850f30a1c..10a3198c91b5 100644 --- a/modules/microshift-custom-ca-con.adoc +++ b/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. diff --git a/modules/microshift-custom-ca-proc.adoc b/modules/microshift-custom-ca-proc.adoc index 7a022e7e4ef1..b84661ddcaac 100644 --- a/modules/microshift-custom-ca-proc.adoc +++ b/modules/microshift-custom-ca-proc.adoc @@ -6,7 +6,7 @@ [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] ==== @@ -14,7 +14,8 @@ Externally generated `kubeconfig` files are created in the `/var/lib/microshift/ ==== .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.