Merge pull request #59177 from rh-tokeefe/OSSM-3796A

OSSM-3796: Refactor adding services to a mesh

modules/ossm-about-adding-namespace.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/installing-ossm.adoc
+
+:_content-type: CONCEPT
+[id="ossm-about-adding-namespace_{context}"]
+= About adding projects to a service mesh
+
+A project contains services; however, the services are only available if you add the project to the service mesh.
+
+[NOTE]
+====
+In {product-title}, a project is essentially a Kubernetes namespace with additional annotations, such as the range of user IDs that can be used in the project. Typically, the {product-title} web console uses the term project, and the CLI uses the term namespace, but the terms are essentially synonymous.
+====
+
+You can add projects to an existing service mesh using either the {product-title} web console or the CLI. There are two methods to add a project to a service mesh:
+
+* Specifying the project name in the `ServiceMeshMemberRoll` resource.
+
+* Creating the `ServiceMeshMember` resource in the project.
+
+.ServiceMeshMemberRoll method
+
+This is the simplest way to add a project to a service mesh. To add a project, specify the project name in the `spec.members` field of the `ServiceMeshMemberRoll` resource. The `ServiceMeshMemberRoll` resource specifies which projects are controlled by the `ServiceMeshControlPlane` resource. 
+
+[NOTE]
+====
+Adding projects using this method requires the user to have the `update servicemeshmemberrolls` and the `update pods` privileges in the project that is being added.
+====
+
+* If you already have an application, workload, or service to add to the service mesh, see the instructions for adding or removing projects from the service mesh using the `ServiceMeshMemberRoll` resource with the xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-add-project-member-roll-recourse-console_ossm-create-mesh[web console] or with the xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-add-project-member-roll-resource-cli_ossm-create-mesh[CLI]. 
+
+* Alternatively, to install a sample application called Bookinfo and add it to a `ServiceMeshMemberRoll` resource, see xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-tutorial-bookinfo-overview_ossm-create-mesh[Bookinfo example application] tutorial.
+
+.ServiceMeshMember method
+
+A `ServiceMeshMember` resource provides a way to add a project to a service mesh without modifying the `ServiceMeshMemberRoll` resource. To add a project, create a `ServiceMeshMember` resource in the project that you want to add to the service mesh. When the {SMProductShortName} Operator processes the `ServiceMeshMember` object, the project appears in the `status.members` list of the `ServiceMeshMemberRoll` resource. Then, the services that reside in the project are made available to the mesh. For more information, see the instructions for adding projects to the service mesh using the `ServiceMeshMember` resource with the xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-adding-project-using-smm-resource-console_ossm-create-mesh[web console] or with the xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-adding-project-using-smm-resource-cli_ossm-create-mesh[CLI].
+
+The mesh administrator must grant each mesh user permission to reference the `ServiceMeshControlPlane` resource in the `ServiceMeshMember` resource. With this permission in place, this method of adding projects to a mesh can be used when the mesh user does not have direct access rights for the service mesh project or the `ServiceMeshMemberRoll` resource. For more information, see xref:../../service_mesh/v2x/ossm-profiles-users.html#ossm-members_ossm-profiles-users[Creating the {SMProductName} members].

modules/ossm-add-project-member-roll-resource-cli.adoc

@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/installing-ossm.adoc
+
+:_content-type: PROCEDURE
+[id="ossm-add-project-member-roll-resource-cli_{context}"]
+= Adding or removing projects from the service mesh using ServiceMeshMemberRoll resource with the CLI
+
+You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.
+
+The `ServiceMeshMemberRoll` resource is deleted when its corresponding `ServiceMeshControlPlane` resource is deleted.
+
+.Prerequisites
+
+* An installed, verified {SMProductName} Operator.
+* An existing `ServiceMeshMemberRoll` resource.
+* The name of the project with the `ServiceMeshMemberRoll` resource.
+* The names of the projects you want to add or remove from the mesh.
+* Access to the OpenShift CLI (`oc`).
+
+.Procedure
+
+. Log in to the {product-title} CLI.
+
+. Edit the `ServiceMeshMemberRoll` resource.
++
+[source,terminal]
+----
+$ oc edit smmr -n <controlplane-namespace>
+----
+
+. Modify the YAML to add or remove projects as members. You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.
++
+.Example servicemeshmemberroll-default.yaml
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshMemberRoll
+metadata:
+  name: default
+  namespace: istio-system #control plane project
+spec:
+  members:
+    # a list of projects joined into the service mesh
+    - your-project-name
+    - another-project-name
+----
+
+. Save the file and exit the editor. 

