Merge pull request #1517 from catherineluse/istio-edits

Add clarifications to Istio docs

content/rancher/v2.x/en/cluster-admin/tools/istio/_index.md

@@ -7,6 +7,12 @@ _Available as of v2.3.0-alpha4_
 
 Using Rancher, you can connect, secure, control, and observe services through integration with [Istio](https://istio.io/), a leading open-source service mesh solution. Istio provides behavioral insights and operational control over the service mesh as a whole, offering a complete solution to satisfy the diverse requirements of microservice applications.
 
+## Prerequisites
+
+The required resource allocation for each service is listed in the [configuration options]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/istio/config/). Please review it before attempting to enable Istio.
+
+In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster.
+
 ## Enabling Istio
 
 As an [administrator]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) or [cluster owner]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles), you can configure Rancher to deploy Istio to your Kubernetes cluster.
@@ -21,19 +27,16 @@ As an [administrator]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global
 
 **Result:** The Istio application, `cluster-istio`, is added as an [application]({{< baseurl >}}/rancher/v2.x/en/catalog/apps/) to the cluster's `system` project.  After the application is `active`, you can start using Istio.
 
-> **Note:** When enabling Istio, you need to ensure your worker nodes and Istio pod have enough resources. In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster.
 
-## Using Istio
+## Using Istio for Metrics Visualization
 
-Once Istio is `active`, you can see visualizations of your Istio service mesh across several services:
+Once Istio is `active`, you can see visualizations of your Istio service mesh with Kiali, Jaeger, Grafana, and Prometheus, which are all open-source projects that Rancher has integrated with.
 
 - **Kiali** helps you define, validate, and observe your Istio service mesh. Kiali shows you what services are in your mesh and how they are connected. Kiali includes Jaeger Tracing to provide distributed tracing out of the box.
 - **Jaeger** is a distributed tracing system released as open source by Uber Technologies. It is used for monitoring and troubleshooting microservices-based distributed systems.
 - **Grafana** is an analytics platform that allows you to query, visualize, alert on and understand your metrics. Grafana lets you visualize data from Prometheus.
 - **Prometheus** is a systems monitoring and alerting toolkit.
 
-Kiali, Jaeger, Grafana, and Prometheus are open-source.
-
 With Istio enabled, you can:
 
 - Access [Kiali UI](https://www.kiali.io/) by clicking the Kiali UI icon in the Istio page.
@@ -42,6 +45,10 @@ With Istio enabled, you can:
 - Access [Prometheus UI](https://prometheus.io/) by clicking the Prometheus UI icon in the Istio page.
 - Go to a project to [view traffic graph, traffic metrics and manage traffic]({{< baseurl >}}/rancher/v2.x/en/project-admin/istio/).
 
+## Leveraging Istio in Projects
+
+After you enable Istio, you can see traphic metrics and a traffic graph on the project level. You can see a traffic graph for all namespaces that have Istio sidecar injection enabled. For more information, refer to [How to Use Istio in Your Project]({{< baseurl >}}/rancher/v2.x/en/project-admin/istio/).
+
 ## Disabling Istio
 
 To disable Istio:

content/rancher/v2.x/en/project-admin/istio/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Istio
+title: How to Use Istio in Your Project
 weight: 3528
 ---
 
@@ -7,6 +7,8 @@ _Available as of v2.3.0-alpha4_
 
 Using Rancher, you can connect, secure, control, and observe services through integration with [Istio](https://istio.io/), a leading open-source service mesh solution. Istio provides behavioral insights and operational control over the service mesh as a whole, offering a complete solution to satisfy the diverse requirements of microservice applications.
 
+Istio requires each pod in the service mesh to run an Istio compatible sidecar. This section describes how to set up Istio sidecar auto injection in the Rancher UI. For more information on the Istio sidecar, refer to the [Istio docs](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/).
+
 >**Prerequisites:**
 >
 >- [Istio]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/istio/) must be enabled in the cluster.
@@ -14,11 +16,13 @@ Using Rancher, you can connect, secure, control, and observe services through in
 
 ## Istio Sidecar Auto Injection
 
+If an Istio sidecar is not injected into a pod, Istio will not work for that pod. If you enable Istio sidecar auto injection for a namespace, all pods created in the namespace will have an injected Istio sidecar.
+
 In the create and edit namespace page, you can enable or disable [Istio sidecar auto injection](https://istio.io/blog/2019/data-plane-setup/#automatic-injection). When you enable it, Rancher will add `istio-injection=enabled` label to the namespace automatically.
 
-After the `istio-injection=enabled` label is added to the namespace, all pods that are created in the namespace will have an injected Istio sidecar.
+Injection occurs at pod creation time. If the pod has been created before you enable auto injection, you need to kill the running pod and verify that a new pod is created with the injected sidecar. 
 
-> **Note:** Injection occurs at pod creation time. If the pod has been created before you enable auto injection. You need to kill the running pod and verify a new pod is created with the injected sidecar.
+For information on how to inject the Istio sidecar manually, refer to the [Istio docs](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/).
 
 ## View Traffic Graph