Skip to content

Commit 792d2ff

Browse files
gabriel-rhgabriel-rh
authored
Merge pull request #58539 from rh-tokeefe/OSSM-3251
OSSM-3251: Add cluster-wide deployment to Service Mesh docs
2 parents 398afd3 + 7e5c9c5 commit 792d2ff

14 files changed

+330
-41
lines changed

‎modules/ossm-about-adding-namespace.adoc

Lines changed: 4 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -13,27 +13,12 @@ A project contains services; however, the services are only available if you add
1313
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.
1414
====
1515

16-
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:
16+
You can add projects to an existing service mesh using either the {product-title} web console or the CLI. There are three methods to add a project to a service mesh:
1717

1818
* Specifying the project name in the `ServiceMeshMemberRoll` resource.
1919
20-
* Creating the `ServiceMeshMember` resource in the project.
21-
22-
.ServiceMeshMemberRoll method
23-
24-
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.
20+
* Configuring label selectors in the `spec.labelSelectors` field of the `ServiceMeshMemberRoll` resource.
2521
26-
[NOTE]
27-
====
28-
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.
29-
====
30-
31-
* 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].
32-
33-
* 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.
34-
35-
.ServiceMeshMember method
36-
37-
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].
22+
* Creating the `ServiceMeshMember` resource in the project.
3823
39-
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].
24+
If you choose to use the first method, then you must create the `ServiceMeshMemberRoll` resource.

‎modules/ossm-about-adding-projects-using-label-selectors.adoc

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/create-mesh.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="ossm-about-adding-projects-using-label-selectors_{context}"]
7+
= About adding projects using label selectors
8+
9+
For cluster-wide deployments, you can use label selectors to add projects to the mesh. Label selectors specified in the `ServiceMeshMemberRoll` resource enable the {SMProductShortName} operator to add or remove namespaces to or from the mesh based on namespace labels. Unlike other standard {product-title} resources that you can use to specify a single label selector, you can use the `ServiceMeshMemberRoll` resource to specify multiple label selectors. If the labels for a namespace match any of the selectors specified in the `ServiceMeshMemberRoll` resource, then the namespace is included in the mesh.
10+
11+
[NOTE]
12+
====
13+
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.
14+
====

‎modules/ossm-about-control-plane-and-cluster-wide-deployment.adoc

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-create-smcp.adoc
3+
4+
:_content-type: CONCEPT
5+
[id="ossm-about-control-plane-and-cluster-wide-deployment_{context}"]
6+
= About control plane and cluster-wide deployments
7+
8+
A cluster-wide deployment contains a {SMProductShortName} Control Plane that monitors resources for an entire cluster. Monitoring resources for an entire cluster closely resembles Istio functionality in that the control plane uses a single query across all namespaces to monitor Istio and Kubernetes resources. As a result, cluster-wide deployments decrease the number of requests sent to the API server.
9+
10+
You can configure the {SMProductShortName} Control Plane for cluster-wide deployments using either the {product-title} web console or the CLI.