modules/ossm-add-project-member-roll-resource-console.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/installing-ossm.adoc
+
+:_content-type: PROCEDURE
+[id="ossm-add-project-member-roll-recourse-console_{context}"]
+= Adding or removing projects from the service mesh using ServiceMeshMemberRoll resource with the web console
+
+You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.
+
+The `ServiceMeshMemberRoll` resource is deleted when its corresponding `ServiceMeshControlPlane` resource is deleted.
+
+.Prerequisites
+* An installed, verified {SMProductName} Operator.
+* An existing `ServiceMeshMemberRoll` resource.
+* The name of the project with the `ServiceMeshMemberRoll` resource.
+* The names of the projects you want to add or remove from the mesh.
+
+.Procedure
+
+. Log in to the {product-title} web console.
+
+. Navigate to *Operators* -> *Installed Operators*.
+
+. Click the *Project* menu and choose the project where your `ServiceMeshControlPlane` resource is deployed from the list. For example `istio-system`.
+
+. Click the {SMProductName} Operator.
+
+. Click the *Istio Service Mesh Member Roll* tab.
+
+. Click the `default` link.
+
+. Click the YAML tab.
+
+. Modify the YAML to add projects as members (or delete them to remove existing members). You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.
++
+.Example servicemeshmemberroll-default.yaml
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshMemberRoll
+metadata:
+  name: default
+  namespace: istio-system #control plane project
+spec:
+  members:
+    # a list of projects joined into the service mesh
+    - your-project-name
+    - another-project-name
+----
+
+. Click *Save*.
+
+. Click *Reload*.

modules/ossm-adding-project-using-smm-resource-cli.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/ossm-create-mesh.adoc
+
+:_content-type: PROCEDURE
+[id="ossm-adding-project-using-smm-resource-cli_{context}"]
+= Adding a project to the service mesh using the ServiceMeshMember resource with the CLI
+
+You can add one or more projects to the {SMProductShortName} from the CLI.
+
+.Prerequisites
+* An installed, verified {SMProductName} Operator.
+* Name of the `ServiceMeshControlPlane` resource and the name of the project it belongs to.
+* Name of the project you want to add to the mesh.
+* A service mesh administrator must explicitly grant access to the service mesh. Administrators can grant users permissions to access the mesh by assigning them the `mesh-user` `Role` using a `RoleBinding` or `ClusterRoleBinding`. For more information, see xref:../../service_mesh/v2x/ossm-profiles-users.html#ossm-members_ossm-profiles-users[Creating the {SMProductName} members].
+
+.Procedure
+
+. Log in to the {product-title} CLI.
+
+. Create the YAML file for the `ServiceMeshMember` manifest. The manifest adds the `my-application` project to the service mesh that was created by the `ServiceMeshControlPlane` resource deployed in the `istio-system` namespace:
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshMember
+metadata:
+  name: default
+  namespace: my-application
+spec:
+  controlPlaneRef:
+    namespace: istio-system
+    name: basic
+----
+
+. Apply the YAML file to create the `ServiceMeshMember` resource:
++
+[source,terminal]
+----
+$ oc apply -f <file-name>
+----
+
+. After creating the `ServiceMeshMember` resource, verify that the namespace is part of the mesh. Confirm the that the value `True` appears in the `READY` column when you run the following command:
++
+[source,terminal]
+----
+$ oc get smm default -n my-application
+----
++
+Alternatively, if you can access the `ServiceMeshMemberRoll` resource, you can also confirm that the `my-application` namespace is displayed in the `status.members` and `status.configuredMembers` fields of the `ServiceMeshMemberRoll` resource.

