Plugging in external CA key and certificate

This task shows how operators can configure Citadel with existing root certificate, signing certificate and key.

By default, Citadel generates self-signed root certificate and key, and uses them to sign the workload certificates. Citadel can also use the operator-specified certificate and key to sign workload certificates, with operator-specified root certificate. This task demonstrates an example to plug certificates and key into Citadel.

Before you begin

• Set up Istio by following the instructions in the quick start with global mutual TLS enabled by using Helm with global.mtls.enabled set to true.

Starting with Istio 0.7, you can use authentication policy to configure mutual TLS for all/selected services in a namespace (repeated for all namespaces to get global setting). See authentication policy task

Plugging in the existing certificate and key

Suppose we want to have Citadel use the existing signing (CA) certificate ca-cert.pem and key ca-key.pem. Furthermore, the certificate ca-cert.pem is signed by the root certificate root-cert.pem. We would like to use root-cert.pem as the root certificate for Istio workloads.

In the following example, Citadel's signing (CA) certificate (ca-cert.pem) is different from root certificate (root-cert.pem), so 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 our example, it contains Citadel's signing 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, the cert-chain.pem file should be empty.

These files are ready to use in the samples/certs/ directory.

The following steps enable plugging in the certificates and key into Citadel:

1. Create a secret cacert including all the input files ca-cert.pem, ca-key.pem, root-cert.pem and cert-chain.pem:

   $ kubectl create secret generic cacerts -n istio-system --from-file=samples/certs/ca-cert.pem \
       --from-file=samples/certs/ca-key.pem --from-file=samples/certs/root-cert.pem \
       --from-file=samples/certs/cert-chain.pem

2. Redeploy Citadel, which reads the certificates and key from the secret-mount files by using Helm with global.mtls.enabled set to true and security.selfSigned to false.

3. To make sure the workloads obtain the new certificates promptly, delete the secrets generated by Citadel (named as istio.*). In this example, istio.default. Citadel will issue new certificates for the workloads.

   $ kubectl delete secret istio.default

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.

2. Retrieve the mounted certificates. In the following, we take the ratings pod as an example, and verify the certificates mounted on the pod.

   Set the pod name to RATINGSPOD:

   $ RATINGSPOD=`kubectl get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'`

   Run the following commands to retrieve the certificates mounted on the proxy:

   $ kubectl exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/root-cert.pem > /tmp/pod-root-cert.pem

   The file /tmp/pod-root-cert.pem contains the root certificate propagated to the pod.

   $ kubectl exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem

   The file /tmp/pod-cert-chain.pem contains the workload certificate and the CA certificate propagated to the pod.

3. Verify the root certificate is the same as the one specified by operator:

   $ openssl x509 -in @samples/certs/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

   Expect the output to be empty.

4. Verify the CA certificate is the same as the one specified by operator:

   $ tail -n 22 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-ca.pem
   $ openssl x509 -in @samples/certs/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 the output to be empty.

5. Verify the certificate chain from the root certificate to the workload certificate:

   $ head -n 21 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-workload.pem
   $ openssl verify -CAfile <(cat @samples/certs/ca-cert.pem@ @samples/certs/root-cert.pem@) /tmp/pod-cert-chain-workload.pem
   /tmp/pod-cert-chain-workload.pem: OK

Cleanup

• To remove the secret cacerts:

  $ kubectl delete secret cacerts -n istio-system

• To remove the Istio components:

  $ kubectl delete -f install/kubernetes/istio-demo-auth.yaml

See also