Skip to content

Commit a7fe846

Browse files
rh-tokeeferh-tokeefe
committed
OSSM-3368: Add content for migrating to cluster-wide
1 parent 67f90f6 commit a7fe846

8 files changed

+387
-0
lines changed

‎modules/ossm-about-migrating-to-cluster-wide.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-deployment-models.adoc
3+
4+
:_mod-docs-content-type: CONCEPT
5+
[id="ossm-about-about-migrating-to-cluster-wide_{context}"]
6+
= About migrating to a cluster-wide mesh
7+
8+
In a cluster-wide mesh, one `ServiceMeshControlPlane` (SMCP) watches all of the namespaces for an entire cluster. You can migrate an existing cluster from a multitenant mesh to a cluster-wide mesh using {SMProductName} version 2.5 or later.
9+
10+
[NOTE]
11+
====
12+
If a cluster must have more than one SMCP, then you cannot migrate to a cluster-wide mesh.
13+
====
14+
15+
By default, a cluster-wide mesh discovers all of the namespaces that comprise a cluster. However, you can configure the mesh to access a limited set of namespaces. Namespaces do not receive sidecar injection by default. You must specify which namespaces receive sidecar injection.
16+
17+
Similarly, you must specify which pods receive sidecar injection. Pods that exist in a namespace that receives sidecar injection do not inherit sidecar injection. Applying sidecar injection to namespaces and to pods are separate operations.
18+
19+
If you change the Istio version when migrating to a cluster-wide mesh, then you must restart the applications. If you use the same Istio version, the application proxies will connect to the new SMCP for the cluster-wide mesh, and work the same way they did for a multitenant mesh.

‎modules/ossm-defining-namespace-receive-sidecar-injection-cluster-wide-mesh-cli.adoc

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-deployment-models.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="ossm-defining-namespace-receive-sidecar-injection-cluster-wide-mesh-cli_{context}"]
6+
= Defining which namespaces receive sidecar injection in a cluster-wide mesh by using the CLI
7+
8+
By default, the {SMProductName} Operator uses member selectors to identify which namespaces receive sidecar injection. Namespaces that do not match the `istio-injection=enabled` label as defined in the `ServiceMeshMemberRoll` resource do not receive sidecar injection.
9+
10+
[NOTE]
11+
====
12+
Using discovery selectors to determine which namespaces the mesh can discover has no effect on sidecar injection. Discovering namespaces and configuring sidecar injection are separate operations.
13+
====
14+
15+
.Prerequisites
16+
17+
* You have installed the {SMProductName} Operator.
18+
* You have deployed a `ServiceMeshControlPlanae` resource with the `mode: ClusterWide` annotation.
19+
* You are logged in as a user with the `cluster-admin` role. If you use {product-dedicated}, you are logged in as a user with the `dedicated-admin` role.
20+
21+
.Procedure
22+
23+
. Log in to the {product-title} CLI.
24+
25+
. Edit the `ServiceMeshMemberRoll` resource.
26+
+
27+
[source,terminal]
28+
----
29+
$ oc edit smmr -n <controlplane-namespace>
30+
----
31+
32+
. Modify the `spec.memberSelectors` field in the `ServiceMeshMemberRoll` resource by adding a member selector that matches the `inject` label. The following example uses `istio-injection: enabled`:
33+
+
34+
[source,yaml]
35+
----
36+
apiVersion: maistra.io/v1
37+
kind: ServiceMeshMemberRoll
38+
metadata:
39+
name: default
40+
spec:
41+
memberSelectors:
42+
- matchLabels:
43+
istio-injection: enabled <1>
44+
----
45+
<1> Ensures that the namespace receives sidecar injection.
46+
47+
. Save the file and exit the editor.

