mirror of https://github.com/istio/istio.io.git
Add task on plugging existing key/cert into Istio CA (#695)
* Add task on plugging existing key/cert into Istio CA * Small fixes. * Small fix. * Add verification steps.
This commit is contained in:
Oliver Liu
Laurent Demailly
parent
e0d4759e24
commit
4a2931459f
|
|
@ -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).
|
||||||
Loading…
Reference in New Issue