From 6e3acad482e11e524a06a80ed62a96b9d5911046 Mon Sep 17 00:00:00 2001
From: Tao Li <taotao12@gmail.com>
Date: Fri, 12 Oct 2018 11:01:29 -0700
Subject: [PATCH] Revise the description of istio-demo (#2743)

---
 content/docs/concepts/security/index.md       | 24 +++++++++++++++++++
 .../setup/kubernetes/quick-start/index.md     | 13 +++++++---
 2 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/content/docs/concepts/security/index.md b/content/docs/concepts/security/index.md
index a0a950c991..bd8ac258b2 100644
--- a/content/docs/concepts/security/index.md
+++ b/content/docs/concepts/security/index.md
@@ -251,6 +251,30 @@ For a client to call a server with mutual TLS authentication:
 
 1. After authorization, the server side Envoy forwards the traffic to the server service through local TCP connections.
 
+#### Permissive mode
+
+Istio mutual TLS has a permissive mode, which allows a service to accept
+both plain text traffic and mutual TLS traffic at the same time. This
+feature greatly improves the mutual TLS onboarding experience.
+
+Many non-Istio clients communicating with a non-Istio server presents a
+problem for an operator who wants to migrate that server to Istio with
+mutual TLS enabled. Commonly, the operator cannot install an Istio sidecar
+for all clients at the same time or does not even have the permissions to
+do so on some clients. Even after installing the Istio sidecar on the
+server, the operator cannot enable mutual TLS without breaking existing
+communications.
+
+With the permissive mode enabled, the server accepts both plain text and
+mutual TLS traffic. The mode provides great flexibility for the
+on-boarding process. The server's installed Istio sidecar takes mutual TLS
+traffic immediately without breaking existing plain text traffic. As a
+result, the operator can gradually install and configure the client's
+Istio sidecars to send mutual TLS traffic. Once the configuration of the
+clients is complete, the operator can configure the server to mutual TLS
+only mode. For more information, visit the
+[Mutual TLS Migration tutorial](/docs/tasks/security/mtls-migration).
+
 #### Secure naming
 
 The secure naming information contains *N-to-N* mappings from the server identities, which are encoded in certificates,
diff --git a/content/docs/setup/kubernetes/quick-start/index.md b/content/docs/setup/kubernetes/quick-start/index.md
index 01884f77d4..df10676d2f 100644
--- a/content/docs/setup/kubernetes/quick-start/index.md
+++ b/content/docs/setup/kubernetes/quick-start/index.md
@@ -38,10 +38,10 @@ we recommend installing with the
 [Helm Chart](/docs/setup/kubernetes/helm-install/), to use all the
 configuration options. This permits customization of Istio to operator specific requirements.
 
-### Option 1: Install Istio without mutual TLS authentication between sidecars
+### Option 1: Install Istio with mutual TLS enabled and set to use permissive mode between sidecars
 
 Visit our
-[mutual TLS authentication between sidecars concept page](/docs/concepts/security/#mutual-tls-authentication)
+[mutual TLS permissive mode page](/docs/concepts/security/#permissive-mode)
 for more information.
 
 Choose this option for:
@@ -54,12 +54,19 @@ Choose this option for:
 * Headless services, or
 * `StatefulSets`
 
-To install Istio without mutual TLS authentication between sidecars:
+To install Istio with mutual TLS enabled and set to use permissive mode
+between sidecars:
 
 {{< text bash >}}
 $ kubectl apply -f install/kubernetes/istio-demo.yaml
 {{< /text >}}
 
+In this option, all services, as servers, can accept both plain text and
+mutual TLS traffic. However, all services, as clients, will send plain
+text traffic.
+Visit [mutual migration](/docs/tasks/security/mtls-migration/#configure-clients-to-send-mutual-tls-traffic)
+for how to configure clients behavior.
+
 ### Option 2: Install Istio with default mutual TLS authentication
 
 Use this option only on a fresh Kubernetes cluster where newly deployed