Skip to content

Commit 2304b1c

Browse files
nrfoxnrfox
authored
Add cert manager migration docs (openshift-service-mesh#179)
Signed-off-by: Nick Fox <[email protected]>
1 parent 78ad04b commit 2304b1c

File tree

1 file changed

+336
-0
lines changed
  • docs/ossm/ossm2-migration/cert-manager

1 file changed

+336
-0
lines changed

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

Lines changed: 336 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,336 @@
1+
# OpenShift Service Mesh 2.6 --> 3.0 Migration with Cert-Manager
2+
3+
When migrating from OpenShift Service Mesh 2.6 --> 3.0 while using Cert-Manager you can largely follow the [ClusterWide](TODO) or [MultiTenant](../multi-tenancy/README.md) migration guides. This document details a few necessary additional steps to follow before creating your `Istio` resource to ensure your cert manager configuration works with 3.0.
4+
5+
<!--
6+
7+
Steps for testing:
8+
9+
1. Install cert-manager operator
10+
11+
1. Install cluster issuer:
12+
13+
```yaml
14+
apiVersion: cert-manager.io/v1
15+
kind: Issuer
16+
metadata:
17+
name: selfsigned-root-issuer
18+
namespace: cert-manager
19+
spec:
20+
selfSigned: {}
21+
---
22+
apiVersion: cert-manager.io/v1
23+
kind: Certificate
24+
metadata:
25+
name: root-ca
26+
namespace: cert-manager
27+
spec:
28+
isCA: true
29+
duration: 21600h # 900d
30+
secretName: root-ca
31+
commonName: root-ca.my-company.net
32+
subject:
33+
organizations:
34+
- my-company.net
35+
issuerRef:
36+
name: selfsigned-root-issuer
37+
kind: Issuer
38+
group: cert-manager.io
39+
---
40+
apiVersion: cert-manager.io/v1
41+
kind: ClusterIssuer
42+
metadata:
43+
name: root-ca
44+
spec:
45+
ca:
46+
secretName: root-ca
47+
```
48+
49+
1. Install istio-ca
50+
51+
```yaml
52+
apiVersion: cert-manager.io/v1
53+
kind: Certificate
54+
metadata:
55+
name: istio-ca
56+
namespace: istio-system
57+
spec:
58+
isCA: true
59+
duration: 21600h
60+
secretName: istio-ca
61+
commonName: istio-ca.my-company.net
62+
subject:
63+
organizations:
64+
- my-company.net
65+
issuerRef:
66+
name: root-ca
67+
kind: ClusterIssuer
68+
group: cert-manager.io
69+
---
70+
apiVersion: cert-manager.io/v1
71+
kind: Issuer
72+
metadata:
73+
name: istio-ca
74+
namespace: istio-system
75+
spec:
76+
ca:
77+
secretName: istio-ca
78+
```
79+
80+
1. Helm install istio-csr
81+
82+
values.yaml
83+
84+
```yaml
85+
image:
86+
repository: quay.io/jetstack/cert-manager-istio-csr
87+
88+
app:
89+
certmanager:
90+
namespace: istio-system
91+
issuer:
92+
group: cert-manager.io
93+
kind: Issuer
94+
name: istio-ca
95+
96+
controller:
97+
leaderElectionNamespace: istio-system
98+
99+
istio:
100+
namespace: istio-system
101+
revisions: ["basic"]
102+
103+
server:
104+
maxCertificateDuration: 5m
105+
106+
tls:
107+
certificateDNSNames:
108+
# This DNS name must be set in the SMCP spec.security.certificateAuthority.cert-manager.address
109+
- cert-manager-istio-csr.istio-system.svc
110+
```
111+
112+
```console
113+
helm repo add jetstack https://charts.jetstack.io --force-update
114+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
115+
--install \
116+
--namespace istio-system \
117+
--wait \
118+
-f values.yaml
119+
```
120+
121+
122+
1. Create SMCP
123+
124+
```yaml
125+
apiVersion: maistra.io/v2
126+
kind: ServiceMeshControlPlane
127+
metadata:
128+
name: basic
129+
namespace: istio-system
130+
spec:
131+
addons:
132+
grafana:
133+
enabled: false
134+
kiali:
135+
enabled: false
136+
prometheus:
137+
enabled: false
138+
gateways:
139+
enabled: false
140+
openshiftRoute:
141+
enabled: false
142+
profiles:
143+
- default
144+
security:
145+
certificateAuthority:
146+
cert-manager:
147+
address: cert-manager-istio-csr.istio-system.svc:443
148+
type: cert-manager
149+
dataPlane:
150+
mtls: true
151+
identity:
152+
type: ThirdParty
153+
manageNetworkPolicy: false
154+
tracing:
155+
type: None
156+
version: v2.6
157+
```
158+
159+
1. Update istio-csr with future Istio revision.
160+
161+
```console
162+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
163+
--install \
164+
--reuse-values \
165+
--namespace istio-system \
166+
--wait \
167+
--set "app.istio.revisions={basic,ossm3-v1-24-1}"
168+
```
169+
170+
1. Create Istio resource
171+
172+
```yaml
173+
apiVersion: sailoperator.io/v1alpha1
174+
kind: Istio
175+
metadata:
176+
generation: 3
177+
name: ossm3
178+
spec:
179+
namespace: istio-system
180+
updateStrategy:
181+
type: RevisionBased
182+
values:
183+
global:
184+
caAddress: cert-manager-istio-csr.istio-system.svc:443
185+
pilot:
186+
env:
187+
ENABLE_CA_SERVER: "false"
188+
version: v1.24.1
189+
```
190+
191+
1. Create bookinfo namespace
192+
193+
```console
194+
oc create ns bookinfo
195+
```
196+
197+
1. Create smmr and add bookinfo to it
198+
```yaml
199+
apiVersion: maistra.io/v1
200+
kind: ServiceMeshMemberRoll
201+
metadata:
202+
name: default
203+
namespace: istio-system
204+
spec:
205+
members:
206+
- bookinfo
207+
```
208+
209+
1. Deploy bookinfo
210+
```console
211+
oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-2.6/samples/bookinfo/platform/kube/bookinfo.yaml
212+
```
213+
214+
1. Ensure proxies injected
215+
216+
```console
217+
oc get pods -n bookinfo
218+
NAME READY STATUS RESTARTS AGE
219+
details-v1-9979968fb-776jq 2/2 Running 0 33m
220+
productpage-v1-8669b4d5c8-hshtz 2/2 Running 0 33m
221+
ratings-v1-bbb89988d-tcgvp 2/2 Running 0 33m
222+
reviews-v1-75b6949cf4-7kbdm 2/2 Running 0 33m
223+
reviews-v2-64f68558b-gsxc4 2/2 Running 0 33m
224+
reviews-v3-596954cfd6-jnb6n 2/2 Running 0 33m
225+
```
226+
227+
1. Migrate to 3.0
228+
229+
```console
230+
oc label ns bookinfo istio.io/rev=ossm3-v1-24-1 maistra.io/ignore-namespace="true" istio-injection- --overwrite=true
231+
oc rollout restart deployment -n bookinfo
232+
```
233+
234+
1. Ensure proxies connected to correct control plane
235+
```console
236+
istioctl ps -n bookinfo
237+
NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION
238+
details-v1-9979968fb-776jq.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-ossm3-v1-24-1-d5b9b4c89-ccz4v 1.24.1
239+
productpage-v1-8669b4d5c8-hshtz.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-ossm3-v1-24-1-d5b9b4c89-ccz4v 1.24.1
240+
ratings-v1-bbb89988d-tcgvp.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-ossm3-v1-24-1-d5b9b4c89-ccz4v 1.24.1
241+
reviews-v1-75b6949cf4-7kbdm.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-ossm3-v1-24-1-d5b9b4c89-ccz4v 1.24.1
242+
reviews-v2-64f68558b-gsxc4.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-ossm3-v1-24-1-d5b9b4c89-ccz4v 1.24.1
243+
reviews-v3-596954cfd6-jnb6n.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-ossm3-v1-24-1-d5b9b4c89-ccz4v 1.24.1
244+
```
245+
-->
246+
247+
Starting with a `ServiceMeshControlPlane` with cert-manager configured:
248+
249+
```yaml
250+
apiVersion: maistra.io/v2
251+
kind: ServiceMeshControlPlane
252+
metadata:
253+
name: basic
254+
namespace: istio-system
255+
spec:
256+
...
257+
security:
258+
certificateAuthority:
259+
cert-manager:
260+
address: cert-manager-istio-csr.istio-system.svc:443
261+
type: cert-manager
262+
dataPlane:
263+
mtls: true
264+
identity:
265+
type: ThirdParty
266+
manageNetworkPolicy: false
267+
```
268+
269+
You will need to perform these updates to your istio-csr deployment:
270+
271+
- The `app.istio.revisions` field needs to include your 3.0 control plane revision _before_ you create your `Istio` resource.
272+
273+
Adding your 3.0 control plane revision to your istio-csr deployment will ensure that proxies can properly communicate with the 3.0 control plane.
274+
275+
```console
276+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
277+
--install \
278+
--reuse-values \
279+
--namespace istio-system \
280+
--wait \
281+
--set "app.istio.revisions={basic,ossm3-v1-24-1}"
282+
```
283+
284+
Depending on whether you will use a `RevisionBased` update strategy or an `InPlace` update strategy, your revision name will vary. If using an `InPlace` strategy, your revision name will match your `Istio` name. If using a `RevisionBased` strategy, revision names use the following format, `<istio-name>-v<major_version>-<minor_version>-<patch_version>`. For example: `ossm3-v1-24-1`.
285+
286+
- The `app.controller.configmapNamespaceSelector` field needs to be either unset _before_ the migration begins or updated _after_ you have completed your migration.
287+
288+
If you have set the `app.controller.configmapNamespaceSelector` field on your istio-csr deployment to `maistra.io/member-of`, you will need to update this accordingly. If you haven't set this field, you can keep it unset.
289+
290+
If the `configmapNamespaceSelector` field on your istio-csr deployment is set, the istio CA configmap will only be injected into namespaces that match the label selector. `MultiTenant` deployments with more than one `ServiceMeshControlPlane` in the cluster should not remove this field since the wrong CA configmap would likely get written to the namespace. `ClusterWide` deployments with only a single `SMCP` can choose to leave this unset. If you are keeping the field set, you need to wait until **after** you have completed your migration to update the `configmapNamespaceSelector` field. Otherwise namespaces without the injection label will no longer have the configmap CA injected.
291+
292+
To unset this field:
293+
294+
```console
295+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
296+
--install \
297+
--reuse-values \
298+
--namespace istio-system \
299+
--wait \
300+
--set "app.controller.configmapNamespaceSelector="
301+
```
302+
303+
To update this field:
304+
305+
> **_NOTE:_** Before updating, ensure you have completely finished your migration and the new injection label, in this example `istio-injection=enabled`, is present on all workload namespaces before updating istio-csr.
306+
307+
```console
308+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
309+
--install \
310+
--reuse-values \
311+
--namespace istio-system \
312+
--wait \
313+
--set "app.controller.configmapNamespaceSelector=istio-injection=enabled"
314+
```
315+
316+
After updating your istio-csr deployment, you can create the `Istio` resource with the following settings to work with cert-manager. Similar to the 2.6 controlplane, these settings disable the built-in CA server and instead use the istio-csr address.
317+
318+
- Create Istio Resource.
319+
320+
```yaml
321+
apiVersion: sailoperator.io/v1alpha1
322+
kind: Istio
323+
metadata:
324+
name: ossm3
325+
spec:
326+
...
327+
namespace: istio-system
328+
values:
329+
global:
330+
caAddress: cert-manager-istio-csr.istio-system.svc:443
331+
pilot:
332+
env:
333+
ENABLE_CA_SERVER: "false"
334+
```
335+
336+
That's it. From here you can follow the [MultiTenant](../multi-tenancy/README.md) or [ClusterWide](TODO) guides for migrating workloads from your 2.6 control plane to the 3.0 control plane.

0 commit comments

Comments
 (0)