modules/ossm-adding-project-using-smm-resource-console.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/ossm-create-mesh.adoc
+
+:_content-type: PROCEDURE
+[id="ossm-adding-project-using-smm-resource-console_{context}"]
+= Adding a project to the service mesh using the ServiceMeshMember resource with the web console
+
+You can add one or more projects to the {SMProductShortName} from the web console.
+
+.Prerequisites
+* An installed, verified {SMProductName} Operator.
+* Name of the `ServiceMeshControlPlane` resource and the name of the project that the resource belongs to.
+* Name of the project you want to add to the mesh.
+* A service mesh administrator must explicitly grant access to the service mesh. Administrators can grant users permissions to access the mesh by assigning them the `mesh-user` `Role` using a `RoleBinding` or `ClusterRoleBinding`. For more information, see xref:../../service_mesh/v2x/ossm-profiles-users.html#ossm-members_ossm-profiles-users[Creating the {SMProductName} members].
+
+.Procedure
+
+. Log in to the {product-title} web console.
+
+. Navigate to *Operators* -> *Installed Operators*.
+
+. Click the *Project* menu and choose the project that you want to add to the mesh from the drop-down list. For example, `istio-system`.
+
+. Click the {SMProductName} Operator.
+
+. Click the *Istio Service Mesh Member* tab.
+
+. Click *Create ServiceMeshMember*
+
+. Accept the default name for the `ServiceMeshMember`.
+
+. Click to expand *ControlPlaneRef*. 
+
+. In the *Namespace* field, select the project that the `ServiceMeshControlPlane` resource belongs to. For example, `istio-system`. 
+
+. In the *Name* field, enter the name of the `ServiceMeshControlPlane` resource that this namespace belongs to. For example, `basic`.  
+
+. Click *Create*.
+
+. Confirm the `ServiceMeshMember` resource was created, and that the project was added to the mesh. Click the resource name; for example, `default`. View the *Conditions* section shown at the end of the screen. Confirm that the `Status` of the `Reconciled` and `Ready` conditions is `True`. If the `Status` is `False`, see the `Reason` and `Message` columns for more information.

service_mesh/v2x/ossm-create-mesh.adoc

@@ -6,18 +6,19 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-After installing the Operators and `ServiceMeshControlPlane` resource, add applications, workloads, or services to your mesh by creating a `ServiceMeshMemberRoll` resource and specifying the namespaces where your content is located. If you already have an application, workload, or service to add to a `ServiceMeshMemberRoll` resource, use the following steps. Or, to install a sample application called Bookinfo and add it to a  `ServiceMeshMemberRoll` resource, skip to the tutorial for installing the xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-tutorial-bookinfo-overview_ossm-create-mesh[Bookinfo example application] to see how an application works in {SMProductName}.
+After installing the Operators and creating the `ServiceMeshControlPlane` resource, add one or more projects to the service mesh. 
 
-The items listed in the `ServiceMeshMemberRoll` resource are the applications and workflows that are managed by the `ServiceMeshControlPlane` resource. The control plane, which includes the {SMProductShortName} Operators, Istiod, and `ServiceMeshControlPlane`, and the data plane, which includes applications and Envoy proxy, must be in separate namespaces.
-
-[NOTE]
-====
-After you add the namespace to the `ServiceMeshMemberRoll`, access to services or pods in that namespace will not be accessible to callers outside the service mesh.
-====
+include::modules/ossm-about-adding-namespace.adoc[leveloffset=+1]
 
 include::modules/ossm-member-roll-create.adoc[leveloffset=+1]
 
-include::modules/ossm-member-roll-modify.adoc[leveloffset=+1]
+include::modules/ossm-add-project-member-roll-resource-console.adoc[leveloffset=+1]
+
+include::modules/ossm-add-project-member-roll-resource-cli.adoc[leveloffset=+1]
+
+include::modules/ossm-adding-project-using-smm-resource-console.adoc[leveloffset=+1]
+
+include::modules/ossm-adding-project-using-smm-resource-cli.adoc[leveloffset=+1]
 
 include::modules/ossm-tutorial-bookinfo-overview.adoc[leveloffset=+1]
 

service_mesh/v2x/ossm-create-smcp.adoc

@@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can deploy a basic installation of the `ServiceMeshControlPlane`(SMCP) by using either the {product-title} web console or from the command line using the `oc` client tool.
+The control plane includes Istiod, Ingress and Egress Gateways, and other components, such as Kiali and Jaeger. The control plane must be deployed in a separate namespace than the {SMProductShortName} Operators and the data plane applications and services. You can deploy a basic installation of the `ServiceMeshControlPlane`(SMCP) from the {product-title} web console or the command line using the `oc` client tool.
 
 [NOTE]
 ====
@@ -46,4 +46,4 @@ include::modules/ossm-install-rosa.adoc[leveloffset=+1]
 
 == Next steps
 
-* Create a `ServiceMeshMemberRoll` resource to specify the namespaces associated with the {SMProductShortName}. For more information, see xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-create-mesh[Adding services to a service mesh].
+* Add a project to the {SMProductShortName} so that applications can be made available. For more information, see xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-create-mesh[Adding services to a service mesh].