Istiotweaks (#153)

* Update _index.md

Fixing some grammar and typos.

* Update introduction.md

Fixed some formatting and grammar.

* Update install.md

Cleaning up formatting and grammar.

* Update deploy.md

Fixed grammar and formatting.

* Update routing.md

Grammar and typo fixes.

* Update visualize.md

fixed some grammar and typos

* Update cleanup.md

Cleaning up grammar and typos

* Update routing.md

Fixed error language message to better illustrate what to expect.

* Update _index.md

Removing callout

Author: geremyCohen

content/servicemesh/_index.md

@@ -1,15 +1,15 @@
 ---
-title: "Servicemesh with Istio"
+title: "Service Mesh with Istio"
 date: 2018-11-13T16:32:30+09:00
 weight: 68
 draft: false
 ---
 
 ### Service Mesh
 
-> A service mesh is a dedicated infrastructure layer for handling **service-to-service communication**. It’s responsible for the reliable delivery of requests through the complex topology of services that comprise a modern, cloud native application
+A service mesh is a dedicated infrastructure layer for handling **service-to-service communication**. It’s responsible for the reliable delivery of requests through the complex topology of services that comprise a modern, cloud native application.
 
-Sservice mesh solution have two distinct components that behave somewhat differently: a data plane and a control plane. Below is an presents the basic architecture.
+Service mesh solutions have two distinct components that behave somewhat differently: 1) a data plane, and 2) a control plane. The following diagram illustrates the basic architecture.
 
 ![Service Mesh Architecture](/images/servicemesh-intro1.png)
 

content/servicemesh/cleanup.md

@@ -5,29 +5,31 @@ weight: 70
 draft: false
 ---
 
-#### Remove telemetry configuration / port-forward process
+To cleanup, follow the below steps.
+
+To remove telemetry configuration / port-forward process
 
 ```
 kubectl delete -f istio-telemetry.yaml
 ```
 
-#### Remove the application virtual services / destination rules
+To remove the application virtual services / destination rules
 
 ```
 kubectl delete -f samples/bookinfo/networking/virtual-service-all-v1.yaml
 
 kubectl delete -f samples/bookinfo/networking/destination-rule-all.yaml
 ```
 
-#### Remove the gateway / application
+To remove the gateway / application
 
 ```
 kubectl delete -f samples/bookinfo/networking/bookinfo-gateway.yaml
 
 kubectl delete -f samples/bookinfo/platform/kube/bookinfo.yaml
 ```
 
-#### Remove the Istio
+To remove Istio
 
 ```
 kubectl delete -f istio.yaml

content/servicemesh/deploy.md

@@ -5,7 +5,7 @@ weight: 40
 draft: false
 ---
 
-> Now that we have all the resources installed for Istio, we will use sample application called BookInfo to review key capabilities of Service Mesh such as intelligent routing and review telemetry data using Prometheus & Grafana.
+Now that we have all the resources installed for Istio, we will use sample application called BookInfo to review key capabilities of the service mesh such as intelligent routing, and review telemetry data using Prometheus & Grafana.
 
 ### Sample Apps
 
@@ -47,7 +47,13 @@ Deploy sample apps by manually injecting istio proxy and confirm pods, services
 kubectl apply -f <(istioctl kube-inject -f samples/bookinfo/platform/kube/bookinfo.yaml)
 ```
 
-The output from 'kubectl get pod, svc' will look like this.
+The output from
+
+```
+kubectl get pod,svc
+```
+
+Should look similar to:
 
 ```
 NAME                              READY     STATUS    RESTARTS   AGE
@@ -66,21 +72,31 @@ ratings       ClusterIP   10.100.1.63      <none>        9080/TCP   17s
 reviews       ClusterIP   10.100.255.157   <none>        9080/TCP   17s
 ```
 
-and define virtualservice, ingressgateway and find out ELB endpoint to get connected from your browser.
+Next we'll define the virtual service and ingress gateway:
 
 ```
 kubectl apply -f samples/bookinfo/networking/bookinfo-gateway.yaml
+```
 
-kubectl get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' -n istio-system 
+Next, we'll query the DNS name of the ingress gateway and use it to connect via the browser.
+
+```
+kubectl get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' -n istio-system ; echo
 ```
+
 This may take a minute or two, first for the Ingress to be created, and secondly for the Ingress to hook up with the services it exposes.
 
-Open a browser and connect to the endpoint that you get from istio-ingressgateway to see whether sample app is working.
+To test, do the following:
+
+1. Open a new browser tab
+2. Paste the DNS endpoint returned from the previous ```get service istiogateway``` command
+3. Add /productpage to the end of that DNS endpoint
+4. Hit enter to retrieve the page.
 
 {{% notice info %}}
