Skip to content

Commit 6c43707

Browse files
nrfoxnrfox
committed
Add docs for istio-csr
Signed-off-by: Nick Fox <[email protected]>
1 parent 212b79f commit 6c43707

File tree

2 files changed

+202
-1
lines changed

2 files changed

+202
-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: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
[Return to OSSM Docs](../)
2+
3+
# Cert Manager and istio-csr Integration
4+
5+
Below are instructions for integrating cert-manager with OpenShift Service Mesh 3. It largely follows the [cert-manager istio-csr documentation](https://cert-manager.io/docs/usage/istio-csr/) but you will need to adjust a few settings based on which `updateStrategy` you are using.
6+
7+
## Common Setup
8+
9+
These steps are the same for each `updateStrategy`.
10+
11+
1. Install the [cert-manager Operator for Red Hat OpenShift](https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-install).
12+
13+
2. Create the `istio-system` namespace for the root cert and for your `Istio` resource.
14+
15+
```sh
16+
oc create namespace istio-system
17+
```
18+
19+
3. Create a Self Signed certificate. Note you should adapt this example based on what PKI you are using e.g. using a vault `Issuer` instead of a self signed `Issuer`.
20+
21+
```sh
22+
oc apply -f https://raw.githubusercontent.com/cert-manager/website/7f5b2be9dd67831574b9bde2407bed4a920b691c/content/docs/tutorials/istio-csr/example/example-issuer.yaml
23+
```
24+
25+
4. Export the root CA to the `cert-manager` namespace.
26+
27+
```sh
28+
oc get -n istio-system secret istio-ca -o jsonpath='{.data.tls\.crt}' | base64 -d > ca.pem
29+
oc create secret generic -n cert-manager istio-root-ca --from-file=ca.pem=ca.pem
30+
```
31+
32+
## InPlace Strategy
33+
34+
1. Install [istio-csr](https://cert-manager.io/docs/usage/istio-csr).
35+
36+
```sh
37+
helm repo add jetstack https://charts.jetstack.io --force-update
38+
39+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
40+
--install \
41+
--namespace cert-manager \
42+
--wait \
43+
--set "app.tls.rootCAFile=/var/run/secrets/istio-csr/ca.pem" \
44+
--set "volumeMounts[0].name=root-ca" \
45+
--set "volumeMounts[0].mountPath=/var/run/secrets/istio-csr" \
46+
--set "volumes[0].name=root-ca" \
47+
--set "volumes[0].secret.secretName=istio-root-ca" \
48+
--set "app.istio.namespace=istio-system"
49+
```
50+
51+
Note: If your controlplane namespace is not `istio-system`, you will need to update `app.istio.namespace` to match your controlplane namespace.
52+
53+
2. Install `Istio` controlplane in the `istio-system` namespace.
54+
55+
```sh
56+
oc apply -f - <<EOF
57+
apiVersion: sailoperator.io/v1alpha1
58+
kind: Istio
59+
metadata:
60+
name: default
61+
spec:
62+
version: v1.23.0
63+
namespace: istio-system
64+
updateStrategy:
65+
type: InPlace
66+
values:
67+
global:
68+
caAddress: cert-manager-istio-csr.cert-manager.svc:443
69+
pilot:
70+
env:
71+
ENABLE_CA_SERVER: "false"
72+
volumeMounts:
73+
- mountPath: /tmp/var/run/secrets/istiod/tls
74+
name: istio-csr-dns-cert
75+
readOnly: true
76+
EOF
77+
```
78+
79+
3. [Verify your deployment](#verify) is configured correctly.
80+
81+
## RevisionBased Strategy
82+
83+
For the `RevisionBased` strategy, you need to specify all the istio revisions in your [istio-csr deployment](https://github.com/cert-manager/istio-csr/tree/main/deploy/charts/istio-csr#appistiorevisions0--string).
84+
85+
1. Install [istio-csr](https://cert-manager.io/docs/usage/istio-csr).
86+
87+
```sh
88+
helm repo add jetstack https://charts.jetstack.io --force-update
89+
90+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
91+
--install \
92+
--namespace cert-manager \
93+
--wait \
94+
--set "app.tls.rootCAFile=/var/run/secrets/istio-csr/ca.pem" \
95+
--set "volumeMounts[0].name=root-ca" \
96+
--set "volumeMounts[0].mountPath=/var/run/secrets/istio-csr" \
97+
--set "volumes[0].name=root-ca" \
98+
--set "volumes[0].secret.secretName=istio-root-ca" \
99+
--set "app.istio.namespace=istio-system" \
100+
--set "app.istio.revisions={default-v1-23-0}"
101+
```
102+
103+
Note: If your controlplane namespace is not `istio-system`, you will need to update `app.istio.namespace` to match your controlplane namespace.
104+
105+
2. Install `Istio` controlplane in the `istio-system` namespace.
106+
107+
```sh
108+
oc apply -f - <<EOF
109+
apiVersion: sailoperator.io/v1alpha1
110+
kind: Istio
111+
metadata:
112+
name: default
113+
spec:
114+
version: v1.23.0
115+
namespace: istio-system
116+
updateStrategy:
117+
type: RevisionBased
118+
values:
119+
global:
120+
caAddress: cert-manager-istio-csr.cert-manager.svc:443
121+
pilot:
122+
env:
123+
ENABLE_CA_SERVER: "false"
124+
volumeMounts:
125+
- mountPath: /tmp/var/run/secrets/istiod/tls
126+
name: istio-csr-dns-cert
127+
readOnly: true
128+
EOF
129+
```
130+
131+
3. [Verify your deployment](#verify) is configured correctly.
132+
133+
### Verify
134+
135+
1. Deploy a sample application.
136+
137+
Create the `sample` namespace.
138+
139+
```sh
140+
oc create namespace sample
141+
```
142+
143+
For the `RevisionBased` strategy, label your namespace with `istio.io/rev=default-v1-23-0`.
144+
145+
```sh
146+
oc label namespace sample istio.io/rev=default-v1-23-0
147+
```
148+
149+
For the `InPlace` strategy, label your namespace with `istio.io/rev=default`.
150+
151+
```sh
152+
oc label namespace sample istio.io/rev=default
153+
```
154+
155+
Deploy the `httpbin` application.
156+
157+
```sh
158+
oc apply -n sample -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/httpbin/httpbin.yaml
159+
```
160+
161+
2. Ensure httpbin pod is Running.
162+
163+
```sh
164+
oc get pods -n sample
165+
```
166+
167+
```sh
168+
NAME READY STATUS RESTARTS AGE
169+
httpbin-67854dd9b5-b7c2q 2/2 Running 0 110s
170+
```
171+
172+
3. Use `istioctl` to ensure httpbin workload certificate matches what is expected.
173+
174+
```sh
175+
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
176+
```
177+
178+
### Upgrades - RevisionBased
179+
180+
Because istio-csr requires you to pass all revisions, each time you upgrade your `RevsionBased` controlplane you will need to **first** update your istio-csr deployment with the new revision before you update your `Istio.spec.version`.
181+
182+
```sh
183+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
184+
--install \
185+
--namespace cert-manager \
186+
--wait \
187+
--reuse-values \
188+
--set "app.istio.revisions={default-v1-23-0,default-v1-23-1}"
189+
```
190+
191+
Once the old revision is no longer in use, you can remove the revision from istio-csr as well.
192+
193+
```sh
194+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
195+
--install \
196+
--namespace cert-manager \
197+
--wait \
198+
--reuse-values \
199+
--set "app.istio.revisions={default-v1-23-1}"
200+
```

0 commit comments

Comments
 (0)