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