-You have to add **/productpage** at the end of the URI in the browser to see the sample webpage
+Remember to add **/productpage** to the end of the URI in the browser to see the sample webpage!
 {{% /notice %}}
 
 ![Sample Apps](/images/servicemesh-deploy2.png)
 
-> Iterate reloading the page and check out review section calls different versions of reviews (v1, v2, v3) each time
+Click reload multiple times to see how the layout and content of the reviews changes as differnt versions (v1, v2, v3) of the app are called.

content/servicemesh/install.md

@@ -6,14 +6,13 @@ draft: false
 ---
 
 ### Install Istio's CRD
-The CRD(Custom Resource Definition) API resource allows you to define custom resources. To find more about CRD click [here](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions).
-
+The [Custom Resource Definition, also known as a CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions), is an API resource which allows you to define custom resources. 
 ```
 kubectl apply -f install/kubernetes/helm/istio/templates/crds.yaml
 ```
 
 ### Install Istio
-Make sure you have Helm to install Istio into your EKS Cluster.
+Helm is required for the following examples.  If you have not installed Helm yet, [please first reference the Helm chapter](/helm_root) before proceeding.
 
 ```
 kubectl create -f install/kubernetes/helm/helm-service-account.yaml
@@ -25,7 +24,13 @@ kubectl create namespace istio-system
 kubectl apply -f istio.yaml
 ```
 
-You can watch the progress of installation using 'kubectl get pod -n istio-system -w'
+Watch the progress of installation using:
+
+```
+kubectl get pod -n istio-system -w
+```
+
+And hit CTRL-C when you're ready to proceed.
 
 ```
 NAME                                    READY     STATUS      RESTARTS   AGE

content/servicemesh/introduction.md

@@ -9,12 +9,12 @@ draft: false
 
 ![Istio Architecture](/images/servicemesh-intro2.png)
 
-> Let's review in detail what each of these components are,
->
-> It is a completely open source service mesh that layers transparently onto existing distributed applications. It is also a platform, including APIs that let it integrate into any logging platform, or telemetry or policy system.
+Istio is a completely open source service mesh that layers transparently onto existing distributed applications. It's also a platform, including APIs, that let it integrate into any logging platform, or telemetry or policy system.
+
+Let's review in more detail what each of the components that make up this service mesh are.
 
 * <span style="color:orange">**Envoy**</span>
-  * Process the inbound/outbound traffic from inter-service and service-to-external-service transparently.
+  * Processes the inbound/outbound traffic from inter-service and service-to-external-service transparently.
 
 * <span style="color:orange">**Pilot**</span>
   * Pilot provides service discovery for the Envoy sidecars, traffic management capabilities for intelligent routing (e.g., A/B tests, canary deployments, etc.), and resiliency (timeouts, retries, circuit breakers, etc.)

content/servicemesh/routing.md

@@ -7,9 +7,9 @@ draft: false
 
 ### Intelligent Routing
 
-> Deploying a microservice-based application in an Istio service mesh allows one to externally control service monitoring and tracing, request (version) routing, resiliency testing, security and policy enforcement, etc., In a consistent way across the services, for the application as a whole.
+Deploying a microservice-based application in an Istio service mesh allows one to externally control service monitoring and tracing, request (version) routing, resiliency testing, security and policy enforcement, and more in a consistent manner across the services, and the application.
 
-Before you can use Istio to control the Bookinfo version routing, you need to define the available versions, called <span style="color:orange">**subsets**</span>, in destination rules.
+Before you can use Istio to control the Bookinfo version routing, you'll need to define the available versions, called <span style="color:orange">**subsets**</span>, in destination rules.
 
 {{% notice info %}}
 Service versions (a.k.a. subsets) - In a continuous deployment scenario, for a given service, there can be distinct subsets of instances running different variants of the application binary. These variants are not necessarily different API versions. They could be iterative changes to the same service, deployed in different environments (prod, staging, dev, etc.). Common scenarios where this occurs include A/B testing, canary rollouts, etc. The choice of a particular version can be decided based on various criterion (headers, url, etc.) and/or by weights assigned to each version. Each service has a default version consisting of all its instances.
@@ -42,9 +42,9 @@ spec:
         subset: v1
 ```
 
-> Iterate reloading the page and check out review section calls only version of reviews v1 all the time
+Try now to reload the page multiple times, and note how only version 1 of reviews is displayed each time.
 
