Merge pull request #60736 from rh-tokeefe/OSSM-4039

OSSM-4039: Refine content for adding services to a mesh

Author: bburt-rh

modules/ossm-about-adding-namespace.adoc

@@ -6,7 +6,7 @@
 [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.
+After installing the Operators and creating the `ServiceMeshControlPlane` resource, add one or more projects to the service mesh. 
 
 [NOTE]
 ====
@@ -21,4 +21,4 @@ You can add projects to an existing service mesh using either the {product-title
 
 * Creating the `ServiceMeshMember` resource in the project.
 
-If you choose to use the first method, then you must create the `ServiceMeshMemberRoll` resource.
+If you use the first method, then you must create the `ServiceMeshMemberRoll` resource.

modules/ossm-about-adding-projects-using-smm.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-create-mesh.adoc
+
+:_content-type: CONCEPT
+[id="ossm-about-adding-projects-using-smm_{context}"]
+= About adding projects using the ServiceMeshMember resource
+
+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. 
+ 
+The mesh administrator must grant each mesh user permission to reference the `ServiceMeshControlPlane` resource in the `ServiceMeshMember` resource. With this permission in place, a mesh user can add a project to a mesh even when that user does not have direct access rights for the service mesh project or the `ServiceMeshMemberRoll` resource. For more information, see Creating the {SMProductName} members.

modules/ossm-about-adding-projects-using-smmr.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-create-mesh.adoc
+
+:_content-type: CONCEPT
+[id="ossm-about-adding-projects-using-smmr_{context}"]
+= About adding projects using the ServiceMeshMemberRoll resource
+
+Using the `ServiceMeshMemberRoll` resource 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 following:
+** Adding or removing projects from the mesh using the `ServiceMeshMemberRoll` resource with the web console
+** Adding or removing projects from the mesh using the `ServiceMeshMemberRoll` resource with the CLI
+
+* Alternatively, to install a sample application called Bookinfo and add it to a `ServiceMeshMemberRoll` resource, see the Bookinfo example application tutorial.

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

@@ -4,9 +4,9 @@
 
 :_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
+= Adding or removing projects from the mesh using ServiceMeshMemberRoll resource with the CLI
 
-You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.
+You can add one or more projects to the mesh using the `ServiceMeshMemberRoll` resource with the CLI. You can add any number of projects, but a project can only belong to *one* mesh.
 
 The `ServiceMeshMemberRoll` resource is deleted when its corresponding `ServiceMeshControlPlane` resource is deleted.
 

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

@@ -4,13 +4,14 @@
 
 :_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
+= Adding or removing projects from the mesh using the ServiceMeshMemberRoll resource with the web console
 
-You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.
+You can add or remove projects from the mesh using the `ServiceMeshMemberRoll` resource with the {product-title} web console. You can add any number of projects, but a project can only belong to *one* mesh.
 
 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.

modules/ossm-add-project-using-label-selectors-cli.adoc

@@ -4,14 +4,14 @@
 
 :_content-type: PROCEDURE
 [id="ossm-adding-project-using-label-selectors-cli_{context}"]
-= Adding a project to the {SMProductShortName} using label selectors with the CLI 
+= Adding a project to the mesh using label selectors with the CLI 
 
 You can use label selectors to add a project to the {SMProductShortName} with the CLI.
 
 .Prerequisites
-* The deployment has an installed, verified {SMProductName} Operator.
+* You have installed the {SMProductName} Operator.
 * The deployment has an existing `ServiceMeshMemberRoll` resource.
-* You are logged in as a user with mesh admin privileges.
+* 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
 

modules/ossm-add-project-using-label-selectors-console.adoc

@@ -4,14 +4,14 @@
 
 :_content-type: PROCEDURE
 [id="ossm-adding-project-using-label-selectors-console_{context}"]
-= Adding a project to the {SMProductShortName} using label selectors with the web console
+= Adding a project to the mesh using label selectors with the web console
 
 You can use labels selectors to add a project to the {SMProductShortName} with the {product-title} web console.
 
 .Prerequisites
-* The deployment has an installed, verified {SMProductName} Operator.
+* You have installed the {SMProductName} Operator.
 * The deployment has an existing `ServiceMeshMemberRoll` resource.
-* You are logged in as a user with mesh admin privileges.
+* 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
 

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

@@ -4,15 +4,15 @@
 
 :_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
+= Adding a project to the mesh using the ServiceMeshMember resource with the CLI
 
-You can add one or more projects to the {SMProductShortName} from the CLI.
+You can add one or more projects to the mesh using the `ServiceMeshMember` resource with 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].
+* You have installed the {SMProductName} Operator.
+* You know the name of the `ServiceMeshControlPlane` resource and the name of the project it belongs to.
+* You know the 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 _Creating the {SMProductName} members_.
 
 .Procedure
 

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

@@ -4,15 +4,15 @@
 
 :_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
+= Adding a project to the mesh using the ServiceMeshMember resource with the web console
 
-You can add one or more projects to the {SMProductShortName} from the {product-title} web console.
+You can add one or more projects to the mesh using the `ServiceMeshMember` resource with the {product-title} 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].
+* You have installed the {SMProductName} Operator.
+* You know the name of the `ServiceMeshControlPlane` resource and the name of the project that the resource belongs to.
+* You know the 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 _Creating the {SMProductName} members_.
 
 .Procedure
 

service_mesh/v2x/ossm-create-mesh.adoc

@@ -6,19 +6,23 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-After installing the Operators and creating the `ServiceMeshControlPlane` resource, add one or more projects to the service mesh. 
+A project contains services; however, the services are only available if you add the project to the service mesh.
 
 include::modules/ossm-about-adding-namespace.adoc[leveloffset=+1]
 
 include::modules/ossm-member-roll-create.adoc[leveloffset=+1]
 
-include::modules/ossm-add-project-member-roll-resource-console.adoc[leveloffset=+1]
+include::modules/ossm-about-adding-projects-using-smmr.adoc[leveloffset=+1]
 
-include::modules/ossm-add-project-member-roll-resource-cli.adoc[leveloffset=+1]
+include::modules/ossm-add-project-member-roll-resource-console.adoc[leveloffset=+2]
 
-include::modules/ossm-adding-project-using-smm-resource-console.adoc[leveloffset=+1]
+include::modules/ossm-add-project-member-roll-resource-cli.adoc[leveloffset=+2]
 
-include::modules/ossm-adding-project-using-smm-resource-cli.adoc[leveloffset=+1]
+include::modules/ossm-about-adding-projects-using-smm.adoc[leveloffset=+1]
+
+include::modules/ossm-adding-project-using-smm-resource-console.adoc[leveloffset=+2]
+
+include::modules/ossm-adding-project-using-smm-resource-cli.adoc[leveloffset=+2]
 
 include::modules/ossm-about-adding-projects-using-label-selectors.adoc[leveloffset=+1]