‎modules/ossm-defining-namespace-receive-sidecar-injection-cluster-wide-mesh-console.adoc

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-deployment-models.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="ossm-defining-namespace-receive-sidecar-injection-cluster-wide-mesh-console_{context}"]
6+
= Defining which namespaces receive sidecar injection in a cluster-wide mesh by using the web console
7+
8+
By default, the {SMProductName} Operator uses member selectors to identify which namespaces receive sidecar injection. Namespaces that do not match the `istio-injection=enabled` label as defined in the `ServiceMeshMemberRoll` resource do not receive sidecar injection.
9+
10+
[NOTE]
11+
====
12+
Using discovery selectors to determine which namespaces the mesh can discover has no effect on sidecar injection. Discovering namespaces and configuring sidecar injection are separate operations.
13+
====
14+
15+
.Prerequisites
16+
17+
* You have installed the {SMProductName} Operator.
18+
* You have deployed a `ServiceMeshControlPlanae` resource with the `mode: ClusterWide` annotation.
19+
* You are logged in as a user with the `cluster-admin` role. If you use {product-dedicated}, you are logged in as a user with the `dedicated-admin` role.
20+
21+
.Procedure
22+
23+
. Log in to the {product-title} web console.
24+
25+
. Navigate to *Operators* -> *Installed Operators*.
26+
27+
. Click the {SMProductName} Operator.
28+
29+
. Click *Istio Service Mesh Member Roll*.
30+
31+
. Click the `ServiceMeshMemberRoll` resource.
32+
33+
. Click *YAML*.
34+
35+
. Modify the `spec.memberSelectors` field in the `ServiceMeshMemberRoll` resource by adding a member selector that matches the `inject` label. The following example uses `istio-injection: enabled`:
36+
+
37+
[source,yaml]
38+
----
39+
apiVersion: maistra.io/v1
40+
kind: ServiceMeshMemberRoll
41+
metadata:
42+
name: default
43+
spec:
44+
memberSelectors:
45+
- matchLabels:
46+
istio-injection: enabled <1>
47+
----
48+
<1> Ensures that the namespace receives sidecar injection.
49+
50+
. Save the file.

‎modules/ossm-excluding-individual-pods-from-cluster-wide-mesh-cli.adoc

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-deployment-models.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="ossm-excluding-individual-pods-from-cluster-wide-mesh-cli_{context}"]
6+
= Excluding individual pods from a cluster-wide mesh by using the CLI
7+
8+
A pod receives sidecar injection if it has the `sidecar.istio.io/inject: true` annotation applied, and the pod exists in a namespace that matches either the label selector or the members list defined in the `ServiceMeshMemberRoll` resource.
9+
10+
If a pod does not have the `sidecar.istio.io/inject` annotation applied, it cannot receive sidecar injection.
11+
12+
.Prerequisites
13+
14+
* You have installed the {SMProductName} Operator.
15+
* You have deployed a `ServiceMeshControlPlane` resource with the `mode: ClusterWide` annotation.
16+
* You are logged in as a user with the `cluster-admin` role. If you use {product-dedicated}, you are logged in as a user with the `dedicated-admin` role.
17+
18+
.Procedure
19+
20+
. Log in to the {product-title} CLI.
21+
22+
. Edit the deployment by running the following command:
23+
+
24+
[source,terminal]
25+
----
26+
$ oc edit deployment -n <namespace> <deploymentName>
27+
----
28+
29+
. Modify the YAML file to deploy one application that receives sidecar injection and one that does not, as shown in the following example:
30+
+
31+
[source,yaml]
32+
----
33+
apiVersion: apps/v1
34+
kind: Deployment
35+
metadata:
36+
name: nginx
37+
spec:
38+
selector:
39+
matchLabels:
40+
app: nginx
41+
template:
42+
metadata:
43+
annotations:
44+
sidecar.istio.io/inject: 'true' <1>
45+
labels:
46+
app: nginx
47+
spec:
48+
containers:
49+
- name: nginx
50+
image: nginx:1.14.2
51+
ports:
52+
- containerPort: 80
53+
---
54+
apiVersion: apps/v1
55+
kind: Deployment
56+
metadata:
57+
name: nginx-without-sidecar
58+
spec:
59+
selector:
60+
matchLabels:
61+
app: nginx-without-sidecar
62+
template:
63+
metadata:
64+
labels:
65+
app: nginx-without-sidecar <2>
66+
spec:
67+
containers:
68+
- name: nginx
69+
image: nginx:1.14.2
70+
ports:
71+
- containerPort: 80
72+
----
73+
<1> This pod has the `sidecar.istio.io/inject` annotation applied, so it receives sidecar injection.
74+
<2> This pod does not have the annotation, so it does not receive sidecar injection.
75+
76+
. Save the file.

