Refine the multicluster gateways installation documentation (#4307)

* Refine the multicluster gateways installation documentation

Change all occurances of we to you.
Use the kubernetes version macro instead of hard-coding.
Refinements to the wording in various places.
Improvements to the workflow, so it works 100% of the time instead of most of the time.
Add the a warning flag related to the samples certs.
Add more information about stubbing a domain for cloud provides that have specific unique procedures.

* refinements

* Fix shortcode error

* Fix linting problems

* Apply review comments.

content/docs/setup/kubernetes/install/multicluster/gateways/index.md

@@ -8,8 +8,7 @@ keywords: [kubernetes,multicluster,federation,gateway]
 ---
 
 Follow this flow to install an Istio [multicluster service mesh](/docs/concepts/multicluster-deployments/)
-where the Kubernetes cluster services and the applications in each cluster
-are limited to remote communication using gateway IPs.
+when services in a Kubernetes cluster use gateways to communicate with services in other clusters.
 
 Instead of using a central Istio control plane to manage the mesh,
 in this configuration each cluster has an **identical** Istio control plane
@@ -25,7 +24,7 @@ Cross-cluster communication occurs over Istio Gateways of the respective cluster
 
 ## Prerequisites
 
-* Two or more Kubernetes clusters with **1.10 or newer**.
+* Two or more Kubernetes clusters with versions: {{< supported_kubernetes_versions >}}.
 
 * Authority to deploy the [Istio control plane using Helm](/docs/setup/kubernetes/install/helm/)
 on **each** Kubernetes cluster.
@@ -36,7 +35,7 @@ on **each** Kubernetes cluster.
 * A **Root CA**. Cross cluster communication requires mutual TLS connection
   between services. To enable mutual TLS communication across clusters, each
   cluster's Citadel will be configured with intermediate CA credentials
-  generated by a shared root CA. For illustration purposes, we use a
+  generated by a shared root CA. For illustration purposes, you use a
   sample root CA certificate available in the Istio installation
   under the `samples/certs` directory.
 
@@ -62,9 +61,8 @@ on **each** Kubernetes cluster.
     {{< /warning >}}
 
     {{< text bash >}}
-    $ cat install/kubernetes/helm/istio-init/files/crd-* > $HOME/istio.yaml
     $ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
-        -f @install/kubernetes/helm/istio/example-values/values-istio-multicluster-gateways.yaml@ >> $HOME/istio.yaml
+        -f @install/kubernetes/helm/istio/example-values/values-istio-multicluster-gateways.yaml@ > $HOME/istio.yaml
     {{< /text >}}
 
     For further details and customization options, refer to the
@@ -85,6 +83,12 @@ on **each** Kubernetes cluster.
 
     * Create a Kubernetes secret for your generated CA certificates using a command similar to the following. See [Certificate Authority (CA) certificates](/docs/tasks/security/plugin-ca-cert/#plugging-in-the-existing-certificate-and-key) for more details.
 
+        {{< warning >}}
+        The root and intermediate certificate from the samples directory are widely
+        distributed and known.  Do **not** use these certificates in production as
+        your clusters would then be open to security vulnerabilities and compromise.
+        {{< /warning >}}
+
         {{< text bash >}}
         $ kubectl create namespace istio-system
         $ kubectl create secret generic cacerts -n istio-system \
@@ -94,6 +98,14 @@ on **each** Kubernetes cluster.
             --from-file=@samples/certs/cert-chain.pem@
         {{< /text >}}
 
+    * Install Istio's CRDs:
+
+        {{< text bash >}}
+        $ kubectl apply -f install/kubernetes/helm/istio-init/files/crd/
+        {{< /text >}}
+
+    * {{< boilerplate verify-crds >}}
+
     * Use the Istio installation yaml file generated in a previous step to install Istio:
 
         {{< text bash >}}
@@ -110,12 +122,20 @@ services. Services local to a cluster share a common DNS suffix
 (e.g., `svc.cluster.local`). Kubernetes DNS provides DNS resolution for these
 services.
 
-To provide a similar setup for services from remote clusters, we name
+To provide a similar setup for services from remote clusters, you name
 services from remote clusters in the format
 `<name>.<namespace>.global`. Istio also ships with a CoreDNS server that
 will provide DNS resolution for these services. In order to utilize this
-DNS, Kubernetes' DNS needs to be configured to point to CoreDNS as the DNS
-server for the `.global` DNS domain.
+DNS, Kubernetes' DNS must be configured to `stub a domain` for `.global`.
+
+{{< warning >}}
+Some cloud providers have different specific `DNS domain stub` capabilities
+and procedures for their Kubernetes services.  Reference the cloud provider's
+documentation to determine how to `stub DNS domains` for each unique
+environment.  The objective of this bash is to stub a domain for `.global` on
+port `53` to reference or proxy the `istiocoredns` service in Istio's service
+namespace.
+{{< /warning >}}
 
 Create one of the following ConfigMaps, or update an existing one, in each
 cluster that will be calling services in remote clusters
@@ -177,9 +197,8 @@ cluster requires a `ServiceEntry` configuration in the remote cluster.
 The host used in the service entry should be of the form `<name>.<namespace>.global`
 where name and namespace correspond to the service's name and namespace respectively.
 
-To confirm that your multicluster configuration is working, we suggest you proceed to our
-simple [multicluster using gateways](/docs/tasks/multicluster/gateways/)
-example to test your setup.
+Confirm your multicluster configuration is functional with the [multicluster using gateways
+task](/docs/tasks/multicluster/gateways).
 
 ## Uninstalling