diff --git a/_topic_map.yml b/_topic_map.yml index d7eba2cb583a..a150c8b0c5ca 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -376,6 +376,8 @@ Topics: File: configuring-ingress-cluster-traffic-nodeport - Name: Configuring the cluster-wide proxy File: enable-cluster-wide-proxy +- Name: Configuring a custom PKI + File: configuring-a-custom-pki --- Name: Storage Dir: storage diff --git a/builds/setting-up-trusted-ca.adoc b/builds/setting-up-trusted-ca.adoc index 0f283ab50450..735b2f53b11f 100644 --- a/builds/setting-up-trusted-ca.adoc +++ b/builds/setting-up-trusted-ca.adoc @@ -22,3 +22,4 @@ include::modules/configmap-adding-ca.adoc[leveloffset=+1] * link:https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-a-configmap[Create a ConfigMap] * link:https://kubectl.docs.kubernetes.io/pages/app_management/secrets_and_configmaps.html[Secrets and ConfigMaps] +* xref:../networking/configuring-a-custom-pki.adoc#configuring-a-custom-pki[Configuring a custom PKI] diff --git a/modules/certificate-injection-using-operators.adoc b/modules/certificate-injection-using-operators.adoc new file mode 100644 index 000000000000..387129660866 --- /dev/null +++ b/modules/certificate-injection-using-operators.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * networking/configuring-a-custom-pki.adoc + +[id="certificate-injection-using-operators_{context}"] += Certificate injection using Operators + +Once your custom CA certificate is added to the cluster via ConfigMap, the +Cluster Network Operator merges the user-provided and system CA certificates +into a single bundle and injects the merged bundle into the Operator requesting +the trust bundle injection. + +Operators request this injection by creating an empty ConfigMap with the +following label: + +[source,yaml] +---- +config.openshift.io/inject-trusted-cabundle="true" +---- + +The Operator mounts this ConfigMap into the container's local trust store. + +[NOTE] +==== +Adding a trusted CA certificate is only needed if the certificate is not +included in the {op-system-first} trust bundle. +==== diff --git a/modules/installation-configure-proxy.adoc b/modules/installation-configure-proxy.adoc index 352ebf151a70..4eb0d8fedc8d 100644 --- a/modules/installation-configure-proxy.adoc +++ b/modules/installation-configure-proxy.adoc @@ -7,6 +7,7 @@ // * installing/installing_restricted_networks/installing-restricted-networks-bare-metal.adoc // * installing/installing_restricted_networks/installing-restricted-networks-vsphere.adoc // * installing/installing_vsphere/installing-vsphere.adoc +// * networking/configuring-a-custom-pki.adoc ifeval::["{context}" == "installing-bare-metal"] :bare-metal: diff --git a/modules/nw-ingress-setting-a-custom-default-certificate.adoc b/modules/nw-ingress-setting-a-custom-default-certificate.adoc index 86de63d3fffa..046e17f7c936 100644 --- a/modules/nw-ingress-setting-a-custom-default-certificate.adoc +++ b/modules/nw-ingress-setting-a-custom-default-certificate.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * ingress/ingress-operator.adoc +// * networking/ingress-operator.adoc [id="nw-ingress-setting-a-custom-default-certificate_{context}"] = Setting a custom default certificate @@ -12,8 +12,10 @@ custom resource (CR). .Prerequisites * You must have a certificate/key pair in PEM-encoded files, where the -certificate is signed by a trusted certificate authority and valid for the -Ingress domain. +certificate is signed by a trusted certificate authority or by a private trusted +certificate authority that you have configured. + +* Your certificate is valid for the Ingress domain. * You must have an `IngressController` CR. You may use the default one: + @@ -72,4 +74,4 @@ map[name:custom-certs-default] The certificate secret name should match the value used to update the CR. Once the `IngressController` CR has been modified, the Ingress Operator -will update the Ingress Controller's deployment to use the custom certificate. +updates the Ingress Controller's deployment to use the custom certificate. diff --git a/modules/nw-proxy-configure-object.adoc b/modules/nw-proxy-configure-object.adoc index c16a19184fb3..d82c64c40cef 100644 --- a/modules/nw-proxy-configure-object.adoc +++ b/modules/nw-proxy-configure-object.adoc @@ -1,5 +1,6 @@ // Module included in the following assemblies: // +// * networking/configuring-a-custom-pki.adoc // * networking/enable-cluster-wide-proxy.adoc [id="nw-proxy-configure-object_{context}"] diff --git a/networking/configuring-a-custom-pki.adoc b/networking/configuring-a-custom-pki.adoc new file mode 100644 index 000000000000..3c07d2bbee78 --- /dev/null +++ b/networking/configuring-a-custom-pki.adoc @@ -0,0 +1,47 @@ +[id="configuring-a-custom-pki"] += Configuring a custom PKI +include::modules/common-attributes.adoc[] +:context: configuring-a-custom-pki + +toc::[] + +Some platform components, such as the web console, use Routes for communication and +must trust other components' certificates to interact with them. If +you are using a custom public key infrastructure (PKI), you must configure it so +its privately signed CA certificates are recognized across the cluster. + +You can leverage the Proxy API to add cluster-wide trusted CA certificates. You +must do this either during installation or at runtime. + +* During _installation_, xref:installation-configure-proxy_{context}[configure the cluster-wide proxy]. You must define your +privately signed CA certificates in the `install-config.yaml` file's +`additionalTrustBundle` setting. ++ +The installation program generates a ConfigMap that is named `user-ca-bundle` +that contains the additional CA certificates you defined. The Cluster Network +Operator then creates a `trusted-ca-bundle` ConfigMap that merges these CA +certificates with the {op-system-first} trust bundle; this ConfigMap is +referenced in the Proxy object's `trustedCA` field. + +* At _runtime_, xref:nw-proxy-configure-object_{context}[modify the default Proxy object to include your privately signed +CA certificates] (part of cluster's proxy enablement workflow). This involves +creating a ConfigMap that contains the privately signed CA certificates that +should be trusted by the cluster, and then modifying the proxy resource with the +`trustedCA` referencing the privately signed certificates' ConfigMap. + +[NOTE] +==== +The installer configuration's `additionalTrustBundle` field and the proxy +resource's `trustedCA` field are used to manage the cluster-wide trust bundle; +`additionalTrustBundle` is used at install time and the proxy's `trustedCA` is +used at runtime. + +The `trustedCA` field is a reference to a `ConfigMap` containing the custom +certificate and key pair used by the cluster component. +==== + +include::modules/installation-configure-proxy.adoc[leveloffset=+1] + +include::modules/nw-proxy-configure-object.adoc[leveloffset=+1] + +include::modules/certificate-injection-using-operators.adoc[leveloffset=+1] diff --git a/networking/ingress-operator.adoc b/networking/ingress-operator.adoc index 78dbe5c4a450..8e431ae77119 100644 --- a/networking/ingress-operator.adoc +++ b/networking/ingress-operator.adoc @@ -32,3 +32,7 @@ include::modules/nw-ingress-sharding-route-labels.adoc[leveloffset=+1] include::modules/nw-ingress-sharding-namespace-labels.adoc[leveloffset=+1] //include::modules/nw-ingress-select-route.adoc[leveloffset=+1] + +== Additional resources + +* xref:../networking/configuring-a-custom-pki.adoc#configuring-a-custom-pki[Configuring a custom PKI]