Merge pull request #98933 from dfitzmau/OSDOCS-14767

OSDOCS-14767: Expanded steps on customize-certificates-add-service-se…

Author: dfitzmau

modules/customize-certificates-add-service-serving-configmap.adoc

@@ -6,24 +6,16 @@
 [id="add-service-certificate-configmap_{context}"]
 = Add the service CA bundle to a config map
 
-A pod can access the service CA certificate by mounting a `ConfigMap` object that
-is annotated with `service.beta.openshift.io/inject-cabundle=true`.
-Once annotated, the cluster automatically injects the service CA
-certificate into the `service-ca.crt` key on the config map. Access to
-this CA certificate allows TLS clients to verify connections to
-services using service serving certificates.
+A pod can access the service Certificate Authority (CA) certificate by mounting a `ConfigMap` object that has the `service.beta.openshift.io/inject-cabundle=true` annotation. After annotating the config map, the cluster automatically injects the service CA certificate into the `service-ca.crt` key on the config map. Access to this CA certificate allows TLS clients to verify connections to services by using service serving certificates.
 
 [IMPORTANT]
 ====
-After adding this annotation to a config map all existing data in it is
-deleted. It is recommended to use a separate config map to contain the
-`service-ca.crt`, instead of using the same config map that stores your
-pod configuration.
+After adding this annotation to a config map, the OpenShift Service CA Operator deletes all the data in the config map. Consider using a separate config map to contain the `service-ca.crt`, instead of using the same config map that stores your pod configuration.
 ====
 
 .Procedure
 
-. Annotate the config map with `service.beta.openshift.io/inject-cabundle=true`:
+. Annotate the config map with the `service.beta.openshift.io/inject-cabundle=true` annotation by entering the following command:
 +
 [source,terminal]
 ----
@@ -34,15 +26,8 @@ $ oc annotate configmap <config_map_name> \//<1>
 +
 [NOTE]
 ====
-Explicitly referencing the `service-ca.crt` key in a volume mount will prevent a pod from starting until the config map has been injected with the CA bundle. This behavior can be overridden by setting the `optional` field to `true` for the volume's serving certificate configuration.
+Explicitly referencing the `service-ca.crt` key in a volume mount prevents a pod from starting until the config map has been injected with the CA bundle. You can override this behavior by setting the `optional` parameter to `true` in the serving certificate configuration of the volume.
 ====
-+
-For example, use the following command to annotate the config map `test1`:
-+
-[source,terminal]
-----
-$ oc annotate configmap test1 service.beta.openshift.io/inject-cabundle=true
-----
 
 . View the config map to ensure that the service CA bundle has been injected:
 +
@@ -61,3 +46,37 @@ data:
     -----BEGIN CERTIFICATE-----
 ...
 ----
+
+. Mount the config map as a volume to each container that exists in a pod by configuring your `Deployment` object.
++
+.Example Deployment object that defines the volume for the mounted config map
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-example-custom-ca-deployment
+  namespace: my-example-custom-ca-ns
+spec:
+  ...
+    spec:
+      ...
+      containers:
+        - name: my-container-that-needs-custom-ca
+          volumeMounts:
+          - name: trusted-ca
+            mountPath: /etc/pki/ca-trust/extracted/pem
+            readOnly: true
+      volumes:
+      - name: trusted-ca
+        configMap:
+          name: <config_map_name> <1>
+          items:
+            - key: ca-bundle.crt <2>
+              path: tls-ca-bundle.pem <3>
+# ...
+----
+<1> Specify the name of the config map that you annotated in an earlier step of the procedure.
+<2> `ca-bundle.crt` is required as the ConfigMap key.
+<3> `tls-ca-bundle.pem` is required as the ConfigMap path.
+

modules/nw-proxy-configure-object.adoc

@@ -35,8 +35,8 @@ After you enable the cluster-wide proxy capability for your cluster and you save
 
 .Prerequisites
 
-* Cluster administrator permissions
-* {product-title} `oc` CLI tool installed
+* You have cluster administrator permissions.
+* You installed the {product-title} `oc` CLI tool.
 
 .Procedure
 
@@ -46,7 +46,7 @@ After you enable the cluster-wide proxy capability for your cluster and you save
 ====
 You can skip this step if the identity certificate of the proxy is signed by an authority from the {op-system-first} trust bundle.
 ====
-
++
 .. Create a file called `user-ca-bundle.yaml`, and provide the values of your PEM-encoded certificates:
 +
 [source,yaml]
@@ -65,7 +65,7 @@ metadata:
 identity certificate.
 <3> The config map name that is referenced from the `Proxy` object.
 <4> The config map must exist in the `openshift-config` namespace.
-
++
 .. Create the config map from the `user-ca-bundle.yaml` file by entering the following command:
 +
 [source,terminal]