docs: Copy-edit TLS.md

docs/configuration/tls.md

@@ -4,17 +4,17 @@ TLS can be configured via the `tls.secretName` and `tls.clientAuth` parameters o
 
 When TLS is enabled for the external inferencing interface, all of the ModelMesh Serving internal (intra-Pod) communication will be secured using the same certificates. The internal links will use mutual TLS regardless of whether client authentication is required for the external connections.
 
-There are various ways to generate TLS certificates, below are steps on how to do this using OpenSSL or CertManager.
+There are various ways to generate TLS certificates. Below are steps on how to do this using OpenSSL or CertManager.
 
 ## Generating TLS Certificates for Dev/Test using OpenSSL
 
-To create a SAN key/cert for TLS, use command:
+To create a SAN key/cert for TLS, use the following command:
 
 ```shell
 openssl req -x509 -newkey rsa:4096 -sha256 -days 3560 -nodes -keyout example.key -out example.crt -subj '/CN=modelmesh-serving' -extensions san -config openssl-san.config
 ```
 
-Where the contents of `openssl-san.config` look like:
+Where the contents of `openssl-san.config` include:
 
 ```
 [ req ]
@@ -23,7 +23,9 @@ distinguished_name = req
 subjectAltName = DNS:modelmesh-serving.${NAMESPACE},DNS:localhost,IP:0.0.0.0
 ```
 
-With the generated key/cert, create a kube secret with contents like:
+`${NAMESPACE}` is the namespace where the ModelMesh Serving Service is deployed.
+
+From there, you can create a secret using the generated certificate and key:
 
 ```yaml
 apiVersion: v1
@@ -37,13 +39,19 @@ stringData:
   ca.crt: <contents-of-example.crt>
 ```
 
-For basic TLS, only the fields `tls.crt` and `tls.key` are needed in the kube secret. For mutual TLS, add `ca.crt` in the kube secret and set the configuration `tls.clientAuth` to `require` in the ConfigMap `model-serving-config`.
+For basic TLS, only the fields `tls.crt` and `tls.key` are required. For mutual TLS, `ca.crt` should be included and `tls.clientAuth` should be set to `require` in the [`model-serving-config` ConfigMap](./README.md).
+
+You can also create this secret imperatively using:
+
+```
+kubectl create secret tls <secret-name> --cert <cert-file> --key <key-file>
+```
 
 ## Creating TLS Certificates using CertManager
 
-1.  If necessary, install `cert-manager` in the cluster - follow the steps here: https://cert-manager.io/docs/installation/.
+1.  [Install `cert-manager`](https://cert-manager.io/docs/installation/) in the cluster.
 
-2.  Create an `Issuer` CR
+2.  Create an `Issuer` CR, modifying its name if needed:
 
         kubectl apply -f - <<EOF
         apiVersion: cert-manager.io/v1
@@ -54,7 +62,7 @@ For basic TLS, only the fields `tls.crt` and `tls.key` are needed in the kube se
           selfSigned: {}
         EOF
 
-3.  Create a `Certificate` CR
+3.  Create a `Certificate` CR:
 
         kubectl apply -f - <<EOF
         apiVersion: cert-manager.io/v1
@@ -80,19 +88,17 @@ For basic TLS, only the fields `tls.crt` and `tls.key` are needed in the kube se
             kind: Issuer
         EOF
 
-    Where `${NAMESPACE}` is the namespace where the ModelMesh Serving Service resides, and `modelmesh-serving` is the name of that service (configured via the `inferenceServiceName` global ConfigMap parameter).
-
-    Replace `modelmesh-serving-selfsigned-issuer` by the name of the issuer that you're using if needed (see previous step).
+    Above, `${NAMESPACE}` is the namespace where the ModelMesh Serving Service resides, and `modelmesh-serving` is the name of that service (configured via the `inferenceServiceName` [global ConfigMap](./README.md). parameter). You can also replace `issuerRef.name` to match the name of the issuer used above if necessary.
 
-    `${HOSTNAME}` is optional but should be set as follows when configuring an external Kubernetes Ingress or OpenShift route as described [here](./README.md#exposing-an-external-endpoint-using-an-openshift-route):
+    `${HOSTNAME}` is optional, but should be set when configuring an external Kubernetes Ingress or OpenShift route as described [here](./README.md#exposing-an-external-endpoint-using-an-openshift-route):
 
-        HOSTNAME=`oc get route modelmesh-serving -o jsonpath='{.spec.host}'`
+           HOSTNAME=`oc get route modelmesh-serving -o jsonpath='{.spec.host}'`
 
-    If the certificate request is successful, a TLS secret with the PEM-encoded certs will be created as `${SECRET_NAME}`.
+    If the certificate request is successful, a TLS secret with the PEM-encoded certs will be created as `modelmesh-serving-cert`, unless changed above.
 
 4.  Wait for the certificate to be successfully issued
 
-        kubectl get certificate/${SECRET_NAME} --watch
+        kubectl get certificate/modelmesh-serving-cert --watch
 
     Once you see `Ready` as `True`, proceed to the next step.
 
@@ -101,11 +107,9 @@ For basic TLS, only the fields `tls.crt` and `tls.key` are needed in the kube se
 
 5.  Enable TLS in ModelMesh Serving
 
-    As explained before, TLS is enabled through adding a value for `tls.secretName` in the user's ConfigMap that points to an existing kube secret with TLS key/cert details.
-
-    So in this case, it would be `${SECRET_NAME}`, which gets created once the `certificate` is `ready`.
+    As explained before, TLS is enabled by adding a value for `tls.secretName` in the ConfigMap, pointing to an existing secret with the TLS key/cert details.
 
-    **Example:**
+    In this case, it would be `${SECRET_NAME}`, which gets created once the `certificate` is `ready`. For example:
 
         kubectl create -f - <<EOF
         apiVersion: v1