openshift-docs/modules/ossm-member-roll-create.adoc

// Module included in the following assemblies:
//
// * service_mesh/v1x/installing-ossm.adoc
// * service_mesh/v2x/installing-ossm.adoc

[id="ossm-member-roll-create_{context}"]
= Creating the {ProductName} member roll

The `ServiceMeshMemberRoll` lists the projects belonging to the control plane. Only projects listed in the `ServiceMeshMemberRoll` are affected by the control plane. A project does not belong to a service mesh until you add it to the member roll for a particular control plane deployment.

You must create a `ServiceMeshMemberRoll` resource named `default` in the same project as the `ServiceMeshControlPlane`.


[NOTE]
====
The member projects are only updated if the {ProductShortName} control plane installation succeeds.
====

[id="ossm-member-roll-create-console_{context}"]
== Creating the member roll from the web console

Follow this procedure to add one or more projects to the {ProductShortName} member roll by using the web console.

.Prerequisites
* An installed, verified {ProductName} Operator.
* Location of the installed `ServiceMeshControlPlane`.
* List of existing projects to add to the service mesh.

.Procedure

. If you do not already have projects for your mesh, or you are starting from scratch, create a project. It must be different from `istio-system`.

.. Navigate to *Home* -> *Projects*.

.. Enter a name in the *Name* field.

.. Click *Create*.

. Log in to the {product-title} web console.

. Navigate to *Operators* -> *Installed Operators*.

. Click the *Project* menu and choose the project where your `ServiceMeshControlPlane` is deployed from the list, for example `istio-system`.

. Click the {ProductName} Operator.

. Click the *All Instances* tab.

. Click *Create New*, and then select *Create Istio Service Mesh Member Roll*.

+
[NOTE]
====
It can take a short time for the Operator to finish copying the resources, therefore you may need to refresh the screen to see the *Create Istio Service Mesh Member Roll* button.
====

. On the *Create Service Mesh Member Roll* page, modify the YAML to add your projects as members.  You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.

. Click *Create* to save the Service Mesh Member Roll.


[id="ossm-member-roll-create-cli_{context}"]
== Creating the member roll from the CLI

Follow this procedure to add a project to the `ServiceMeshMemberRoll` from the command line.

.Prerequisites

* An installed, verified {ProductName} Operator.
* Location of the installed `ServiceMeshControlPlane`.
* List of projects to add to the service mesh.
* Access to the OpenShift CLI (`oc`).

.Procedure

. Log in to the {product-title} CLI.
+
[source,terminal]
----
$ oc login
----
+
. Create a `ServiceMeshMemberRoll` resource in the same project as the `ServiceMeshControlPlane` resource, in our example that is `istio-system`. The resource must be named `default`.
+
[source,terminal]
----
$ oc create -n istio-system -f servicemeshmemberroll-default.yaml
----
+
.Example servicemeshmemberroll-default.yaml

[source,yaml]
----
apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
  name: default
  namespace: istio-system
spec:
  members:
    # a list of projects joined into the service mesh
    - your-project-name
    - another-project-name
----
+
. Modify the default YAML to add your projects as `members`.  You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.

[id="ossm-member-roll-create-member_{context}"]
== Creating the {ProductName} members

`ServiceMeshMember` resources can be created by service mesh users who don't have privileges to add members to the `ServiceMeshMemberRoll` directly. While project administrators are automatically given permission to create the `ServiceMeshMember` resource in their project, they cannot point it to any `ServiceMeshControlPlane` until the service mesh administrator explicitly grants access to the service mesh. Administrators can grant users permissions to access the mesh by granting them the `mesh-user` user role, for example:

----
$ oc policy add-role-to-user -n <control_plane_namespace> --role-namespace <control_plane_namespace> mesh-user <user_name>.
----

Administrators can modify the `mesh user` role binding in the control plane project to specify the users and groups that are granted access. The `ServiceMeshMember` adds the project to the `ServiceMeshMemberRoll` within the control plane project that it references.

[source,yaml]
----
apiVersion: maistra.io/v1
kind: ServiceMeshMember
metadata:
  name: default
spec:
  controlPlaneRef:
    namespace: <control_plane_namespace>
    name: minimal-install
----

The mesh-users role binding is created automatically after the administrator creates the `ServiceMeshControlPlane` resource. An administrator can use the following command to add a role to a user.

----
$ oc policy add-role-to-user
----

The administrator can also create the `mesh-user` role binding before the administrator creates the `ServiceMeshControlPlane` resource. For example, the administrator can create it in the same `oc apply` operation as the `ServiceMeshControlPlane` resource.

This example adds a role binding for `alice`:

[source,yaml]
----
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: <control_plane_namespace>
  name: mesh-users
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: mesh-user
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: alice
----