documentation for enable/use SDS in 1.1 (#3090)

* documentation for SDS in 1.1 release

* lint

* address comments

* address comments

* address comments

* grammer

content/docs/concepts/security/index.md

@@ -135,10 +135,10 @@ Currently we use different certificate key provisioning mechanisms for each scen
 
 1. The above CSR process repeats periodically for certificate and key rotation.
 
-### Node Agent in Kubernetes (in development)
+### Node Agent in Kubernetes
 
-In the near future, Istio will use node agent in Kubernetes for certificate and key provision, as shown in the figure below.
-Note that the identity provision flow for on-premises machines is the same so we only describe the Kubernetes scenario.
+Istio provides the option of using node agent in Kubernetes for certificate and key provisioning, as shown in the figure below.
+Note that the identity provisioning flow for on-premises machines will be similar in the near future, we only describe the Kubernetes scenario here.
 
 {{< image width="80%" link="./node_agent.svg" caption="PKI with node agents in Kubernetes"  >}}
 

content/docs/tasks/security/auth-sds/index.md

@@ -0,0 +1,82 @@
+---
+title: Provisioning Identity through SDS
+description: Shows how to enable SDS (secret discovery service) for Istio identity provisioning.
+weight: 70
+keywords: [security,auth-sds]
+---
+
+This task shows how to enable [SDS (secret discovery service)](https://www.envoyproxy.io/docs/envoy/latest/configuration/secret#config-secret-discovery-service) for Istio identity provisioning.
+
+Prior to Istio 1.1, the keys and certificates of Istio workloads were generated by Citadel and distributed to sidecars
+through secret-mount files, this approach has the following side effects:
+* Traffic interruption:
+  When certificate rotation happens, Envoy (Pilot agent) needs to restart to pick up key/certificate update,
+  which causes traffic interruption.
+* Potential security issue:
+  Since key/certificate are file-mounted to sidecars, hackers could remote to sidecar container and steal key/certificate content.
+
+These issues are addressed in Istio 1.1 through the support of SDS to provision identities.
+
+Workload requests key/certificate from SDS server(node agent, which runs as per-node daemon set) using k8s service account JWT through
+the SDS API, node agent generates private key and send CSR request to Citadel, Citadel verifies the JWT and signs the certificate,
+the key/certificate will eventually be sent back to workload sidecar through SDS server(node agent).
+Since key/certificate which are generated through SDS are stored in workload sidecar's memory, it's more secure than file mount;
+also the workload doesn't need to restart to pick up the certificate change when rotation happens.
+
+## Before you begin
+
+* Set up Istio by following the instructions using [Helm](/docs/setup/kubernetes/helm-install/) with SDS setup and global mutual TLS enabled:
+
+    {{< text bash >}}
+    $ cat install/kubernetes/namespace.yaml > istio-auth-sds.yaml
+    $ cat install/kubernetes/helm/istio-init/files/crd-* >> istio-auth-sds.yaml
+    $ helm dep update --skip-refresh install/kubernetes/helm/istio
+    $ helm template install/kubernetes/helm/istio --name istio --namespace istio-system --values install/kubernetes/helm/istio/values-istio-sds-auth.yaml >> istio-auth-sds.yaml
+    $ kubectl create -f istio-auth-sds.yaml
+    {{< /text >}}
+
+## Service-to-service mutual TLS using key/certificate provisioned through SDS
+
+Follow the [authentication policy task](/docs/tasks/security/authn-policy/) to setup test services.
+
+{{< text bash >}}
+$ kubectl create ns foo
+$ kubectl apply -f <(istioctl kube-inject -f samples/httpbin/httpbin.yaml) -n foo
+$ kubectl apply -f <(istioctl kube-inject -f samples/sleep/sleep.yaml) -n foo
+$ ubectl create ns bar
+$ kubectl apply -f <(istioctl kube-inject -f samples/httpbin/httpbin.yaml) -n bar
+$ kubectl apply -f <(istioctl kube-inject -f samples/sleep/sleep.yaml) -n bar
+{{< /text >}}
+
+Verify all mutual TLS requests succeed:
+
+{{< text bash >}}
+$ for from in "foo" "bar"; do for to in "foo" "bar"; do kubectl exec $(kubectl get pod -l app=sleep -n ${from} -o jsonpath={.items..metadata.name}) -c sleep -n ${from} -- curl "http://httpbin.${to}:8000/ip" -s -o /dev/null -w "sleep.${from} to httpbin.${to}: %{http_code}\n"; done; done
+sleep.foo to httpbin.foo: 200
+sleep.foo to httpbin.bar: 200
+sleep.bar to httpbin.foo: 200
+sleep.bar to httpbin.bar: 200
+{{< /text >}}
+
+## Verifying no secret-mount file is generated
+
+As mentioned, instead of using secret-mount file, key/certificate provisioned by SDS flow are stored in workload sidecar's memory,
+which is more secure and avoids traffic interruption.
+
+Verify no secret-mount file is generated by remotely accessing to workload sidecar container that we just deployed:
+
+{{< text bash >}}
+$ kubectl exec -it $(kubectl get pod -l app=sleep -n foo -o jsonpath={.items..metadata.name}) -c istio-proxy -n foo  -- /bin/bash
+{{< /text >}}
+
+As you can see there is no secret file mounted at `/etc/certs` folder.
+
+## Cleanup
+
+Clean up test services and Istio control plane:
+
+{{< text bash >}}
+$ kubectl delete ns foo
+$ kubectl delete ns bar
+$ kubectl delete -f istio-auth-sds.yaml
+{{< /text >}}