OSSM-3368: Add content for migrating to cluster-wide

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

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-deployment-models.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-about-migrating-to-cluster-wide_{context}"]
+= About migrating to a cluster-wide mesh
+
+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. 
+
+[NOTE]
+====
+If a cluster must have more than one SMCP, then you cannot migrate to a cluster-wide mesh.
+====
+
+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.
+
+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.
+
+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

@@ -0,0 +1,47 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-deployment-models.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-defining-namespace-receive-sidecar-injection-cluster-wide-mesh-cli_{context}"]
+= Defining which namespaces receive sidecar injection in a cluster-wide mesh by using the CLI
+
+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.
+
+[NOTE]
+====
+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.
+====
+
+.Prerequisites
+
+* You have installed the {SMProductName} Operator.
+* You have deployed a `ServiceMeshControlPlanae` resource with the `mode: ClusterWide` annotation.
+* 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.
+
+.Procedure
+
+. Log in to the {product-title} CLI.
+
+. Edit the `ServiceMeshMemberRoll` resource.
++
+[source,terminal]
+----
+$ oc edit smmr -n <controlplane-namespace>
+----
+
+. 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`:
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshMemberRoll
+metadata: 
+  name: default
+spec: 
+  memberSelectors: 
+  - matchLabels: 
+      istio-injection: enabled <1>
+----
+<1> Ensures that the namespace receives sidecar injection. 
+
+. Save the file and exit the editor.

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

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-deployment-models.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-defining-namespace-receive-sidecar-injection-cluster-wide-mesh-console_{context}"]
+= Defining which namespaces receive sidecar injection in a cluster-wide mesh by using the web console
+
+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.
+
+[NOTE]
+====
+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.
+====
+
+.Prerequisites
+
+* You have installed the {SMProductName} Operator.
+* You have deployed a `ServiceMeshControlPlanae` resource with the `mode: ClusterWide` annotation.
+* 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.
+
+.Procedure
+
+. Log in to the {product-title} web console.
+
+. Navigate to *Operators* -> *Installed Operators*.
+
+. Click the {SMProductName} Operator.
+
+. Click *Istio Service Mesh Member Roll*.
+
+. Click the `ServiceMeshMemberRoll` resource.
+
+. Click *YAML*.
+
+. 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`:
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshMemberRoll
+metadata: 
+  name: default
+spec: 
+  memberSelectors: 
+  - matchLabels: 
+      istio-injection: enabled <1>
+----
+<1> Ensures that the namespace receives sidecar injection. 
+
+. Save the file.

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

@@ -0,0 +1,76 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-deployment-models.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="ossm-excluding-individual-pods-from-cluster-wide-mesh-cli_{context}"]
+= Excluding individual pods from a cluster-wide mesh by using the CLI
+
+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. 
+
+If a pod does not have the `sidecar.istio.io/inject` annotation applied, it cannot receive sidecar injection.
+
+.Prerequisites
+
+* You have installed the {SMProductName} Operator.
+* You have deployed a `ServiceMeshControlPlane` resource with the `mode: ClusterWide` annotation.
+* 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.
+
+.Procedure
+
+. Log in to the {product-title} CLI.
+
+. Edit the deployment by running the following command:
++
+[source,terminal]
+----
+$ oc edit deployment -n <namespace> <deploymentName>
+----
+
+. Modify the YAML file to deploy one application that receives sidecar injection and one that does not, as shown in the following example:
++
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+spec:
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      annotations:
+        sidecar.istio.io/inject: 'true' <1>
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.14.2
+        ports:
+        - containerPort: 80
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-without-sidecar
+spec:
+  selector:
+    matchLabels:
+      app: nginx-without-sidecar 
+  template:
+    metadata:
+      labels:
+        app: nginx-without-sidecar <2>
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.14.2
+        ports:
+        - containerPort: 80
+----
+<1> This pod has the `sidecar.istio.io/inject` annotation applied, so it receives sidecar injection.
+<2> This pod does not have the annotation, so it does not receive sidecar injection.
+
+. Save the file.

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