‎modules/ossm-excluding-individual-pods-from-cluster-wide-mesh-console.adoc

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-deployment-models.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="ossm-excluding-individual-pods-from-cluster-wide-mesh-console_{context}"]
6+
= Excluding individual pods from a cluster-wide mesh by using the web console
7+
8+
A pod receives sidecar injection if it has the `sidecar.istio.io/inject: true` annotation applied, and the pod exists in a namespace that matches either the label selector or the members list defined in the `ServiceMeshMemberRoll` resource.
9+
10+
If a pod does not have the `sidecar.istio.io/inject` annotation applied, it cannot receive sidecar injection.
11+
12+
.Prerequisites
13+
14+
* You have installed the {SMProductName} Operator.
15+
* You have deployed a `ServiceMeshControlPlane` resource with the `mode: ClusterWide` annotation.
16+
* You are logged in as a user with the `cluster-admin` role. If you use {product-dedicated}, you are logged in as a user with the `dedicated-admin` role.
17+
18+
.Procedure
19+
20+
. Log in to the {product-title} web console.
21+
22+
. Navigate to *Workloads* -> *Deployments*.
23+
24+
. Click the name of the deployment.
25+
26+
. Click *YAML*.
27+
28+
. Modify the YAML file to deploy one application that receives sidecar injection and one that does not, as shown in the following example:
29+
+
30+
[source,yaml]
31+
----
32+
apiVersion: apps/v1
33+
kind: Deployment
34+
metadata:
35+
name: nginx
36+
spec:
37+
selector:
38+
matchLabels:
39+
app: nginx
40+
template:
41+
metadata:
42+
annotations:
43+
sidecar.istio.io/inject: 'true' <1>
44+
labels:
45+
app: nginx
46+
spec:
47+
containers:
48+
- name: nginx
49+
image: nginx:1.14.2
50+
ports:
51+
- containerPort: 80
52+
---
53+
apiVersion: apps/v1
54+
kind: Deployment
55+
metadata:
56+
name: nginx-without-sidecar
57+
spec:
58+
selector:
59+
matchLabels:
60+
app: nginx-without-sidecar
61+
template:
62+
metadata:
63+
labels:
64+
app: nginx-without-sidecar <2>
65+
spec:
66+
containers:
67+
- name: nginx
68+
image: nginx:1.14.2
69+
ports:
70+
- containerPort: 80
71+
----
72+
<1> This pod has the `sidecar.istio.io/inject` annotation applied, so it receives sidecar injection.
73+
<2> This pod does not have the annotation, so it does not receive sidecar injection.
74+
75+
. Save the file.

