mirror of https://github.com/istio/istio.io.git
145 lines
5.8 KiB
Markdown
145 lines
5.8 KiB
Markdown
---
|
|
title: Plugging in external CA key and certificate
|
|
description: Shows how operators can configure Citadel with existing root certificate, signing certificate and key.
|
|
weight: 60
|
|
---
|
|
|
|
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](/docs/setup/kubernetes/quick-start/).
|
|
Note that authentication should be enabled at step 5 in the
|
|
[installation steps](/docs/setup/kubernetes/quick-start/#installation-steps).
|
|
|
|
## 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`:
|
|
|
|
```command
|
|
$ 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
|
|
```
|
|
|
|
1. Redeploy Citadel, which reads the certificates and key from the secret-mount files:
|
|
|
|
```command
|
|
$ kubectl apply -f install/kubernetes/istio-citadel-plugin-certs.yaml
|
|
```
|
|
|
|
> Note: if you are using different certificate/key file or secret names,
|
|
you need to change corresponding volume mounts and arguments in `istio-citadel-plugin-certs.yaml`.
|
|
|
|
1. 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.
|
|
|
|
```command
|
|
$ 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](/docs/guides/bookinfo/).
|
|
|
|
1. 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`:
|
|
|
|
```command
|
|
$ 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:
|
|
|
|
```command
|
|
$ 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.
|
|
|
|
```command
|
|
$ 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.
|
|
|
|
1. Verify the root certificate is the same as the one specified by operator:
|
|
|
|
```command
|
|
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.
|
|
|
|
1. Verify the CA certificate is the same as the one specified by operator:
|
|
|
|
```command
|
|
$ 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.
|
|
|
|
1. Verify the certificate chain from the root certificate to the workload certificate:
|
|
|
|
```command
|
|
$ 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
|
|
```
|
|
|
|
Expect the following output:
|
|
|
|
```command
|
|
/tmp/pod-cert-chain-workload.pem: OK
|
|
```
|
|
|
|
## Cleanup
|
|
|
|
* To remove the secret `cacerts`:
|
|
|
|
```command
|
|
$ kubectl delete secret cacerts -n istio-system
|
|
```
|
|
|
|
* To remove the Istio components:
|
|
|
|
```command
|
|
$ kubectl delete -f install/kubernetes/istio-auth.yaml
|
|
```
|
|
|
|
## What's next
|
|
|
|
* Read more about [Citadel (codename is istio\_ca) arguments](/docs/reference/commands/istio_ca/).
|
|
* Read [how the sample certificates and keys are generated](https://github.com/istio/istio/blob/master/security/samples/plugin_ca_certs).
|