Skip to content

Commit 2c2e140

Browse files
sridhargaddamsridhargaddam
authored
Merge pull request openshift-service-mesh#138 from nrfox/document-istio-csr-integration
Add docs for istio-csr
2 parents 212b79f + dda37bc commit 2c2e140

File tree

2 files changed

+256
-1
lines changed

2 files changed

+256
-1
lines changed

‎docs/ossm/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,5 @@ This documentation is specific to the OpenShift Service Mesh product and may dif
66

77
# Table of Contents
88

9-
- [Running Red Hat OpenShift Service Mesh (OSSM) 2 and OSSM 3 side by side](./ossm-2-and-ossm-3-side-by-side/README.md)
9+
- [Running Red Hat OpenShift Service Mesh (OSSM) 2 and OSSM 3 side by side](./ossm-2-and-ossm-3-side-by-side/README.md)
10+
- [Cert Manager and istio-csr Integration](./cert-manager/README.md)

‎docs/ossm/cert-manager/README.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
[Return to OSSM Docs](../)
2+
3+
# About integrating Service Mesh with cert-manager and istio-csr
4+
5+
The cert-manager tool is a solution for X.509 certificate management on Kubernetes. It delivers a unified API to integrate applications with private or public key infrastructure (PKI), such as Vault, Google Cloud Certificate Authority Service, Let’s Encrypt, and other providers.
6+
7+
The cert-manager tool ensures the certificates are valid and up-to-date by attempting to renew certificates at a configured time before they expire.
8+
9+
For Istio users, cert-manager also provides integration with istio-csr, which is a certificate authority (CA) server that handles certificate signing requests (CSR) from Istio proxies. The server then delegates signing to cert-manager, which forwards CSRs to the configured CA server.
10+
11+
> [!NOTE]
12+
> Red Hat provides support for integrating with istio-csr and cert-manager. Red Hat does not provide direct support for the istio-csr or the community cert-manager components. The use of community cert-manager shown here is for demonstration purposes only.
13+
14+
## Prerequisites
15+
16+
- One of these versions of cert-manager:
17+
- cert-manager Operator for Red Hat OpenShift 1.10 or later
18+
- community cert-manager Operator 1.11 or later
19+
- cert-manager 1.11 or later
20+
- OpenShift Service Mesh Operator 3.0 or later
21+
- istio-csr 0.6.0 or later
22+
- `IstioCNI` instance is running in the cluster
23+
- [istioctl](https://istio.io/latest/docs/setup/install/istioctl/) is installed
24+
- [jq](https://github.com/jqlang/jq) is installed
25+
- [helm](https://helm.sh/docs/intro/install/) is installed
26+
27+
## Installing cert-manager
28+
29+
You can install the cert-manager tool to manage the lifecycle of TLS certificates and ensure that they are valid and up-to-date. If you are running Istio in your environment, you can also install the istio-csr certificate authority (CA) server, which handles certificate signing requests (CSR) from Istio proxies. The istio-csr CA delegates signing to the cert-manager tool, which delegates to the configured CA.
30+
31+
### Procedure
32+
33+
1. Create the `istio-system` namespace:
34+
35+
```sh
36+
oc create namespace istio-system
37+
```
38+
39+
2. Create the root cluster issuer:
40+
41+
```sh
42+
oc apply -f - <<EOF
43+
apiVersion: cert-manager.io/v1
44+
kind: Issuer
45+
metadata:
46+
name: selfsigned
47+
namespace: istio-system
48+
spec:
49+
selfSigned: {}
50+
---
51+
apiVersion: cert-manager.io/v1
52+
kind: Certificate
53+
metadata:
54+
name: istio-ca
55+
namespace: istio-system
56+
spec:
57+
isCA: true
58+
duration: 87600h # 10 years
59+
secretName: istio-ca
60+
commonName: istio-ca
61+
privateKey:
62+
algorithm: ECDSA
63+
size: 256
64+
subject:
65+
organizations:
66+
- cluster.local
67+
- cert-manager
68+
issuerRef:
69+
name: selfsigned
70+
kind: Issuer
71+
group: cert-manager.io
72+
---
73+
apiVersion: cert-manager.io/v1
74+
kind: Issuer
75+
metadata:
76+
name: istio-ca
77+
namespace: istio-system
78+
spec:
79+
ca:
80+
secretName: istio-ca
81+
EOF
82+
oc wait --for=condition=Ready certificates/istio-ca -n istio-system
83+
```
84+
85+
3. Export the Root CA to the `cert-manager` namespace:
86+
87+
```sh
88+
oc get -n istio-system secret istio-ca -o jsonpath='{.data.tls\.crt}' | base64 -d > ca.pem
89+
oc create secret generic -n cert-manager istio-root-ca --from-file=ca.pem=ca.pem
90+
```
91+
92+
4. Install istio-csr:
93+
94+
Next you will install istio-csr into the `cert-manager` namespace. Depending on which `updateStrategy` (`InPlace` or `RevisionBased`) you will choose for your `Istio` resource, you may need to pass additional options.
95+
96+
<!-- GitHub alerts cannot be nested within other elements but removing the indentation here messes up the rest of the indentation below. For this reason, using a plain note here instead of a fancy Alert.-->
97+
98+
**Note:** If your controlplane namespace is not `istio-system`, you will need to update `app.istio.namespace` to match your controlplane namespace.
99+
100+
`InPlace` strategy installation
101+
102+
```sh
103+
helm repo add jetstack https://charts.jetstack.io --force-update
104+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
105+
--install \
106+
--namespace cert-manager \
107+
--wait \
108+
--set "app.tls.rootCAFile=/var/run/secrets/istio-csr/ca.pem" \
109+
--set "volumeMounts[0].name=root-ca" \
110+
--set "volumeMounts[0].mountPath=/var/run/secrets/istio-csr" \
111+
--set "volumes[0].name=root-ca" \
112+
--set "volumes[0].secret.secretName=istio-root-ca" \
113+
--set "app.istio.namespace=istio-system"
114+
```
115+
116+
`RevisionBased` strategy installation
117+
118+
For the `RevisionBased` strategy, you need to specify all the istio revisions to your [istio-csr deployment](https://github.com/cert-manager/istio-csr/tree/main/deploy/charts/istio-csr#appistiorevisions0--string). You can find the names of your `IstioRevision`s with this command:
119+
120+
```sh
121+
oc get istiorevisions
122+
```
123+
124+
Install `istio-csr`
125+
126+
```sh
127+
helm repo add jetstack https://charts.jetstack.io --force-update
128+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
129+
--install \
130+
--namespace cert-manager \
131+
--wait \
132+
--set "app.tls.rootCAFile=/var/run/secrets/istio-csr/ca.pem" \
133+
--set "volumeMounts[0].name=root-ca" \
134+
--set "volumeMounts[0].mountPath=/var/run/secrets/istio-csr" \
135+
--set "volumes[0].name=root-ca" \
136+
--set "volumes[0].secret.secretName=istio-root-ca" \
137+
--set "app.istio.namespace=istio-system" \
138+
--set "app.istio.revisions={default-v1-23-0}"
139+
```
140+
141+
5. Install your `Istio` resource. Here we are disabling Istio's built in CA server and instead pointing istiod to the istio-csr CA server which will issue certificates for both istiod and user workloads. Additionally we mount the istiod certificate in a known location where it will be read by istiod. Mounting the certificates to a known location is only necessary on OSSM.
142+
143+
```sh
144+
oc apply -f - <<EOF
145+
apiVersion: sailoperator.io/v1alpha1
146+
kind: Istio
147+
metadata:
148+
name: default
149+
spec:
150+
version: v1.23.0
151+
namespace: istio-system
152+
values:
153+
global:
154+
caAddress: cert-manager-istio-csr.cert-manager.svc:443
155+
pilot:
156+
env:
157+
ENABLE_CA_SERVER: "false"
158+
volumeMounts:
159+
- mountPath: /tmp/var/run/secrets/istiod/tls
160+
name: istio-csr-dns-cert
161+
readOnly: true
162+
EOF
163+
```
164+
165+
6. Verification
166+
167+
Use the sample httpbin service and sleep app to check traffic between the workloads is possible and check the workload certificate of the proxy to verify that the cert-manager tool is installed correctly.
168+
169+
a. Create the `sample` namespace:
170+
171+
```sh
172+
oc new-project sample
173+
```
174+
175+
b. Find your active `IstioRevision`:
176+
177+
```sh
178+
oc get istiorevisions
179+
```
180+
181+
c. Add the injection label for your active revision to the `sample` namespace:
182+
183+
```sh
184+
oc label namespace sample istio.io/rev=<your-active-revision-name> --overwrite=true
185+
```
186+
187+
d. Deploy the HTTP and sleep apps:
188+
189+
```sh
190+
oc apply -n sample -f https://raw.githubusercontent.com/istio/istio/refs/heads/master/samples/httpbin/httpbin.yaml
191+
oc apply -n sample -f https://raw.githubusercontent.com/istio/istio/refs/heads/master/samples/sleep/sleep.yaml
192+
oc rollout status deployment httpbin sleep
193+
```
194+
195+
e. Verify that sleep can access the httpbin service:
196+
197+
```sh
198+
oc exec "$(oc get pod -l app=sleep -n sample \
199+
-o jsonpath={.items..metadata.name})" -c sleep -n sample -- \
200+
curl http://httpbin.sample:8000/ip -s -o /dev/null \
201+
-w "%{http_code}\n"
202+
```
203+
204+
Example output
205+
206+
```sh
207+
200
208+
```
209+
210+
f. Verify `httpbin` workload certificate matches what is expected:
211+
212+
```sh
213+
istioctl proxy-config secret -n sample $(oc get pods -n sample -o jsonpath='{.items..metadata.name}' --selector app=httpbin) -o json | jq -r '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' | base64 --decode | openssl x509 -text -noout
214+
```
215+
216+
Example output
217+
218+
```sh
219+
...
220+
Issuer: O = cert-manager + O = cluster.local, CN = istio-ca
221+
...
222+
X509v3 Subject Alternative Name:
223+
URI:spiffe://cluster.local/ns/sample/sa/httpbin
224+
```
225+
226+
### `RevisionBased` Upgrades
227+
228+
This section only applies to `RevisionBased` deployments.
229+
230+
Because istio-csr requires you to pass all revisions, each time you upgrade your `RevisionBased` controlplane you will need to **first** update your istio-csr deployment with the new revision before you update your `Istio.spec.version`. For example, before upgrading your controlplane from `v1.23.0 --> v1.23.1`, you need to first update your istio-csr deployment with the new revision:
231+
232+
```sh
233+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
234+
--install \
235+
--namespace cert-manager \
236+
--wait \
237+
--reuse-values \
238+
--set "app.istio.revisions={default-v1-23-0,default-v1-23-1}"
239+
```
240+
241+
Then you can update your `Istio.spec.version = v1.23.1`. Once the old revision is no longer in use, you can remove the revision from your istio-csr deployment as well.
242+
243+
```sh
244+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
245+
--install \
246+
--namespace cert-manager \
247+
--wait \
248+
--reuse-values \
249+
--set "app.istio.revisions={default-v1-23-1}"
250+
```
251+
252+
### Additional resources
253+
254+
For information about how to install the cert-manager Operator for OpenShift Container Platform, see: [Installing the cert-manager Operator for Red Hat OpenShift](https://docs.openshift.com/container-platform/4.16/security/cert_manager_operator/cert-manager-operator-install.html).

0 commit comments

Comments
 (0)