[enterprise-4.3] Bug 1712525, Configuring a custom PKI

_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

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]

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.
+====

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:

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.

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}"]

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]

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]