‎modules/ossm-excluding-namespaces-from-cluster-wide-mesh-cli.adoc

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-deployment-models.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="ossm-excluding-namespaces-from-cluster-wide-mesh-cli_{context}"]
6+
= Including and excluding namespaces from a cluster-wide mesh by using the CLI
7+
8+
By default, the {SMProductName} Operator uses discovery selectors to identify the namespaces that make up the mesh. Namespaces that do not contain the label defined in the `ServiceMeshMemberRoll` resource are not matched by the discovery selector and are excluded from the mesh.
9+
10+
.Prerequisites
11+
12+
* You have installed the {SMProductName} Operator.
13+
* You have deployed a `ServiceMeshControlPlane` resource.
14+
* You are logged in as a user with the `cluster-admin` role. If you use {product-dedicated}, you are logged in as a user with the `dedicated-admin` role.
15+
16+
.Procedure
17+
18+
. Log in to the {product-title} CLI.
19+
20+
. Open the `ServiceMeshControlPlane` resource as a YAML file by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc -n istio-system edit smcp <name> <1>
25+
----
26+
<1> `<name>` represents the name of the `ServiceMeshControlPlane` resource.
27+
28+
. Modify the YAML file so that the `spec.discoverySelectors` field of the `ServiceMeshMemberRoll` resource includes the discovery selector. The following example uses `istio-discovery: enabled`:
29+
+
30+
[source,yaml]
31+
----
32+
apiVersion: maistra.io/v2
33+
kind: ServiceMeshControlPlane
34+
metadata:
35+
name: basic
36+
spec:
37+
mode: ClusterWide
38+
meshConfig:
39+
discoverySelectors:
40+
- matchLabels:
41+
istio-discovery: enabled <1>
42+
- matchExpressions:
43+
- key: kubernetes.io/metadata.name <2>
44+
operator: NotIn
45+
values:
46+
- bookinfo
47+
- httpbin
48+
----
49+
<1> Ensures that the mesh discovers namespaces that contain the label `istio-discovery: enabled`. The mesh does not discover namespaces that do not contain the label.
50+
<2> Ensures that the mesh does not discover namespaces `bookinfo` and `httpbin`.
51+
52+
. Save the file and exit the editor.

‎modules/ossm-excluding-namespaces-from-cluster-wide-mesh-console.adoc

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-deployment-models.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="ossm-excluding-namespaces-from-cluster-wide-mesh-console_{context}"]
6+
= Including and excluding namespaces from a cluster-wide mesh by using the web console
7+
8+
By default, the {SMProductName} Operator uses discovery selectors to identify the namespaces that make up the mesh. Namespaces that do not contain the label defined in the `ServiceMeshMemberRoll` resource are not matched by the discovery selector and are excluded from the mesh.
9+
10+
.Prerequisites
11+
12+
* You have installed the {SMProductName} Operator.
13+
* You have deployed a `ServiceMeshControlPlane` resource.
14+
* You are logged in as a user with the `cluster-admin` role. If you use {product-dedicated}, you are logged in as a user with the `dedicated-admin` role.
15+
16+
.Procedure
17+
18+
. Log in to the {product-title} web console.
19+
20+
. Navigate to *Operators* -> *Installed Operators*.
21+
22+
. Click the {SMProductName} Operator.
23+
24+
. Click *Istio Service Mesh Control Plane*.
25+
26+
. Click the name of the control plane.
27+
28+
. Click *YAML*.
29+
30+
. Modify the YAML file so that the `spec.discoverySelectors` field of the `ServiceMeshMemberRoll` resource includes the discovery selector. The following example uses `istio-discovery: enabled`:
31+
+
32+
[source,yaml]
33+
----
34+
apiVersion: maistra.io/v2
35+
kind: ServiceMeshControlPlane
36+
metadata:
37+
name: basic
38+
spec:
39+
mode: ClusterWide
40+
meshConfig:
41+
discoverySelectors:
42+
- matchLabels:
43+
istio-discovery: enabled <1>
44+
- matchExpressions:
45+
- key: kubernetes.io/metadata.name <2>
46+
operator: NotIn
47+
values:
48+
- bookinfo
49+
- httpbin
50+
----
51+
<1> Ensures that the mesh discovers namespaces that contain the label `istio-discovery: enabled`. The mesh does not discover namespaces that do not contain the label.
52+
<2> Ensures that the mesh does not discover namespaces `bookinfo` and `httpbin`.
53+
54+
. Save the file.

0 commit comments

Comments
 (0)