‎modules/ossm-about-smcp.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-create-smcp.adoc
3+
4+
:_content-type: CONCEPT
5+
[id="ossm-about-smcp_{context}"]
6+
= About ServiceMeshControlPlane
7+
8+
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.
9+
10+
[NOTE]
11+
====
12+
This basic installation is configured based on the default {product-title} settings and is not designed for production use. Use this default installation to verify your installation, and then configure your `ServiceMeshControlPlane` settings for your environment.
13+
====
14+
15+
[NOTE]
16+
====
17+
Red Hat OpenShift Service on AWS (ROSA) places additional restrictions on where you can create resources, and as a result, the default deployment does not work. See Installing {SMProductShortName} on Red Hat OpenShift Service on AWS for additional requirements before deploying your SMCP in a ROSA environment.
18+
====
19+
20+
[NOTE]
21+
====
22+
The {SMProductShortName} documentation uses `istio-system` as the example project, but you can deploy the service mesh to any project.
23+
====

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/installing-ossm.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ossm-adding-project-using-label-selectors-cli_{context}"]
7+
= Adding a project to the {SMProductShortName} using label selectors with the CLI
8+
9+
You can use label selectors to add a project to the {SMProductShortName} with the CLI.
10+
11+
.Prerequisites
12+
* The deployment has an installed, verified {SMProductName} Operator.
13+
* The deployment has an existing `ServiceMeshMemberRoll` resource.
14+
* You are logged in as a user with mesh admin privileges.
15+
16+
.Procedure
17+
18+
. Log in to the {product-title} CLI.
19+
20+
. Edit the `ServiceMeshMemberRoll` resource.
21+
+
22+
[source,terminal]
23+
----
24+
$ oc edit smmr -n <controlplane_project>
25+
----
26+
+
27+
The previous example uses `<controlplane_project>` as an example. You can deploy the {SMProductShortName} control plane to any project as long as it is separate from the project that contains your services.
28+
29+
. Modify the YAML file to include namespace label selectors in the `spec.memberSelectors` field of the `ServiceMeshMemberRoll` resource.
30+
+
31+
[NOTE]
32+
====
33+
Instead of using the `matchLabels` field, you can also use the `matchExpressions` field in the selector.
34+
====
35+
+
36+
[source,yaml]
37+
----
38+
apiVersion: maistra.io/v1
39+
kind: ServiceMeshMemberRoll
40+
metadata:
41+
name: default
42+
namespace: istio-system
43+
spec:
44+
memberSelectors: <1>
45+
- matchLabels: <2>
46+
mykey: myvalue <2>
47+
- matchLabels: <3>
48+
myotherkey: myothervalue <3>
49+
----
50+
<1> Contains the label selectors used to identify which project namespaces are included in the service mesh. If a project namespace has either label specified by the selectors, then the project namespace is included in the service mesh. The project namespace does not need both labels to be included.
51+
<2> Specifies all namespaces with the `mykey=myvalue` label. When the selector identifies a match, the project namespace is added to the service mesh.
52+
<3> Specifies all namespaces with the `myotherkey=myothervalue` label. When the selector identifies a match, the project namespace is added to the service mesh.

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/ossm-create-mesh.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ossm-adding-project-using-label-selectors-console_{context}"]
7+
= Adding a project to the {SMProductShortName} using label selectors with the web console
8+
9+
You can use labels selectors to add a project to the {SMProductShortName} with the {product-title} web console.
10+
11+
.Prerequisites
12+
* The deployment has an installed, verified {SMProductName} Operator.
13+
* The deployment has an existing `ServiceMeshMemberRoll` resource.
14+
* You are logged in as a user with mesh admin privileges.
15+
16+
.Procedure
17+
18+
. Log in to the {product-title} web console.
19+
20+
. Navigate to *Operators* -> *Installed Operators*.
21+
22+
. Click the *Project* menu, and from the drop-down list, select the project where your `ServiceMeshMemberRoll` resource is deployed. For example, *istio-system*.
23+
24+
. Click the {SMProductName} Operator.
25+
26+
. Click the *Istio Service Mesh Member Roll* tab.
27+
28+
. Click *Create ServiceMeshMember Roll*.
29+
30+
. Accept the default name for the `ServiceMeshMemberRoll`.
31+
32+
. In the *Labels* field, enter key-value pairs to define the labels that identify which namespaces to include in the service mesh. If a project namespace has either label specified by the selectors, then the project namespace is included in the service mesh. You do not need to include both labels.
33+
+
34+
For example, entering `mykey=myvalue` includes all namespaces with this label as part of the mesh. When the selector identifies a match, the project namespace is added to the service mesh.
35+
+
36+
Entering `myotherkey=myothervalue` includes all namespaces with this label as part of the mesh. When the selector identifies a match, the project namespace is added to the service mesh.
37+
38+
. Click *Create*.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[id="ossm-adding-project-using-smm-resource-console_{context}"]
77
= Adding a project to the service mesh using the ServiceMeshMember resource with the web console
88

