[service-mesh-docs-3.0.0tp1] OSSM-8200 Document how to scope the mesh with Discovery Selectors

install/ossm-installing-openshift-service-mesh.adoc

@@ -16,6 +16,13 @@ include::modules/ossm-creating-istio-project-using-console.adoc[leveloffset=+2]
 include::modules/ossm-creating-istio-resource-using-console.adoc[leveloffset=+2]
 include::modules/ossm-creating-istio-cni-project-using-console.adoc[leveloffset=+2]
 include::modules/ossm-creating-istiocni-resource-using-console.adoc[leveloffset=+2]
+include::modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc[leveloffset=+1]
+include::modules/ossm-about-discoveryselectors.adoc[leveloffset=+2]
+include::modules/ossm-using-discoveryselectors-scope-service-mesh.adoc[leveloffset=+2]
+[role="_next-steps"]
+.Next steps
+* xref:../install/ossm-installing-openshift-service-mesh.adoc#deploying-book-info_ossm-about-bookinfo-application[Deploying the Bookinfo application]
+
 include::modules/ossm-about-bookinfo-application.adoc[leveloffset=+1]
 include::modules/ossm-deploying-bookinfo-application.adoc[leveloffset=+2]
 include::modules/ossm-about-accessing-bookinfo-application-using-gateway.adoc[leveloffset=+2]

modules/ossm-about-discoveryselectors.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+// install/ossm-installing-openshift-service-mesh.adoc
+
+:_mod-docs-content-type: Concept
+[id="ossm-about-discoveryselectors_{context}"]
+= About discovery selectors
+:context: ossm-about-discoveryselectors
+
+With discovery selectors, the mesh administrator can control which namespaces the control plane can access. By using a {k8s} label selector, the administrator sets the criteria for the namespaces visible to the control plane, excluding any namespaces that do not match the specified criteria.
+
+[NOTE]
+====
+Istiod always opens a watch to {ocp-short-name} for all namespaces. However, discovery selectors ignore objects that are not selected very early in its processing, minimizing costs.
+====
+
+The `discoverySelectors` field accepts an array of {k8s} selectors, which apply to labels on namespaces. You can configure each selector for different use cases:
+
+* Custom label names and values. For example, configure all namespaces with the label `istio-discovery=enabled`.
+* A list of namespace labels by using set-based selectors with OR logic. For instance, configure namespaces with `istio-discovery=enabled` OR `region=us-east1`.
+* Inclusion and exclusion of namespaces. For example, configure namespaces with `istio-discovery=enabled` AND the label `app=helloworld`.
+
+[NOTE]
+====
+Discovery selectors are not a security boundary. Istiod continues to have access to all namespaces even when you have configured the `discoverySelector` field.
+====
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors[Label selectors]
+* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements[Resources that support set-based requirements]

modules/ossm-deploying-bookinfo-application.adoc

@@ -4,7 +4,6 @@
 :_mod-docs-content-type: Procedure
 [id="deploying-book-info_{context}"]
 = Deploying the Bookinfo application
-:context: ossm-pdeploying-book-info
 
 .Prerequisites
 
@@ -24,11 +23,11 @@ The *Display name* and *Description* fields provide supplementary information an
 
 . Click *Create*.
 
-. Apply the {Istio} injection label to the `bookinfo` namespace by entering the following command at the CLI:
+. Apply the {Istio} discovery selector and injection label to the `bookinfo` namespace by entering the following command at the CLI:
 +
 [source,terminal]
 ----
-$ oc label namespace bookinfo istio-injection=enabled
+$ oc label namespace bookinfo istio-discovery=enabled istio-injection=enabled 
 ----
 +
 [NOTE]

modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+// install/ossm-installing-openshift-service-mesh.adoc
+
+:_mod-docs-content-type: Concept
+[id="ossm-scoping-service-mesh-with-discoveryselectors_{context}"]
+= Scoping the Service Mesh with discovery selectors
+:context: ossm-scoping-service-mesh-with-discoveryselectors
+
+{SMProductShortName} includes workloads that meet the following criteria:
+
+* The control plane has discovered the workload.
+* The workload has an Envoy proxy sidecar injected.
+
+By default, the control plane discovers workloads in all namespaces across the cluster, with the following results:
+
+* Each proxy instance receives configuration for all namespaces, including workloads not enrolled in the mesh.
+* Any workload with the appropriate pod or namespace injection label receives a proxy sidecar.
+
+In shared clusters, you might want to limit the scope of {SMProductShortName} to only certain namespaces. This approach is especially useful if multiple service meshes run in the same cluster.

modules/ossm-using-discoveryselectors-scope-service-mesh.adoc

@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+// install/ossm-installing-openshift-service-mesh.adoc
+
+:_mod-docs-content-type: Procedure
+[id="ossm-discoveryselectors-scope-service-mesh_{context}"]
+= Scoping a Service Mesh by using discovery selectors
+:context: ossm-discoveryselectors-scope-service-mesh
+
+If you know which namespaces to include in the {SMProductShortName}, configure `discoverySelectors` during or after installation by adding the required selectors to the `meshConfig.discoverySelectors` section of the `{istio}` resource. For example, configure {istio} to discover only namespaces labeled `istio-discovery=enabled`.
+
+.Prerequisites
+* The {SMProduct} operator is installed.
+* An {istio} CNI resource is created.
+
+.Procedure
+. Add a label to the namespace containing the {istio} control plane, for example, the `istio-system` system namespace.
++
+[source,terminal]
+----
+$ oc label namespace istio-system istio-discovery=enabled
+----
+
+. Modify the `{istio}` control plane resource to include a `discoverySelectors` section with the same label.
++
+[source,yaml]
+----
+kind: Istio
+apiVersion: sailoperator.io/v1alpha1
+metadata:
+  name: default
+spec:
+  namespace: istio-system
+  values:
+    meshConfig:
+      discoverySelectors:
+        - matchLabels:
+            istio-discovery: enabled
+----
+
+. Apply the Istio CR:
++
+[source,terminal]
+----
+$ oc apply -f istio.yaml
+----
+
+. Ensure that all namespaces that will contain workloads that are to be part of the {SMProductShortName} have both the `discoverySelector` label and, if needed, the appropriate {istio} injection label.
+
+[NOTE]
+====
+Discovery selectors help restrict the scope of a single {SMProductShortName} and are essential for limiting the control plane scope when you deploy multiple {istio} control planes in a single cluster.
+====
+