Clean up tasks (#549)

* Adding guides for telemetry

* nits

* nit

* egress

* consul install file fix

* more task cleanup

* nits

* update telemetry tasks

* more tweaks

* remove what's next

* tweaks to security tasks

* some nits to telemetry guide

* overall tweaks

Gemfile.lock

@@ -6,32 +6,32 @@ GEM
       minitest (~> 5.1)
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    addressable (2.5.1)
+    addressable (2.5.2)
-      public_suffix (~> 2.0, >= 2.0.2)
+      public_suffix (>= 2.0.2, < 4.0)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
-    coffee-script-source (1.12.2)
+    coffee-script-source (1.11.1)
     colorator (1.1.0)
-    colored (1.2)
+    colorize (0.8.1)
     ethon (0.10.1)
       ffi (>= 1.3.0)
     execjs (2.7.0)
-    faraday (0.12.1)
+    faraday (0.13.1)
       multipart-post (>= 1.2, < 3)
     ffi (1.9.18)
     forwardable-extended (2.6.0)
     gemoji (3.0.0)
-    github-pages (146)
+    github-pages (161)
       activesupport (= 4.2.8)
       github-pages-health-check (= 1.3.5)
-      jekyll (= 3.4.5)
+      jekyll (= 3.5.2)
-      jekyll-avatar (= 0.4.2)
+      jekyll-avatar (= 0.5.0)
-      jekyll-coffeescript (= 1.0.1)
+      jekyll-coffeescript (= 1.0.2)
       jekyll-default-layout (= 0.1.4)
       jekyll-feed (= 0.9.2)
-      jekyll-gist (= 1.4.0)
+      jekyll-gist (= 1.4.1)
-      jekyll-github-metadata (= 2.5.1)
+      jekyll-github-metadata (= 2.9.3)
       jekyll-mentions (= 1.2.0)
       jekyll-optional-front-matter (= 0.2.0)
       jekyll-paginate (= 1.1.0)
@@ -39,26 +39,26 @@ GEM
       jekyll-redirect-from (= 0.12.1)
       jekyll-relative-links (= 0.4.1)
       jekyll-sass-converter (= 1.5.0)
-      jekyll-seo-tag (= 2.2.3)
+      jekyll-seo-tag (= 2.3.0)
-      jekyll-sitemap (= 1.0.0)
+      jekyll-sitemap (= 1.1.1)
       jekyll-swiss (= 0.4.0)
-      jekyll-theme-architect (= 0.0.4)
+      jekyll-theme-architect (= 0.1.0)
-      jekyll-theme-cayman (= 0.0.4)
+      jekyll-theme-cayman (= 0.1.0)
-      jekyll-theme-dinky (= 0.0.4)
+      jekyll-theme-dinky (= 0.1.0)
-      jekyll-theme-hacker (= 0.0.4)
+      jekyll-theme-hacker (= 0.1.0)
-      jekyll-theme-leap-day (= 0.0.4)
+      jekyll-theme-leap-day (= 0.1.0)
-      jekyll-theme-merlot (= 0.0.4)
+      jekyll-theme-merlot (= 0.1.0)
-      jekyll-theme-midnight (= 0.0.4)
+      jekyll-theme-midnight (= 0.1.0)
-      jekyll-theme-minimal (= 0.0.4)
+      jekyll-theme-minimal (= 0.1.0)
-      jekyll-theme-modernist (= 0.0.4)
+      jekyll-theme-modernist (= 0.1.0)
-      jekyll-theme-primer (= 0.3.1)
+      jekyll-theme-primer (= 0.5.2)
-      jekyll-theme-slate (= 0.0.4)
+      jekyll-theme-slate (= 0.1.0)
-      jekyll-theme-tactile (= 0.0.4)
+      jekyll-theme-tactile (= 0.1.0)
-      jekyll-theme-time-machine (= 0.0.4)
+      jekyll-theme-time-machine (= 0.1.0)
-      jekyll-titles-from-headings (= 0.2.0)
+      jekyll-titles-from-headings (= 0.4.0)
       jemoji (= 0.8.0)
       kramdown (= 1.13.2)
-      liquid (= 3.0.6)
+      liquid (= 4.0.0)
       listen (= 3.0.6)
       mercenary (~> 0.3)
       minima (= 2.1.1)
@@ -70,41 +70,42 @@ GEM
       octokit (~> 4.0)
       public_suffix (~> 2.0)
       typhoeus (~> 0.7)
-    html-pipeline (2.6.0)
+    html-pipeline (2.7.1)
       activesupport (>= 2)
       nokogiri (>= 1.4)
-    html-proofer (3.7.2)
+    html-proofer (3.7.3)
       activesupport (>= 4.2, < 6.0)
       addressable (~> 2.3)
-      colored (~> 1.2)
+      colorize (~> 0.8)
       mercenary (~> 0.3.2)
       nokogiri (~> 1.7)
       parallel (~> 1.3)
       typhoeus (~> 0.7)
       yell (~> 2.0)
     i18n (0.8.6)
-    jekyll (3.4.5)
+    jekyll (3.5.2)
       addressable (~> 2.4)
       colorator (~> 1.0)
       jekyll-sass-converter (~> 1.0)
       jekyll-watch (~> 1.1)
       kramdown (~> 1.3)
-      liquid (~> 3.0)
+      liquid (~> 4.0)
       mercenary (~> 0.3.3)
       pathutil (~> 0.9)
       rouge (~> 1.7)
       safe_yaml (~> 1.0)
-    jekyll-avatar (0.4.2)
+    jekyll-avatar (0.5.0)
       jekyll (~> 3.0)
-    jekyll-coffeescript (1.0.1)
+    jekyll-coffeescript (1.0.2)
       coffee-script (~> 2.2)
+      coffee-script-source (~> 1.11.1)
     jekyll-default-layout (0.1.4)
       jekyll (~> 3.0)
     jekyll-feed (0.9.2)
       jekyll (~> 3.3)
-    jekyll-gist (1.4.0)
+    jekyll-gist (1.4.1)
       octokit (~> 4.2)
-    jekyll-github-metadata (2.5.1)
+    jekyll-github-metadata (2.9.3)
       jekyll (~> 3.1)
       octokit (~> 4.0, != 4.4.0)
     jekyll-include-cache (0.1.0)
@@ -124,38 +125,52 @@ GEM
       jekyll (~> 3.3)
     jekyll-sass-converter (1.5.0)
       sass (~> 3.4)
-    jekyll-seo-tag (2.2.3)
+    jekyll-seo-tag (2.3.0)
       jekyll (~> 3.3)
-    jekyll-sitemap (1.0.0)
+    jekyll-sitemap (1.1.1)
       jekyll (~> 3.3)
     jekyll-swiss (0.4.0)
-    jekyll-theme-architect (0.0.4)
+    jekyll-theme-architect (0.1.0)
-      jekyll (~> 3.3)
+      jekyll (~> 3.5)
-    jekyll-theme-cayman (0.0.4)
+      jekyll-seo-tag (~> 2.0)
-      jekyll (~> 3.3)
+    jekyll-theme-cayman (0.1.0)
-    jekyll-theme-dinky (0.0.4)
+      jekyll (~> 3.5)
-      jekyll (~> 3.3)
+      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-hacker (0.0.4)
+    jekyll-theme-dinky (0.1.0)
-      jekyll (~> 3.3)
+      jekyll (~> 3.5)
-    jekyll-theme-leap-day (0.0.4)
+      jekyll-seo-tag (~> 2.0)
-      jekyll (~> 3.3)
+    jekyll-theme-hacker (0.1.0)
-    jekyll-theme-merlot (0.0.4)
+      jekyll (~> 3.5)
-      jekyll (~> 3.3)
+      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-midnight (0.0.4)
+    jekyll-theme-leap-day (0.1.0)
-      jekyll (~> 3.3)
+      jekyll (~> 3.5)
-    jekyll-theme-minimal (0.0.4)
+      jekyll-seo-tag (~> 2.0)
-      jekyll (~> 3.3)
+    jekyll-theme-merlot (0.1.0)
-    jekyll-theme-modernist (0.0.4)
+      jekyll (~> 3.5)
-      jekyll (~> 3.3)
+      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-primer (0.3.1)
+    jekyll-theme-midnight (0.1.0)
-      jekyll (~> 3.3)
+      jekyll (~> 3.5)
-    jekyll-theme-slate (0.0.4)
+      jekyll-seo-tag (~> 2.0)
-      jekyll (~> 3.3)
+    jekyll-theme-minimal (0.1.0)
-    jekyll-theme-tactile (0.0.4)
+      jekyll (~> 3.5)
-      jekyll (~> 3.3)
+      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-time-machine (0.0.4)
+    jekyll-theme-modernist (0.1.0)
-      jekyll (~> 3.3)
+      jekyll (~> 3.5)
-    jekyll-titles-from-headings (0.2.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-primer (0.5.2)
+      jekyll (~> 3.5)
+      jekyll-github-metadata (~> 2.9)
+      jekyll-seo-tag (~> 2.2)
+    jekyll-theme-slate (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-tactile (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-time-machine (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-titles-from-headings (0.4.0)
       jekyll (~> 3.3)
     jekyll-watch (1.5.0)
       listen (~> 3.0, < 3.1)
@@ -165,7 +180,7 @@ GEM
       html-pipeline (~> 2.2)
       jekyll (>= 3.0)
     kramdown (1.13.2)
-    liquid (3.0.6)
+    liquid (4.0.0)
     listen (3.0.6)
       rb-fsevent (>= 0.9.3)
       rb-inotify (>= 0.9.7)
@@ -173,14 +188,14 @@ GEM
     mini_portile2 (2.1.0)
     minima (2.1.1)
       jekyll (~> 3.3)
-    minitest (5.10.2)
+    minitest (5.10.3)
     multipart-post (2.0.0)
     net-dns (0.8.0)
     nokogiri (1.7.2)
       mini_portile2 (~> 2.1.0)
     octokit (4.7.0)
       sawyer (~> 0.8.0, >= 0.5.3)
-    parallel (1.11.2)
+    parallel (1.12.0)
     pathutil (0.14.0)
       forwardable-extended (~> 2.6)
     public_suffix (2.0.5)

_docs/concepts/traffic-management/rules-configuration.md

@@ -44,7 +44,7 @@ will receive traffic.
 Rules can be configured using the
 [istioctl CLI]({{home}}/docs/reference/commands/istioctl.html), or in a Kubernetes
 deployment using the `kubectl` command instead. See the
-[configuring request routing task]({{home}}/docs/tasks/request-routing.html) for
+[configuring request routing task]({{home}}/docs/tasks/traffic-management/request-routing.html) for
 examples.
 
 There are three kinds of traffic management rules in Istio: **Route Rules**, **Destination
@@ -280,7 +280,7 @@ spec:
 Note that request timeouts and retries can also be
 [overridden on a per-request basis](./handling-failures.html#fine-tuning).
 
-See the [request timeouts task]({{home}}/docs/tasks/request-timeouts.html) for a demonstration of timeout control.
+See the [request timeouts task]({{home}}/docs/tasks/traffic-management/request-timeouts.html) for a demonstration of timeout control.
 
 ### Injecting faults in the request path
 
@@ -358,7 +358,7 @@ spec:
       httpStatus: 400
 ```
 
-To see fault injection in action, see the [fault injection task]({{home}}/docs/tasks/fault-injection.html).
+To see fault injection in action, see the [fault injection task]({{home}}/docs/tasks/traffic-management/fault-injection.html).
 
 ### Rules have precedence
 

_docs/guides/bookinfo.md

@@ -1,12 +1,11 @@
 ---
-title: Bookinfo Sample Application
+1;95;0ctitle: Bookinfo Sample Application
 overview: This guide deploys a sample application composed of four separate microservices which will be used to demonstrate various features of the Istio service mesh.
 
 order: 10
 
 layout: docs
 type: markdown
-redirect_from: "/docs/samples/bookinfo.html"
 ---
 {% include home.html %}
 

_docs/guides/guide.md.template

@@ -0,0 +1,43 @@
+// Before use, remove this line and uncomment the next line
+// ---
+title: My Guide
+overview: Provide a simple one sentence overview of this guide's content
+
+order: 42
+
+layout: docs
+type: markdown
+---
+
+Provide a simple one sentence overview of this guides's content.
+
+## Overview
+
+Provide a high level overview of what users can expect to learn, why these
+features are important, and so on. This is not a task, but a feature of
+Istio.
+
+## Before you begin
+
+List action prerequisites and knowledge prerequisites.
+
+## Application Setup
+
+1. Steps to setup the application
+
+## Tasks
+
+1. some tasks that will complete the goal of this sample.
+
+## <Your Topic Headlines>
+
+<Your Topic Content>
+
+## Cleanup
+
+placeholder
+
+## Further reading
+
+It's good to close with a 'what's next' section to point people to
+other related material.

_docs/guides/integrating-vms.md

@@ -1,9 +1,8 @@
 ---
-title: Integrating Virtual Machines
+title: Integrating Virtual Machines in Google Cloud
 overview: This sample deploys the Bookinfo services across Kubernetes and a set of virtual machines, and illustrates how to use the Istio service mesh to control this infrastructure as a single mesh.
 
 order: 60
-draft: true
 layout: docs
 type: markdown
 ---
@@ -13,20 +12,72 @@ This sample deploys the Bookinfo services across Kubernetes and a set of
 Virtual Machines, and illustrates how to use Istio service mesh to control
 this infrastructure as a single mesh.
 
-## Before you begin
-* Describe installation options.
-
-* Install Istio control plane in a Kubernetes cluster by following the quick start instructions in the
-[Installation guide]({{home}}/docs/setup/kubernetes/).
-
 ## Overview
 
-Placeholder.
+Provide a high level overview of what users can expect to learn, why these
+features are important, and so on. This is not a task, but a feature of
+Istio.
 
-## Application Setup
+## Before you begin
 
-1. Steps
+* Setup Istio by following the instructions in the
+  [Installation guide](({{home}}/docs/setup/).
 
-## Tasks
+* Deploy the [BookInfo]({{home}}/docs/guides/bookinfo.html) sample application.
 
-1. some tasks that will complete the goal of this sample.
+* Create a VM named 'db' in the same project as Istio cluster, and [Join the Mesh]({{home}}/docs/setup/kubernetes/mesh-expansion.html).
+
+## Running mysql on the VM
+
+We will first install mysql on the VM, and configure it as a backend for the ratings service.
+
+On the VM:
+```bash
+  sudo apt-get update && apt-get install ...
+  # TODO copy or link the istio/istio test script
+```
+
+## Registering the mysql service with the mesh
+
+### Machine admin
+First step is to configure the VM sidecar, by adding the service port and restarting the sidecar.
+
+On the DB machine:
+```bash
+
+  sudo echo "ISTIO_INBOUND_PORTS=..." > /var/lib/istio/envoy/sidecar.env
+  sudo chown istio-proxy /var/lib/istio/envoy/sidecar.env
+  sudo systemctl restart istio
+ # Or
+  db$ sudo istio-pilot vi /var/lib/istio/envoy/sidecar.env
+  # add mysql port to the "ISTIO_INBOUND_PORTS" config
+  ```
+
+###  Cluster admin
+
+  If you previously run the mysql bookinfo on kubernetes, you need to remove the k8s mysql service:
+
+  ```bash
+  kubectl delete service mysql
+  ```
+
+  Run istioctl to configure the service (on your admin machine):
+
+  ```bash
+  istioctl register mysql PORT IP
+  ```
+
+  Note that the 'db' machine does not need and should not have special kubernetes priviledges.
+
+## Registering the mongodb service with the Mesh
+
+ In progress...
+
+## Using the mysql service
+
+The ratings service in bookinfo will use the DB on the machine. To verify it works, you can
+modify the ratings value on the database.
+
+```bash
+  # ...
+```

_docs/guides/intelligent-routing.md

@@ -43,7 +43,7 @@ for a running application.
    as the test user, we will notice that the v2 version of the `reviews` service has a bug.
    Note that all other users are unaware of this testing against the live system.
 
-1. [Traffic Shifting]({{home}}/docs/tasks/traffic-management/version-migration.html) Finally, we will
+1. [Traffic Shifting]({{home}}/docs/tasks/traffic-management/traffic-shifting.html) Finally, we will
    use Istio to gradually migrate traffic for all users from to a v3 version of
    the `reviews` service, one which includes the fix for the bug discovered in v2.
 

_docs/guides/policy-enforcement.md

@@ -11,16 +11,18 @@ type: markdown
 
 This sample uses the Bookinfo application to demonstrate policy enforcement using Istio Mixer.
 
+## Overview
+
+Provide a high level overview of what users can expect to learn, why these
+features are important, and so on. This is not a task, but a feature of
+Istio.
+
 ## Before you begin
 * Describe installation options.
 
 * Install Istio control plane in a Kubernetes cluster by following the quick start instructions in the
 [Installation guide]({{home}}/docs/setup/kubernetes/quick-start.html).
 
-## Overview
-
-Placeholder.
-
 ## Application Setup
 
 1. Steps

_docs/guides/sample.md.template

@@ -1,25 +0,0 @@
-// Before use, remove this line and uncomment the next line
-// ---
-title: My Sample
-overview: My overview
-
-order: 42
-
-layout: docs
-type: markdown
----
-
-Provide a simple one sentence overview of this page's content.
-
-## Before you begin
-
-List action prerequisites and knowledge prerequisites.
-
-## <Your Topic Headlines>
-
-<Your Topic Content>
-
-## What's next
-
-It's good to close with a 'what's next' section to point people to
-other related material.

_docs/guides/security.md

@@ -11,16 +11,16 @@ type: markdown
 
 This sample demonstrates how to obtain uniform metrics, logs, traces across different services using Istio Mixer and Istio sidecar.
 
+## Overview
+
+Placeholder.
+
 ## Before you begin
 * Describe installation options.
 
 * Install Istio control plane in a Kubernetes cluster by following the quick start instructions in the
 [Installation guide]({{home}}/docs/setup/kubernetes/quick-start.html).
 
-## Overview
-
-Placeholder.
-
 ## Application Setup
 
 1. Steps

_docs/guides/telemetry.md

@@ -36,18 +36,21 @@ developers to manually instrument their applications.
    This task will configure Mixer to collect a uniform set of metrics
    across all services in the Bookinfo application.
 
-1. [Querying metrics]({{home}}/docs/tasks/telemetry/querying-metrics.html) This task installs the Prometheus add-on for metrics collection and demonstrates querying a configured Prometheus server for Istio metrics.
+1. [Querying metrics]({{home}}/docs/tasks/telemetry/querying-metrics.html)
+   This task installs the Prometheus add-on for metrics collection and
+   demonstrates querying a configured Prometheus server for Istio metrics.
 
-1. [Using the Istio Dashboard]({{home}}/docs/tasks/telemetry/using-istio-dashboard.html) This task installs the Grafana add-on with a pre-configured dashboard for monitoring mesh traffic.
+1. [Distributed tracing]({{home}}/docs/tasks/telemetry/distributed-tracing.html)
+   We will now use Istio to trace how requests are flowing across services
+   in the application. Distributed tracing speeds up troubleshooting by
+   allowing developers to quickly understand how different services
+   contribute to the overall end-user perceived latency. In addition, it
+   can be a valuable tool to diagnosis and troubleshooting in distributed
+   applications.
 
-1. [Generating a Service Graph]({{home}}/docs/tasks/telemetry/servicegraph.html) This task generates a graph of service connections based on observed mesh traffic using the Servicegraph add-on.
+1. [Using the Istio Dashboard]({{home}}/docs/tasks/telemetry/using-istio-dashboard.html)
-
+   This task installs the Grafana add-on with a pre-configured dashboard
-1. [Request tracing]({{home}}/docs/tasks/telemetry/distributed-tracing.html) We will now use Istio to
+   for monitoring mesh traffic.
-   trace how requests are flowing across services in the
-   application. Distributed tracing speeds up troubleshooting by allowing
-   developers to quickly understand how different services contribute to
-   the overall end-user perceived latency. In addition, it can be a
-   valuable tool to diagnosis and troubleshooting in distributed applications.
 
 ## Cleanup
 

_docs/setup/consul/quick-start.md

@@ -51,7 +51,7 @@ Quick Start instructions to install and configure Istio in a Docker Compose setu
 1. Bring up the Istio control plane containers:
 
     ```bash
-    docker-compose -f samples/bookinfo/consul/control-plane.yaml up -d
+    docker-compose -f install/consul/istio.yaml up -d
     ```
 
 1. Confirm that all docker containers are running:
@@ -85,7 +85,7 @@ docker-compose -f <your-app-spec>.yaml up -d)
 1. Uninstall Istio core components by removing the docker containers:
 
 ```bash
-docker-compose -f samples/bookinfo/consul/control-plane.yaml down
+docker-compose -f install/consul/istio.yaml down
 ```
 
 ## What's next

_docs/setup/index.md

@@ -7,7 +7,6 @@ order: 15
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/installing-istio.html"
 ---
 
 {% include section-index.html %}

_docs/setup/kubernetes/automatic-sidecar-inject.md

@@ -1,5 +1,5 @@
 ---
-title: Automatic sidecar injection
+title: Automatic Sidecar Injection
 overview: Instructions for installing the Istio initializer in Kubernetes to automatically inject the Istio sidecar into pods.
 
 order: 50

_docs/setup/kubernetes/mesh-expansion.md

@@ -1,6 +1,6 @@
 ---
-title: Mesh Expansion
+title: Adding VMs to the Mesh
-overview: Instructions to add external machines and expand the Istio mesh.
+overview: Instructions for integrating VMs and bare metal hosts into an Istio mesh deployed on Kubernetes.
 
 order: 60
 
@@ -8,8 +8,8 @@ layout: docs
 type: markdown
 ---
 
-Instructions to configure Istio on a Kubernetes cluster so it can be expanded with
+Instructions for integrating VMs and bare metal hosts into an Istio mesh
-services running on cloud, on-premises VMs, or external machines.
+deployed on Kubernetes.
 
 ## Prerequisites
 

_docs/tasks/policy-enforcement/rate-limiting.md

@@ -6,7 +6,6 @@ order: 10
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/rate-limiting.html"
 ---
 {% include home.html %}
 
@@ -192,14 +191,14 @@ selected by matching only three out of four quota dimensions.
   istioctl delete -f samples/bookinfo/kube/route-rule-reviews-v3.yaml
   ```
 
-## What's next
+* If you are not planning to explore any follow-on tasks, refer to the
+  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
+  to shutdown the application.
+
+## Further reading
 
 * Learn more about [Mixer]({{home}}/docs/concepts/policy-and-control/mixer.html) and [Mixer Config]({{home}}/docs/concepts/policy-and-control/mixer-config.html).
 
 * Discover the full [Attribute Vocabulary]({{home}}/docs/reference/config/mixer/attribute-vocabulary.html).
 
 * Read the reference guide to [Writing Config]({{home}}/docs/reference/writing-config.html).
-
-* If you are not planning to explore any follow-on tasks, refer to the
-  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
-  to shutdown the application and cleanup the associated rules.

_docs/tasks/security/basic-access-control.md

@@ -1,12 +1,11 @@
 ---
-title: Enabling Simple Access Control
+title: Setup Basic Access Control
 overview: This task shows how to use Istio to control access to a service.
           
 order: 20
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/basic-access-control.html"
 ---
 {% include home.html %}
 
@@ -14,8 +13,8 @@ This task shows how to use Istio to control access to a service.
 
 ## Before you begin
 
-* Setup Istio by following the instructions in the
+* Setup Istio on Kubernetes by following the instructions in the
-  [Installation guide]({{home}}/docs/setup/kubernetes/quick-start.html).
+  [Installation guide]({{home}}/docs/setup/kubernetes/).
 
 * Deploy the [BookInfo]({{home}}/docs/guides/bookinfo.html) sample application.
 
@@ -170,10 +169,18 @@ Istio also supports attribute-based whitelists and blacklists.
   istioctl delete -f samples/bookinfo/kube/route-rule-reviews-v3.yaml
   ```
 
-## What's next
+* If you are not planning to explore any follow-on tasks, refer to the
+  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
+  to shutdown the application.
+
+## Further reading
 
 * Learn more about [Mixer]({{home}}/docs/concepts/policy-and-control/mixer.html) and [Mixer Config]({{home}}/docs/concepts/policy-and-control/mixer-config.html).
 
 * Discover the full [Attribute Vocabulary]({{home}}/docs/reference/config/mixer/attribute-vocabulary.html).
 
 * Read the reference guide to [Writing Config]({{home}}/docs/reference/writing-config.html).
+
+* Understand the differences between Kubernetes network policies and Istio
+  access control policies from this
+  [blog]({{home}}/blog/using-network-policy-in-concert-with-istio.html).

_docs/tasks/security/faq.md

@@ -9,20 +9,20 @@ type: markdown
 ---
 {% include home.html %}
 
-* Can a service with Istio Auth enabled communicate with a service without
+* _Can a service with Istio Auth enabled communicate with a service without
-  Istio?
+  Istio?_
 
   Currently it is not well supported. But we do have plan to support this
   in the near future.
 
-* Can I enable Istio Auth with some services while disable others in the
+* _Can I enable Istio Auth with some services while disable others in the
-  same cluster?
+  same cluster?_
 
   Currently we only support cluster-wise Auth enable/disable. It is a high
   priority action item for us to support per-service auth.
 
-* How can I use Kubernetes liveness and readiness for service health check
+* _How can I use Kubernetes liveness and readiness for service health check
-  with Istio Auth enabled?
+  with Istio Auth enabled?_
 
   If Istio Auth is enabled, http and tcp health check from kubelet will not
   work since they do not have Istio Auth issued certs. A workaround is to
@@ -30,7 +30,7 @@ type: markdown
   service pod and curl itself within the pod. The Istio team is actively
   working on a real solution.
 
-* Can I access the Kubernetes API Server with Auth enabled?
+* _Can I access the Kubernetes API Server with Auth enabled?_
 
   The Kubernetes API server does not support mutual TLS
   authentication. Hence, when Istio mTLS authentication is enabled, it is

_docs/tasks/security/istio-auth.md

@@ -1,12 +1,11 @@
 ---
-title: Testing Istio Auth
+title: Testing mTLS authentication
 overview: This task shows you how to verify and test Istio-Auth.
 
 order: 10
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/istio-auth.html"
 ---
 {% include home.html %}
 
@@ -116,3 +115,9 @@ server identity. As a result, we use curl option '-k' to prevent the curl client
 in server's (i.e., productpage) certificate. 
 Please check secure naming [here]({{home}}/docs/concepts/network-and-auth/auth.html#workflow) for more information
 about how the client verifies the server's identity in Istio.
+
+## Further reading
+
+* Learn more about the design principles behind Istio's automatic mTLS authentication
+  between all services in this
+  [blog]({{home}}/blog/istio-auth-for-microservices.html).

_docs/tasks/telemetry/distributed-tracing.md

@@ -2,11 +2,10 @@
 title: Distributed Tracing
 overview: How to configure the proxies to send tracing requests to Zipkin or Jaeger
 
-order: 20
+order: 10
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/distributed-tracing.html"
 ---
 {% include home.html %}
 
@@ -158,10 +157,12 @@ The reviews application (Java) does something similar:
 
 When you make downstream calls in your applications, make sure to include these headers.
 
-## What's next
+## Cleanup
-
-* Learn more about [Metrics and Logs]({{home}}/docs/tasks/metrics-logs.html)
 
 * If you are not planning to explore any follow-on tasks, refer to the
   [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
-  to shutdown the application and cleanup the associated rules.
+  to shutdown the application.
+
+## Further reading
+
+* Learn more about [Metrics and Logs]({{home}}/docs/tasks/telemetry/metrics-logs.html)

_docs/tasks/telemetry/metrics-logs.md

@@ -3,11 +3,10 @@ title: Collecting Metrics and Logs
 
 overview: This task shows you how to configure Istio to collect metrics and logs.
 
-order: 10
+order: 20
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/metrics-logs.html"
 ---
 {% include home.html %}
 
@@ -296,13 +295,17 @@ here to illustrate how to use `match` expressions to control rule execution.
 
 ## Cleanup
 
-Remove the new telemetry configuration:
+* Remove the new telemetry configuration:
 
-```bash
+  ```bash
-istioctl delete -f new_telemetry.yaml
+  istioctl delete -f new_telemetry.yaml
-```
+  ```
 
-## What's next
+* If you are not planning to explore any follow-on tasks, refer to the
+  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
+  to shutdown the application.
+
+## Further reading
 
 * Learn more about [Mixer]({{home}}/docs/concepts/policy-and-control/mixer.html)
   and [Mixer
@@ -314,11 +317,4 @@ istioctl delete -f new_telemetry.yaml
 * Read the reference guide to [Writing
   Config]({{home}}/docs/reference/writing-config.html).
 
-* Try out the related telemetry tasks:
+* Refer to the [In-Depth Telemetry]({{home}}/docs/guides/telemetry.html) guide.
-  - [Querying Istio Metrics]({{home}}/docs/tasks/telemetry/querying-metrics.html)
-  - [Using the Istio Dashboard]({{home}}/docs/tasks/telemetry/using-istio-dashboard.html)
-  - [Generating an Istio Service Graph]({{home}}/docs/tasks/telemetry/servicegraph.html)
-
-* If you are not planning to explore any follow-on tasks, refer to the [BookInfo
-  cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions to shutdown
-  the application and cleanup the associated rules.

_docs/tasks/telemetry/querying-metrics.md

@@ -1,9 +1,9 @@
 ---
-title: Querying Istio Metrics
+title: Querying Metrics from Prometheus
 
 overview: This task shows you how to query for Istio Metrics using Prometheus.
 
-order: 15
+order: 30
 
 layout: docs
 type: markdown
@@ -121,17 +121,17 @@ docs](https://prometheus.io/docs/querying/basics/).
 
 ## Cleanup
 
-In Kubernetes environments, execute the following command to remove the
+* In Kubernetes environments, execute the following command to remove the
-Prometheus add-on:
+  Prometheus add-on:
 
-```bash
+  ```bash
-kubectl delete -f install/kubernetes/addons/prometheus.yaml
+  kubectl delete -f install/kubernetes/addons/prometheus.yaml
-```
+  ```
 
-## What's next
+* If you are not planning to explore any follow-on tasks, refer to the
+  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
+  to shutdown the application.
 
-* Try out the related telemetry tasks:
+## Further reading
-  - [Using the Istio
+
-    Dashboard]({{home}}/docs/tasks/telemetry/using-istio-dashboard.html)
+* Refer to the [In-Depth Telemetry]({{home}}/docs/guides/telemetry.html) guide.
-  - [Generating an Istio Service
-    Graph]({{home}}/docs/tasks/telemetry/servicegraph.html)

_docs/tasks/telemetry/servicegraph.md

@@ -1,9 +1,9 @@
 ---
-title: Generating an Istio Service Graph
+title: Generating a Service Graph
 
 overview: This task shows you how to generate a graph of services within an Istio mesh.
 
-order: 25
+order: 50
 
 layout: docs
 type: markdown
@@ -106,9 +106,13 @@ The Servicegraph example is built on top of Prometheus queries.
 
 ## Cleanup
 
-In Kubernetes environments, execute the following command to remove the
+* In Kubernetes environments, execute the following command to remove the
-ServiceGraph add-on:
+  ServiceGraph add-on:
 
-```bash
+  ```bash
-kubectl delete -f install/kubernetes/addons/servicegraph.yaml
+  kubectl delete -f install/kubernetes/addons/servicegraph.yaml
-```
+  ```
+
+* If you are not planning to explore any follow-on tasks, refer to the
+  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
+  to shutdown the application.

_docs/tasks/telemetry/using-istio-dashboard.md

@@ -1,9 +1,9 @@
 ---
-title: Using the Istio Dashboard
+title: Visualizing Metrics with Grafana
 
 overview: This task shows you how to setup and use the Istio Dashboard to monitor mesh traffic.
 
-order: 18
+order: 40
 
 layout: docs
 type: markdown
@@ -114,9 +114,13 @@ For more on how to create, configure, and edit dashboards, please see the
 
 ## Cleanup
 
-In Kubernetes environments, execute the following command to remove the Grafana
+* In Kubernetes environments, execute the following command to remove the Grafana
-add-on:
+  add-on:
 
-```bash
+  ```bash
-kubectl delete -f install/kubernetes/addons/grafana.yaml
+  kubectl delete -f install/kubernetes/addons/grafana.yaml
-```
+  ```
+
+* If you are not planning to explore any follow-on tasks, refer to the
+  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
+  to shutdown the application.

_docs/tasks/traffic-management/egress.md

@@ -1,12 +1,11 @@
 ---
-title: Enabling Egress Traffic
+title: Control Egress Traffic
 overview: Describes how to configure Istio to route traffic from services in the mesh to external services.
 
 order: 40
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/egress.html"
 ---
 {% include home.html %}
 
@@ -248,9 +247,11 @@ cloud provider specific knowledge and configuration.
    kubectl delete -f samples/sleep/sleep.yaml
    ```
 
-
+## Further reading
-## What's next
 
 * Read more about [egress rules]({{home}}/docs/concepts/traffic-management/rules-configuration.html#egress-rules).
 
-* Learn how to use Istio's [request routing](./request-routing.html) features.
+* Learn how to setup
+  [timeouts]({{home}}/docs/reference/config/traffic-rules/routing-rules.html#httptimeout),
+  [retries]({{home}}/docs/reference/config/traffic-rules/routing-rules.html#httpretry),
+  and [circuit breakers]({{home}}/docs/reference/config/traffic-rules/destination-policies.html#circuitbreaker) for egress traffic.

_docs/tasks/traffic-management/faq.md

@@ -9,17 +9,17 @@ type: markdown
 ---
 {% include home.html %}
 
-* How can I view the current rules I have configured with Istio?
+* _How can I view the current rules I have configured with Istio?_
 
   Rules can be viewed using `istioctl get routerules -o yaml` or `kubectl get routerules -o yaml`.
 
-* I created a weighted Route Rule to split traffic between two versions of a service but I am not seeing
+* _I created a weighted Route Rule to split traffic between two versions of a service but I am not seeing
-  the expected behavior.
+  the expected behavior._
   
   For the current Envoy sidecar implementation, up to 100 requests may be required for the desired
   distribution to be observed.
   
-* How come some of my services are unreachable after creating Route Rules?
+* _How come some of my services are unreachable after creating Route Rules?_
  
   This is an known issue with the current Envoy sidecar implementation.  After two seconds of creating the 
   rule, services should become available.

_docs/tasks/traffic-management/fault-injection.md

@@ -6,7 +6,6 @@ order: 20
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/fault-injection.html"
 ---
 {% include home.html %}
 
@@ -25,12 +24,18 @@ This task shows how to inject delays and test the resiliency of your application
   
   > Note: This assumes you don't have any routes set yet. If you've already created conflicting route rules for the sample, you'll need to use `replace` rather than `create` in one or both of the following commands.
 
-
   ```bash
   istioctl create -f samples/bookinfo/kube/route-rule-all-v1.yaml
   istioctl create -f samples/bookinfo/kube/route-rule-reviews-test-v2.yaml
   ```
-  
+
+> Note: This task assumes you are deploying the application on Kubernetes.
+  All of the example commands are using the Kubernetes version of the rule yaml files
+  (e.g., `samples/bookinfo/kube/route-rule-all-v1.yaml`). If you are running this
+  task in a different environment, change `kube` to the directory that corresponds
+  to your runtime (e.g., `samples/bookinfo/consul/route-rule-all-v1.yaml` for
+  the Consul-based runtime).
+
 ## Fault injection
 
 To test our BookInfo application microservices for resiliency, we will _inject a 7s delay_
@@ -105,7 +110,8 @@ continue without any errors.
 
   However, we already have this fix running in v3 of the reviews service, so we can simply
   fix the problem by migrating all
-  traffic to `reviews:v3` as described in the [version migration](./version-migration.html).
+  traffic to `reviews:v3` as described in the
+  [traffic shifting]({{home}}/docs/tasks/traffic-management/traffic-shifting.html) task.
 
   (Left as an exercise for the reader - change the delay rule to
   use a 2.8 second delay and then run it against the v3 version of reviews.)
@@ -120,10 +126,10 @@ continue without any errors.
   istioctl delete -f samples/bookinfo/kube/route-rule-ratings-test-delay.yaml
   ```
 
-## What's next
-
-* Learn more about [fault injection]({{home}}/docs/concepts/traffic-management/fault-injection.html).
-
 * If you are not planning to explore any follow-on tasks, refer to the
   [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
-  to shutdown the application and cleanup the associated rules.
+  to shutdown the application.
+
+## Further reading
+
+* Learn more about [fault injection]({{home}}/docs/concepts/traffic-management/fault-injection.html).

_docs/tasks/traffic-management/ingress.md

@@ -1,12 +1,11 @@
 ---
-title: Enabling Ingress Traffic
+title: Istio Ingress Controller
-overview: Describes how to configure Istio to expose a service outside of the service mesh.
+overview: Describes how to configure the Istio ingress controller on Kubernetes.
 
 order: 30
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/ingress.html"
 ---
 
 This task describes how to configure Istio to expose a service outside of the service mesh cluster.
@@ -320,8 +319,8 @@ We also showed how to control the ingress traffic using an Istio route rule.
    ```
 
 
-## What's next
+## Further reading
+
+* Learn more about [Ingress Resources](https://kubernetes.io/docs/concepts/services-networking/ingress/).
 
 * Learn more about [routing rules]({{home}}/docs/concepts/traffic-management/rules-configuration.html).
-
-* Learn how to expose external services by [enabling egress traffic](./egress.html).

_docs/tasks/traffic-management/request-routing.md

@@ -6,7 +6,6 @@ order: 10
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/request-routing.html"
 ---
 {% include home.html %}
 
@@ -23,7 +22,7 @@ This task shows you how to configure dynamic request routing based on weights an
   All of the example commands are using the Kubernetes version of the rule yaml files
   (e.g., `samples/bookinfo/kube/route-rule-all-v1.yaml`). If you are running this
   task in a different environment, change `kube` to the directory that corresponds
-  to your runtime (e.g., samples/bookinfo/consul/route-rule-all-v1.yaml for
+  to your runtime (e.g., `samples/bookinfo/consul/route-rule-all-v1.yaml` for
   the Consul-based runtime).
 
 ## Content-based routing
@@ -173,26 +172,15 @@ all users to v2, optionally in a gradual fashion. We'll explore this in a separa
 
 * Remove the application routing rules.
 
-  For Kubernetes-based setup, use the following command:
-
   ```bash
   istioctl delete -f samples/bookinfo/kube/route-rule-all-v1.yaml
   istioctl delete -f samples/bookinfo/kube/route-rule-reviews-test-v2.yaml
   ```
 
-  For Consul-based setup, use the following command:
-
-  ```bash
-  istioctl delete -f samples/bookinfo/consul/route-rule-all-v1.yaml
-  istioctl delete -f samples/bookinfo/consul/route-rule-reviews-test-v2.yaml
-  ```
-
-## What's next
-
-* Learn more about [request routing]({{home}}/docs/concepts/traffic-management/rules-configuration.html).
-
-* Test the BookInfo application resiliency by [injecting faults](./fault-injection.html).
-
 * If you are not planning to explore any follow-on tasks, refer to the
   [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
-  to shutdown the application and cleanup the associated rules.
+  to shutdown the application.
+
+## Further reading
+
+* Learn more about [request routing]({{home}}/docs/concepts/traffic-management/rules-configuration.html).

_docs/tasks/traffic-management/request-timeouts.md

@@ -6,7 +6,6 @@ order: 50
 
 layout: docs
 type: markdown
-redirect_from: "/docs/tasks/request-timeouts.html"
 ---
 {% include home.html %}
 
@@ -22,12 +21,17 @@ This task shows you how to setup request timeouts in Envoy using Istio.
 
 * Initialize the application version routing by running the following command:
 
-> Note: This assumes you don't have any routes set yet. If you've already created route rules for the sample, you'll need to use `replace` rather than `create` in the following command.
-  
   ```bash
   istioctl create -f samples/bookinfo/kube/route-rule-all-v1.yaml
   ```
 
+> Note: This task assumes you are deploying the application on Kubernetes.
+  All of the example commands are using the Kubernetes version of the rule yaml files
+  (e.g., `samples/bookinfo/kube/route-rule-all-v1.yaml`). If you are running this
+  task in a different environment, change `kube` to the directory that corresponds
+  to your runtime (e.g., `samples/bookinfo/consul/route-rule-all-v1.yaml` for
+  the Consul-based runtime).
+
 ## Request timeouts
 
 A timeout for http requests can be specified using the *httpReqTimeout* field of a routing rule.
@@ -130,12 +134,20 @@ as you did in this task, they can also be overridden on a per-request basis if t
 an "x-envoy-upstream-rq-timeout-ms" header on outbound requests. In the header
 the timeout is specified in millisecond (instead of second) units. 
 
-## What's next
+## Cleanup
+
+* Remove the application routing rules.
+
+  ```bash
+  istioctl delete -f samples/bookinfo/kube/route-rule-all-v1.yaml
+  ```
+
+* If you are not planning to explore any follow-on tasks, refer to the
+  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
+  to shutdown the application.
+
+## Further reading
 
 * Learn more about [failure handling]({{home}}/docs/concepts/traffic-management/handling-failures.html).
 
 * Learn more about [routing rules]({{home}}/docs/concepts/traffic-management/rules-configuration.html).
-
-* If you are not planning to explore any follow-on tasks, refer to the
-  [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
-  to shutdown the application and cleanup the associated rules.

_docs/tasks/traffic-management/services-expansion.md

@@ -1,79 +0,0 @@
----
-title: Accessing Services in the Expanded Mesh
-overview: This task shows you how to use services provided by VM
-
-order: 60
-
-#draft: true
-layout: docs
-type: markdown
----
-{% include home.html %}
-
-This task shows you how to configure services running in a VM that joined the cluster.
-
-Current task was tested on GCP. _WIP on adding specific info for other providers_
-
-## Before you begin
-
-* Setup Istio by following the instructions in the
-  [Installation guide](({{home}}/docs/setup/).
-
-* Deploy the [BookInfo]({{home}}/docs/samples/bookinfo.html) sample application.
-
-* Create a VM named 'db' in the same project as Istio cluster, and [Join the Mesh]({{home}}/docs/setup/kubernetes/mesh-expansion.html).
-
-## Running mysql on the VM
-
-We will first install mysql on the VM, and configure it as a backend for the ratings service.
-
-On the VM:
-```bash
-  sudo apt-get update && apt-get install ...
-  # TODO copy or link the istio/istio test script
-```
-
-## Registering the mysql service with the mesh
-
-### Machine admin
-First step is to configure the VM sidecar, by adding the service port and restarting the sidecar.
-
-On the DB machine:
-```bash
-
-  sudo echo "ISTIO_INBOUND_PORTS=..." > /var/lib/istio/envoy/sidecar.env
-  sudo chown istio-proxy /var/lib/istio/envoy/sidecar.env
-  sudo systemctl restart istio
- # Or
-  db$ sudo istio-pilot vi /var/lib/istio/envoy/sidecar.env
-  # add mysql port to the "ISTIO_INBOUND_PORTS" config
-  ```
-
-###  Cluster admin
-
-  If you previously run the mysql bookinfo on kubernetes, you need to remove the k8s mysql service:
-
-  ```bash
-  kubectl delete service mysql
-  ```
-
-  Run istioctl to configure the service (on your admin machine):
-
-  ```bash
-  istioctl register mysql PORT IP
-  ```
-
-  Note that the 'db' machine does not need and should not have special kubernetes priviledges.
-
-## Registering the mongodb service with the Mesh
-
- In progress...
-
-## Using the mysql service
-
-The ratings service in bookinfo will use the DB on the machine. To verify it works, you can
-modify the ratings value on the database.
-
-```bash
-  # ...
-```

_docs/tasks/traffic-management/traffic-shifting.md

@@ -2,7 +2,7 @@
 title: Traffic Shifting
 overview: This task shows you how to migrate traffic from an old to new version of a service.
 
-order: 10
+order: 25
 
 layout: docs
 type: markdown
@@ -26,7 +26,7 @@ two steps: 50%, 100%.
   All of the example commands are using the Kubernetes version of the rule yaml files
   (e.g., `samples/bookinfo/kube/route-rule-all-v1.yaml`). If you are running this
   task in a different environment, change `kube` to the directory that corresponds
-  to your runtime (e.g., samples/bookinfo/consul/route-rule-all-v1.yaml for
+  to your runtime (e.g., `samples/bookinfo/consul/route-rule-all-v1.yaml` for
   the Consul-based runtime).
 
 ## Weight-based version routing
@@ -80,11 +80,18 @@ With Istio, we can allow the two versions of the `reviews` service to scale up a
 without affecting the traffic distribution between them.
 For more about version routing with autoscaling, check out [Canary Deployments using Istio]({{home}}/blog/canary-deployments-using-istio.html).
 
+## Cleanup
 
-## What's next
+* Remove the application routing rules.
 
-* Learn more about [request routing]({{home}}/docs/concepts/traffic-management/rules-configuration.html).
+  ```bash
+  istioctl delete -f samples/bookinfo/kube/route-rule-all-v1.yaml
+  ```
 
 * If you are not planning to explore any follow-on tasks, refer to the
   [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
-  to shutdown the application and cleanup the associated rules.
+  to shutdown the application.
+
+## Further reading
+
+* Learn more about [request routing]({{home}}/docs/concepts/traffic-management/rules-configuration.html).