9-
You can add one or more projects to the {SMProductShortName} from the web console.
9+
You can add one or more projects to the {SMProductShortName} from the {product-title} web console.
1010

1111
.Prerequisites
1212
* An installed, verified {SMProductName} Operator.

‎modules/ossm-customize-smmr-cluster-wide.adoc

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
//
2+
This module is included in the following assemblies:
3+
* service_mesh/v2x/ossm-create-smcp.adoc
4+
//
5+
6+
:_content-type: CONCEPT
7+
[id="ossm-customize-smrr-cluster-wide_{context}"]
8+
= Customizing the member roll for a cluster-wide mesh
9+
10+
In cluster-wide mode, when you create the `ServiceMeshControlPlane` resource, the `ServiceMeshMemberRoll` resource is also created. You can modify the `ServiceMeshMemberRoll` resource after it gets created. After you modify the resource, the {SMProductShortName} operator no longer changes it. If you modify the `ServiceMeshMemberRoll` resource by using the {product-title} web console, accept the prompt to overwrite the modifications.
11+
12+
Alternatively, you can create a `ServiceMeshMemberRoll` resource before deploying the `ServiceMeshControlPlane` resource. When you create the `ServiceMeshControlPlane` resource, the {SMProductShortName} Operator will not modify the `ServiceMeshMemberRoll`.
13+
14+
[NOTE]
15+
====
16+
The `ServiceMeshMemberRoll` resource name must be named `default` and must be created in the same project namespace as the `ServiceMeshControlPlane` resource.
17+
====
18+
19+
There are two ways to add a namespace to the mesh. You can either add the namespace by specifying its name in the `spec.members` list, or configure a set of namespace label selectors to include or exclude namespaces based on their labels.
20+
21+
[NOTE]
22+
====
23+
Regardless of how members are specified in the `ServiceMeshMemberRoll` resource, you can also add members to the mesh by creating the `ServiceMeshMember` resource in each namespace.
24+
====

‎modules/ossm-deploy-cluster-wide-control-plane-cli.adoc

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
//
2+
This module is included in the following assemblies:
3+
* service_mesh/v2x/ossm-create-smcp.adoc
4+
//
5+
:_content-type: PROCEDURE
6+
[id="ossm-deploy-cluster-wide-control-plane-cli_{context}"]
7+
= Configuring the control plane for cluster-wide deployment with the CLI
8+
9+
You can configure the `ServiceMeshControlPlane` resource for cluster-wide deployment using the CLI. In this example, `istio-system` is the name of the Service Mesh control plane namespace.
10+
11+
.Prerequisites
12+
13+
* The {SMProductName} Operator is installed.
14+
* You have access to the OpenShift CLI (`oc`).
15+
16+
.Procedure
17+
18+
. Log in to the {product-title} CLI as a user with the `cluster-admin` role. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role.
19+
+
20+
[source,terminal]
21+
----
22+
$ oc login --username=<NAMEOFUSER> https://<HOSTNAME>:6443
23+
----
24+
+
25+
. Create a project named `istio-system`.
26+
+
27+
[source,terminal]
28+
----
29+
$ oc new-project istio-system
30+
----
31+
32+
. Create a `ServiceMeshControlPlane` file named `istio-installation.yaml` using the following example.
33+
+
34+
.Example version {MaistraVersion} istio-installation.yaml
35+
[source,yaml, subs="attributes,verbatim"]
36+
----
37+
apiVersion: maistra.io/v2
38+
kind: ServiceMeshControlPlane
39+
metadata:
40+
name: basic
41+
namespace: istio-system
42+
spec:
43+
version: v{MaistraVersion}
44+
mode: ClusterWide
45+
----
46+
47+
. Run the following command to deploy the {SMProductShortName} control plane, where `<istio_installation.yaml>` includes the full path to your file.
48+
+
49+
[source,terminal]
50+
----
51+
$ oc create -n istio-system -f <istio_installation.yaml>
52+
----
53+
+
54+
. To monitor the progress of the pod deployment, run the following command:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc get pods -n istio-system -w
59+
----
60+
+
61+
You should see output similar to the following example:
62+
+
63+
.Example output
64+
[source,terminal]
65+
----
66+
NAME READY STATUS RESTARTS AGE
67+
grafana-b4d59bd7-mrgbr 2/2 Running 0 65m
68+
istio-egressgateway-678dc97b4c-wrjkp 1/1 Running 0 108s
69+
istio-ingressgateway-b45c9d54d-4qg6n 1/1 Running 0 108s
70+
istiod-basic-55d78bbbcd-j5556 1/1 Running 0 108s
71+
jaeger-67c75bd6dc-jv6k6 2/2 Running 0 65m
72+
kiali-6476c7656c-x5msp 1/1 Running 0 43m
73+
prometheus-58954b8d6b-m5std 2/2 Running 0 66m
74+
----

