Add task on plugging existing key/cert into Istio CA

_docs/tasks/security/plugin-ca-cert.md

@@ -0,0 +1,147 @@
+---
+title: Plugging in CA certificate and key
+overview: This task shows how operators can plug existing certificate and key into Istio CA.
+
+order: 40
+
+layout: docs
+type: markdown
+---
+{% include home.html %}
+
+This task shows how operators can plug existing certificate and key into Istio CA.
+
+By default, the Istio CA generates self-signed CA certificate and key and uses them to sign the workload certificates.
+The Istio CA can also use the operator-specified certificate and key to sign workload certificates.
+This task demonstrates an example to plug certificate and key into the Istio CA.
+
+## Before you begin
+
+* Set up Istio on auth-enabled Kubernetes by following the instructions in the
+  [quick start]({{home}}/docs/setup/kubernetes/quick-start.html).
+  Note that authentication should be enabled at step 4 in the
+  [installation steps]({{home}}/docs/setup/kubernetes/quick-start.html#installation-steps).
+
+## Plugging in the existing certificate and key
+
+Suppose we want to have Istio CA use the existing certificate `ca-cert.pem` and key `ca-key.pem`.
+Furthermore, the certificate `ca-cert.pem` is signed by the root certificate `root-cert.pem`,
+and we would like to use `root-cert.pem` as the root certificate for Istio workloads.
+
+In this example, because the Istio CA certificate (`ca-cert.pem`) is not set as the workloads' root certificate (`root-cert.pem`),
+the workload cannot validate the workload certificates directly from the root certificate.
+The workload needs a `cert-chain.pem` file to specify the chain of trust,
+which should include the certificates of all the intermediate CAs between the workloads and the root CA.
+In this example, it only contains the Istio CA certificate, so `cert-chain.pem` is the same as `ca-cert.pem`.
+Note that if your `ca-cert.pem` is the same as `root-cert.pem`, you can have an empty `cert-chain.pem` file.
+
+Download the example files:
+```bash
+wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/samples/plugin_ca_certs/ca-cert.pem
+wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/samples/plugin_ca_certs/ca-key.pem
+wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/samples/plugin_ca_certs/root-cert.pem
+wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/samples/plugin_ca_certs/cert-chain.pem
+```
+
+The following steps enable plugging in the certificate and key into the Istio CA:
+1. Create a secret `cacert` including all the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`:
+   ```bash
+   kubectl create secret generic cacerts -n istio-system --from-file=/tmp/ca-cert.pem --from-file=/tmp/ca-key.pem \
+   --from-file=/tmp/root-cert.pem --from-file=/tmp/cert-chain.pem
+   ```
+
+1. Redeploy the Istio CA, which reads the certificates and key from the secret-mount files:
+   ```bash
+   kubectl apply -f install/kubernetes/istio-ca-plugin-certs.yaml
+   ```
+
+1. To make sure the workloads obtain the new certificates promptly,
+   delete the secrets generated by Istio CA (named as istio.\*).
+   In this example, `istio.default`. The Istio CA will issue new certificates for the workloads.
+   ```bash
+   kubectl delete secret istio.default
+   ```
+Note that if you are using different certificate/key file or secret names,
+you need to change corresponding arguments in `istio-ca-plugin-certs.yaml`.
+
+## Verifying the new certificates
+
+In this section, we verify that the new workload certificates and root certificates are propagated.
+This requires you have `openssl` installed on your machine.
+
+1. Deploy the bookinfo application following the [instructions]({{home}}/docs/guides/bookinfo.html).
+
+1. Retrieve the mounted certificates.
+
+   Get the pods:
+   ```bash
+   kubectl get pods
+   ```
+
+   which produces:
+   ```bash
+   NAME                                        READY     STATUS    RESTARTS   AGE
+   details-v1-1520924117-48z17                 2/2       Running   0          6m
+   productpage-v1-560495357-jk1lz              2/2       Running   0          6m
+   ratings-v1-734492171-rnr5l                  2/2       Running   0          6m
+   reviews-v1-874083890-f0qf0                  2/2       Running   0          6m
+   reviews-v2-1343845940-b34q5                 2/2       Running   0          6m
+   reviews-v3-1813607990-8ch52                 2/2       Running   0          6m
+   ```
+
+   In the following, we take the pod `ratings-v1-734492171-rnr5l` as an example, and verify the mounted certificates.
+   Run the following commands to retrieve the certificates mounted on the proxy:
+
+   ```bash
+   kubectl exec -it ratings-v1-734492171-rnr5l -c istio-proxy -- /bin/cat /etc/certs/root-cert.pem > /tmp/pod-root-cert.pem
+   ```
+   The file `/tmp/pod-root-cert.pem` should contain the root certificate specified by the operator.
+
+   ```bash
+   kubectl exec -it ratings-v1-734492171-rnr5l -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem
+   ```
+   The file `/tmp/pod-cert-chain.pem` should contain the workload certificate and the CA certificate.
+
+1. Verify the root certificate is the same as the one specified by operator:
+   ```bash
+   openssl x509 -in /tmp/root-cert.pem -text -noout > /tmp/root-cert.crt.txt
+   openssl x509 -in /tmp/pod-root-cert.pem -text -noout > /tmp/pod-root-cert.crt.txt
+   diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt
+   ```
+
+1. Verify that the CA certificate is the same as the one specified by operator:
+   ```bash
+   tail /tmp/pod-cert-chain.pem -n 22 > /tmp/pod-cert-chain-ca.pem
+   openssl x509 -in /tmp/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt
+   openssl x509 -in /tmp/pod-cert-chain-ca.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt
+   diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt
+   ```
+   Expect that the output to be empty.
+
+1. Verify the certificate chain from the root certificate to the workload certificate:
+   ```bash
+   head /tmp/pod-cert-chain.pem -n 18 > /tmp/pod-cert-chain-workload.pem
+   openssl verify -CAfile <(cat /tmp/ca-cert.pem /tmp/root-cert.pem) /tmp/pod-cert-chain-workload.pem
+   ```
+   Expect the following output:
+   ```bash
+   /tmp/pod-cert-chain-workload.pem: OK
+   ```
+
+## Cleanup
+
+* To remove the secret `cacerts`:
+
+  ```bash
+  kubectl delete secret cacerts -n istio-system
+  ```
+
+* To remove the Istio components:
+  ```bash
+  kubectl delete -f install/kubernetes/istio-auth.yaml
+  ```
+
+## Further reading
+
+* Read the [Istio CA arguments](https://github.com/istio/istio/blob/master/security/cmd/istio_ca/main.go).
+* Read [how the sample certificates and keys are generated](https://github.com/istio/istio/blob/master/security/samples/plugin_ca_certs).