-Change the route configuration so that all traffic from a specific user is routed to a specific service version. In this case, all traffic from a user named <span style="color:orange">*Jason*</span> will be routed to the service <span style="color:orange">**reviews:v2**</span>.
+Next, we'll change the route configuration so that all traffic from a specific user is routed to a specific service version. In this case, all traffic from a user named <span style="color:orange">*Jason*</span> will be routed to the service <span style="color:orange">**reviews:v2**</span>.
 
 ```
 kubectl apply -f samples/bookinfo/networking/virtual-service-reviews-test-v2.yaml
@@ -73,7 +73,7 @@ spec:
         subset: v1
 ```
 
-> Click Sign in on top right corner and login using 'jason' as user name with blank password. You will only see reviews:v2 all the time. Others will see reviews:v1
+To test, click **Sign in** from the top right corner of the page, and login using **jason** as user name with a blank password. You will only see reviews:v2 all the time. Others will see reviews:v1.
 
 To test for resiliency, inject a 7s delay between the reviews:v2 and ratings microservices for user jason. This test will uncover a bug that was intentionally introduced into the Bookinfo app.
 
@@ -108,9 +108,9 @@ spec:
         subset: v1
 ```
 
-> Click Sign in on top right corner and login using 'jason' as user name with blank password. You will see the delays and it ends up display error for reviews. Others will see reviews without error.
->
-> The timeout between the productpage and the reviews service is 6 seconds - coded as 3s + 1 retry for 6s total.
+Logout, then click **Sign in** from the top right corner of the page, using **jason** as the user name with a blank password. You will see the delays and it ends up display error for reviews. Others will see reviews without error.
+
+The timeout between the productpage and the reviews service is 6 seconds - coded as 3s + 1 retry for 6s total.
 
 To test for another resiliency, introduce an HTTP abort to the ratings microservices for the test user jason. The page will immediately display the “<span style="color:orange">*Ratings service is currently unavailable*</span>”
 
@@ -120,7 +120,7 @@ kubectl apply -f samples/bookinfo/networking/virtual-service-ratings-test-abort.
 kubectl get virtualservice ratings -o yaml
 ```
 
-The subset is set to v1 in default and return 500 HTTP error for all the request if the logged user is match with 'jason' for ratings.
+The subset is set to v1 and by default returns an error message of "Ratings service is currently unavailable" below the reviewer name if the logged username matches 'jason'.
 
 ```
 spec:
@@ -144,9 +144,10 @@ spec:
         host: ratings
         subset: v1
 ```
-> Click Sign in on top right corner and login using 'jason' as user name with blank password. You will see error for ratings. Others will see rating without error.
 
-This demo shows you how to gradually migrate traffic from one version of a microservice to another. Send <span style="color:orange">50% of traffic to reviews:v1</span> and <span style="color:blue">50% to reviews:v3</span>.
+To test, click **Sign in** from the top right corner of the page and login using **jason** for the user name with a blank password. As **jason** you will see the error message. Others (not logged in as **jason**) will see no error message.
+
+Next, we'll demonstrate how to gradually migrate traffic from one version of a microservice to another. In our example, we'll send <span style="color:orange">50% of traffic to reviews:v1</span> and <span style="color:blue">50% to reviews:v3</span>.
 
 ```
 kubectl apply -f samples/bookinfo/networking/virtual-service-all-v1.yaml
@@ -173,4 +174,4 @@ spec:
       weight: 50
 ```
 
-> keep refreshing your browser. You will see the pages for reviews:v1 and reviews:v3
+To test it, refresh your browser over and over, and you'll see only reviews:v1 and reviews:v3.

content/servicemesh/visualize.md

@@ -7,15 +7,15 @@ draft: false
 
 ### Collecting new telemetry data
 
-Download a YAML file to hold configuration for the new metric and log stream that Istio will generate and collect automatically.
+Next, download a YAML file to hold configuration for the new metric and log stream that Istio will generate and collect automatically.
 
 ```
 curl -LO https://eksworkshop.com/servicemesh/deploy.files/istio-telemetry.yaml
 
 kubectl apply -f istio-telemetry.yaml
 ```
 
-Make sure prometheus and grafana is running
+Make sure Prometheus and Grafana are running
 
 ```
 kubectl -n istio-system get svc prometheus
@@ -52,4 +52,4 @@ You will see that the traffic is evenly spread between <span style="color:orange
 
 ![Grafana Dashabord](/images/servicemesh-visualize1.png)
 
-We encourage you to review other Istio dashboards that are available by clicking Istio Mesh Dashboard Menu on top left and selecting different dashboard
+We encourage you to explore other Istio dashboards that are available by clicking the **Istio Mesh Dashboard** menu on top left of the page, and selecting a different dashboard.