‎modules/ossm-deploy-cluster-wide-control-plane-console.adoc

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/ossm-create-smcp.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ossm-deploy-cluster-wide-control-plane-console_{context}"]
7+
= Configuring the control plane for cluster-wide deployment with the web console
8+
9+
You can configure the `ServiceMeshControlPlane` resource for cluster-wide deployment using the {product-title} web console. In this example, `istio-system` is the name of the {SMProductShortName} control plane project.
10+
11+
.Prerequisites
12+
13+
* The {SMProductName} Operator is installed.
14+
* You are logged in using an account with the `cluster-admin` role, or if you use {product-dedicated} with the `dedicated-admin` role.
15+
16+
.Procedure
17+
18+
. Create a project named `istio-system`.
19+
+
20+
.. Navigate to *Home* -> *Projects*.
21+
+
22+
.. Click *Create Project*.
23+
+
24+
.. In the *Name* field, enter `istio-system`. The `ServiceMeshControlPlane` resource must be installed in a project that is separate from your microservices and Operators.
25+
+
26+
These steps use `istio-system` as an example. You can deploy the {SMProductShortName} control plane to any project as long as it is separate from the project that contains your services.
27+
+
28+
.. Click *Create*.
29+
30+
. Navigate to *Operators* -> *Installed Operators*.
31+
32+
. Click the {SMProductName} Operator, then click *Istio Service Mesh Control Plane*.
33+
34+
. On the *Istio Service Mesh Control Plane* tab, click *Create ServiceMeshControlPlane*.
35+
36+
. Click *YAML view*. The version of the {SMProductShortName} control plane determines the features available regardless of the version of the Operator.
37+
38+
. Modify the `spec.mode` field of the YAML file to specify `ClusterWide`.
39+
+
40+
.Example version {MaistraVersion} istio-installation.yaml
41+
+
42+
[source,yaml]
43+
----
44+
apiVersion: maistra.io/v2
45+
kind: ServiceMeshControlPlane
46+
metadata:
47+
name: basic
48+
namespace: istio-system
49+
spec:
50+
version: v{MaistraVersion}
51+
mode: ClusterWide
52+
----
53+
54+
. Click *Create*. The Operator creates pods, services, and {SMProductShortName} control plane components based on your configuration parameters. The operator also creates the `ServiceMeshMemberRoll` if it does not exist as part of the default configuration.
55+
56+
. To verify that the control plane installed correctly, click the *Istio Service Mesh Control Plane* tab.
57+
+
58+
.. Click the name of the new `ServiceMeshControlPlane` object.
59+
+
60+
.. Click the *Resources* tab to see the {SMProductName} control plane resources that the Operator created and configured.

0 commit comments

Comments
 (0)