bz2062068 updating CA bundle certificates

additional changes

xref update

adoc not html

xref fix

fixed travis build error

sme feedback

peer review feedback

Author: sheriff-rh

_topic_maps/_topic_map.yml

@@ -739,6 +739,8 @@ Topics:
     File: api-server
   - Name: Securing service traffic using service serving certificates
     File: service-serving-certificate
+  - Name: Updating the CA bundle
+    File: updating-ca-bundle
 - Name: Certificate types and descriptions
   Dir: certificate_types_descriptions
   Distros: openshift-enterprise,openshift-origin

modules/ca-bundle-replacing.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * security/certificates/updating-ca-bundle.adoc
+
+:_content-type: PROCEDURE
+[id="ca-bundle-replacing_{context}"]
+= Replacing the CA Bundle certificate
+
+.Procedure
+
+. Create a config map that includes the root CA certificate used to sign the wildcard certificate:
++
+[source,terminal]
+----
+$ oc create configmap custom-ca \
+     --from-file=ca-bundle.crt=</path/to/example-ca.crt> \//<1>
+     -n openshift-config
+----
+<1> `</path/to/example-ca.crt>` is the path to the CA certificate bundle on your local file system.
+
+. Update the cluster-wide proxy configuration with the newly created config map:
++
+[source,terminal]
+----
+$ oc patch proxy/cluster \
+     --type=merge \
+     --patch='{"spec":{"trustedCA":{"name":"custom-ca"}}}'
+----

modules/ca-bundle-understanding.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * security/certificates/updating-ca-bundle.adoc
+
+:_content-type: SNIPPET
+[id="ca-bundle-understanding_{context}"]
+= Understanding the CA Bundle certificate
+
+Proxy certificates allow users to specify one or more custom certificate authority (CA) used by platform components when making egress connections.
+
+The `trustedCA` field of the Proxy object is a reference to a config map that contains a user-provided trusted certificate authority (CA) bundle. This bundle is merged with the {op-system-first} trust bundle and injected into the trust store of platform components that make egress HTTPS calls. For example, `image-registry-operator` calls an external image registry to download images. If `trustedCA` is not specified, only the {op-system} trust bundle is used for proxied HTTPS connections. Provide custom CA certificates to the {op-system} trust bundle if you want to use your own certificate infrastructure.
+
+The `trustedCA` field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from required key `ca-bundle.crt` and copying it to a config map named `trusted-ca-bundle` in the `openshift-config-managed` namespace. The namespace for the config map referenced by `trustedCA` is `openshift-config`:
+
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: user-ca-bundle
+  namespace: openshift-config
+data:
+  ca-bundle.crt: |
+    -----BEGIN CERTIFICATE-----
+    Custom CA certificate bundle.
+    -----END CERTIFICATE-----
+----

networking/enable-cluster-wide-proxy.adoc

@@ -22,3 +22,10 @@ For installations on Amazon Web Services (AWS), Google Cloud Platform (GCP), Mic
 include::modules/nw-proxy-configure-object.adoc[leveloffset=+1]
 
 include::modules/nw-proxy-remove.adoc[leveloffset=+1]
+
+[discrete]
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../security/certificates/updating-ca-bundle.adoc#ca-bundle-understanding_updating-ca-bundle[Replacing the CA Bundle certificate]
+* xref:../security/certificate_types_descriptions/proxy-certificates.adoc#customization[Proxy certificate customization]

security/certificates/replacing-default-ingress-certificate.adoc

@@ -9,3 +9,10 @@ toc::[]
 include::modules/customize-certificates-understanding-default-router.adoc[leveloffset=+1]
 
 include::modules/customize-certificates-replace-default-router.adoc[leveloffset=+1]
+
+[discrete]
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../../security/certificates/updating-ca-bundle.adoc#ca-bundle-understanding_updating-ca-bundle[Replacing the CA Bundle certificate]
+* xref:../../security/certificate_types_descriptions/proxy-certificates.adoc#customization[Proxy certificate customization]

security/certificates/updating-ca-bundle.adoc

@@ -0,0 +1,19 @@
+:_content-type: ASSEMBLY
+[id="updating-ca-bundle"]
+= Updating the CA bundle
+include::_attributes/common-attributes.adoc[]
+:context: updating-ca-bundle
+
+toc::[]
+
+include::modules/ca-bundle-understanding.adoc[leveloffset=+1]
+
+include::modules/ca-bundle-replacing.adoc[leveloffset=+1]
+
+[discrete]
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../../security/certificates/replacing-default-ingress-certificate.adoc#replacing-default-ingress_replacing-default-ingress[Replacing the default ingress certificate]
+* xref:../../networking/enable-cluster-wide-proxy.adoc#nw-proxy-configure-object_config-cluster-wide-proxy[Enabling the cluster-wide proxy]
+* xref:../../security/certificate_types_descriptions/proxy-certificates.adoc#customization[Proxy certificate customization]