@@ -0,0 +1,75 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-deployment-models.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="ossm-excluding-individual-pods-from-cluster-wide-mesh-console_{context}"]
+= Excluding individual pods from a cluster-wide mesh by using the web console
+
+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. 
+
+If a pod does not have the `sidecar.istio.io/inject` annotation applied, it cannot receive sidecar injection.
+
+.Prerequisites
+
+* You have installed the {SMProductName} Operator.
+* You have deployed a `ServiceMeshControlPlane` resource with the `mode: ClusterWide` annotation.
+* 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.
+
+.Procedure
+
+. Log in to the {product-title} web console.
+
+. Navigate to *Workloads* -> *Deployments*.
+
+. Click the name of the deployment.
+
+. Click *YAML*.
+
+. Modify the YAML file to deploy one application that receives sidecar injection and one that does not, as shown in the following example:
++
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+spec:
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      annotations:
+        sidecar.istio.io/inject: 'true' <1>
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.14.2
+        ports:
+        - containerPort: 80
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-without-sidecar
+spec:
+  selector:
+    matchLabels:
+      app: nginx-without-sidecar 
+  template:
+    metadata:
+      labels:
+        app: nginx-without-sidecar <2>
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.14.2
+        ports:
+        - containerPort: 80
+----
+<1> This pod has the `sidecar.istio.io/inject` annotation applied, so it receives sidecar injection.
+<2> This pod does not have the annotation, so it does not receive sidecar injection.
+
+. Save the file.

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

@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-deployment-models.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-excluding-namespaces-from-cluster-wide-mesh-cli_{context}"]
+= Including and excluding namespaces from a cluster-wide mesh by using the CLI
+
+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.  
+
+.Prerequisites
+
+* You have installed the {SMProductName} Operator.
+* You have deployed a `ServiceMeshControlPlane` resource.
+* 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.
+
+.Procedure
+
+. Log in to the {product-title} CLI.
+
+. Open the `ServiceMeshControlPlane` resource as a YAML file by running the following command:
++
+[source,terminal]
+----
+$ oc -n istio-system edit smcp <name> <1>
+----
+<1> `<name>` represents the name of the `ServiceMeshControlPlane` resource.
+
+. 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`:
++
+[source,yaml]
+----
+apiVersion: maistra.io/v2
+kind: ServiceMeshControlPlane
+metadata: 
+  name: basic
+spec: 
+  mode: ClusterWide
+  meshConfig: 
+    discoverySelectors:
+    - matchLabels: 
+        istio-discovery: enabled <1>
+    - matchExpressions:
+      - key: kubernetes.io/metadata.name <2>
+        operator: NotIn
+        values:
+        - bookinfo
+        - httpbin
+----
+<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.
+<2> Ensures that the mesh does not discover namespaces `bookinfo` and `httpbin`.
+
+. Save the file and exit the editor.

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

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-deployment-models.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-excluding-namespaces-from-cluster-wide-mesh-console_{context}"]
+= Including and excluding namespaces from a cluster-wide mesh by using the web console
+
+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.  
+
+.Prerequisites
+
+* You have installed the {SMProductName} Operator.
+* You have deployed a `ServiceMeshControlPlane` resource.
+* 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.
+
+.Procedure
+
+. Log in to the {product-title} web console.
+
+. Navigate to *Operators* -> *Installed Operators*.
+
+. Click the {SMProductName} Operator.
+
+. Click *Istio Service Mesh Control Plane*.
+
+. Click the name of the control plane.
+
+. Click *YAML*.
+
+. 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`:
++
+[source,yaml]
+----
+apiVersion: maistra.io/v2
+kind: ServiceMeshControlPlane
+metadata: 
+  name: basic
+spec: 
+  mode: ClusterWide
+  meshConfig: 
+    discoverySelectors:
+    - matchLabels: 
+        istio-discovery: enabled <1>
+    - matchExpressions:
+      - key: kubernetes.io/metadata.name <2>
+        operator: NotIn
+        values:
+        - bookinfo
+        - httpbin
+----
+<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.
+<2> Ensures that the mesh does not discover namespaces `bookinfo` and `httpbin`.
+
+. Save the file.