Merge pull request #67896 from mburke5678/service-mesh-fix-errors

mburke5678 · web-flow · commit 83bd2dc2c798 · 2024-03-28T15:09:48.000-04:00
Service Mesh docs fixes during ROSA review
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -3804,7 +3804,7 @@ Topics:
     File: ossm-about
   - Name: Service Mesh 2.x release notes
     File: servicemesh-release-notes
-  - Name: Service Mesh architecture
+  - Name: Understanding Service Mesh
     File: ossm-architecture
   - Name: Service Mesh deployment models
     File: ossm-deployment-models
diff --git a/modules/distr-tracing-config-security-ossm-cli.adoc b/modules/distr-tracing-config-security-ossm-cli.adoc
@@ -31,11 +31,11 @@ $ oc login https://<HOSTNAME>:6443
 $ oc project istio-system
 ----
 +
-. Run the following command to edit the Jaeger custom resource file, where `jaeger.yaml` is the name of your Jaeger custom resource.
+. Run the following command to edit the Jaeger custom resource file:
 +
 [source,terminal]
 ----
-$ oc edit -n tracing-system -f jaeger.yaml
+$ oc edit -n openshift-distributed-tracing -f jaeger.yaml
 ----
 +
 . Edit the `Jaeger` custom resource file to add the `htpasswd` configuration as shown in the following example.
@@ -78,16 +78,9 @@ spec:
       readOnly: true
 ----
 +
-. Run the following command to apply your changes, where <jaeger.yaml> is the name of your Jaeger custom resource.
-+
-[source,terminal]
-----
-$ oc apply -n tracing-system -f <jaeger.yaml>
-----
-+
 . Run the following command to watch the progress of the pod deployment:
 +
 [source,terminal]
 ----
-$ oc get pods -n tracing-system -w
+$ oc get pods -n openshift-distributed-tracing
 ----
diff --git a/modules/distr-tracing-config-security-ossm-web.adoc b/modules/distr-tracing-config-security-ossm-web.adoc
@@ -19,7 +19,7 @@ You can modify the Jaeger resource to configure {JaegerShortName} security for u
 
 . Log in to the {product-title} web console as a user with the `cluster-admin` role.
 
-. Navigate to Operators → Installed Operators.
+. Navigate to *Operators* -> *Installed Operators*.
 
 . Click the *Project* menu and select the project where your `ServiceMeshControlPlane` resource is deployed from the list, for example `istio-system`.
 
@@ -69,6 +69,7 @@ spec:
     - mountPath: /etc/pki/ca-trust/extracted/pem/
       name: trusted-ca-bundle
       readOnly: true
+# ...
 ----
 +
 . Click *Save*.
diff --git a/modules/distr-tracing-config-storage.adoc b/modules/distr-tracing-config-storage.adoc
@@ -696,9 +696,9 @@ spec:
 
 .Prerequisites
 
-* {product-title} 4.7
-* {logging-title} 5.2
-* The Elasticsearch node and the Jaeger instances must be deployed in the same namespace.  For example, `tracing-system`.
+* The {SMProductName} Operator is installed.
+* The {logging-title} is installed with default configuration in your cluster.
+* The Elasticsearch node and the Jaeger instances must be deployed in the same namespace. For example, `tracing-system`.
 
 You enable certificate management by setting `spec.storage.elasticsearch.useCertManagement` to `true` in the Jaeger custom resource.
 
diff --git a/modules/ossm-add-project-member-roll-resource-cli.adoc b/modules/ossm-add-project-member-roll-resource-cli.adoc
@@ -6,7 +6,7 @@
 [id="ossm-add-project-member-roll-resource-cli_{context}"]
 = Adding or removing projects from the mesh using ServiceMeshMemberRoll resource with the CLI
 
-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.
+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.
 
@@ -29,7 +29,7 @@ The `ServiceMeshMemberRoll` resource is deleted when its corresponding `ServiceM
 $ 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.
+. 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]
diff --git a/modules/ossm-add-project-member-roll-resource-console.adoc b/modules/ossm-add-project-member-roll-resource-console.adoc
@@ -6,7 +6,7 @@
 [id="ossm-add-project-member-roll-recourse-console_{context}"]
 = Adding or removing projects from the mesh using the ServiceMeshMemberRoll resource with the web console
 
-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.
+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.
 
@@ -33,7 +33,7 @@ The `ServiceMeshMemberRoll` resource is deleted when its corresponding `ServiceM
 
 . 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.
+. 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]
diff --git a/modules/ossm-adding-project-using-smm-resource-cli.adoc b/modules/ossm-adding-project-using-smm-resource-cli.adoc
@@ -40,11 +40,43 @@ spec:
 $ 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:
+.Verification
+
+* Verify that the namespace is part of the mesh by running the following command. Confirm the that the value `True` appears in the `READY` column.
 +
 [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.
+.Example output
+[source,terminal]
+----
+NAME      CONTROL PLANE        READY   AGE
+default   istio-system/basic   True    2m11s
+----
+
+* Alternatively, view the `ServiceMeshMemberRoll` resource to confirm that the `my-application` namespace is displayed in the `status.members` and `status.configuredMembers` fields of the `ServiceMeshMemberRoll` resource.
++
+[source,terminal]
+----
+$ oc describe smmr default -n istio-system
+----
++
+.Example output
+[source,terminal]
+----
+Name:         default
+Namespace:    istio-system
+Labels:       <none>
+# ...
+Status:
+# ...
+  Configured Members:
+    default
+    my-application
+# ...
+  Members:
+    default
+    my-application
+----
diff --git a/modules/ossm-adding-project-using-smm-resource-console.adoc b/modules/ossm-adding-project-using-smm-resource-console.adoc
@@ -38,4 +38,12 @@ You can add one or more projects to the mesh using the `ServiceMeshMember` resou
 
 . 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.
+.Verification
+
+. Confirm the `ServiceMeshMember` resource was created and that the project was added to the mesh by using the following steps:
+
+.. 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.
diff --git a/modules/ossm-architecture.adoc b/modules/ossm-architecture.adoc
@@ -12,7 +12,7 @@ image::ossm-architecture.png[Service Mesh architecture image]
 At a high level, {SMProductName} consists of a data plane and a control plane
 
 The *data plane* is a set of intelligent proxies, running alongside application containers in a pod, that intercept and control all inbound and outbound network communication between microservices in the service mesh.
-The data plane is implemented in such a way that it intercepts all inbound (ingress) and outbound (egress) network traffic. The Istio data plane is composed of Envoy containers running along side application containers in a pod. The Envoy container acts as a proxy, controlling all network communication into and out of the pod.
+The data plane is implemented in such a way that it intercepts all inbound (ingress) and outbound (egress) network traffic. The Istio data plane consists of Envoy containers running along side application containers in a pod. The Envoy container acts as a proxy, controlling all network communication into and out of the pod.
 
 * *Envoy proxies* are the only Istio components that interact with data plane traffic. All incoming (ingress) and outgoing (egress) network traffic between services flows through the proxies. The Envoy proxy also collects all metrics related to services traffic within the mesh. Envoy proxies are deployed as sidecars, running in the same pod as services. Envoy proxies are also used to implement mesh gateways.
 
diff --git a/modules/ossm-config-operator-infrastructure-node.adoc b/modules/ossm-config-operator-infrastructure-node.adoc
@@ -37,6 +37,14 @@ $ oc -n openshift-operators edit subscription <name> <1>
 +
 [source,yaml]
 ----
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  labels:
+    operators.coreos.com/servicemeshoperator.openshift-operators: ""
+  name: servicemeshoperator
+  namespace: openshift-operators
+# ...
 spec:
   config:
     nodeSelector: <1>
@@ -50,4 +58,4 @@ spec:
       value: reserved
 ----
 <1> Ensures that the operator pod is only scheduled on an infrastructure node.
-<2> Ensures that the pod is accepted by the infrastructure node.
+<2> Ensures that the pod is accepted by the infrastructure node.
diff --git a/modules/ossm-control-plane-cli.adoc b/modules/ossm-control-plane-cli.adoc
@@ -1,6 +1,7 @@
-// This module is included in the following assemblies:
-//
-// * service_mesh/v2x/ossm-create-smcp.adoc
+////
+This module is included in the following assemblies:
+* service_mesh/v2x/ossm-create-smcp.adoc
+////
 
 :_mod-docs-content-type: PROCEDURE
 [id="ossm-control-plane-deploy-cli_{context}"]
diff --git a/modules/ossm-control-plane-web.adoc b/modules/ossm-control-plane-web.adoc
@@ -40,11 +40,19 @@ These steps use `istio-system` as an example, but you can deploy your {SMProduct
 
 . On the *Istio Service Mesh Control Plane* tab, click *Create ServiceMeshControlPlane*.
 
-. On the *Create ServiceMeshControlPlane* page, accept the default {SMProductShortName} control plane version to take advantage of the features available in the most current version of the product. The version of the control plane determines the features available regardless of the version of the Operator.
+. On the *Create ServiceMeshControlPlane* page:
 +
-.. Click *Create*. The Operator creates pods, services, and {SMProductShortName} control plane components based on your configuration parameters. You can configure `ServiceMeshControlPlane` settings later.
+--
+.. Accept the default {SMProductShortName} control plane version to take advantage of the features available in the most current version of the product. The version of the control plane determines the features available regardless of the version of the Operator.
+
+.. Click *Create*. 
+--
 +
-. To verify the control plane installed correctly, click the *Istio Service Mesh Control Plane* tab.
+The Operator creates pods, services, and {SMProductShortName} control plane components based on your configuration parameters. You can configure `ServiceMeshControlPlane` settings at a later time.
+
+.Verification
+
+* To verify the control plane installed correctly, click the *Istio Service Mesh Control Plane* tab.
 +
 .. Click the name of the new control plane.
 +
diff --git a/modules/ossm-cr-threescale.adoc b/modules/ossm-cr-threescale.adoc
@@ -12,6 +12,10 @@ The following table explains the parameters for the 3scale Istio Adapter in the
 .Example 3scale parameters
 [source,yaml]
 ----
+apiVersion: maistra.io/v2
+kind: ServiceMeshControlPlane
+metadata:
+  name: basic
 spec:
   addons:
     3Scale:
@@ -32,6 +36,7 @@ spec:
       PARAM_USE_CACHED_BACKEND: false
       PARAM_BACKEND_CACHE_FLUSH_INTERVAL_SECONDS: 15
       PARAM_BACKEND_CACHE_POLICY_FAIL_CLOSED: true
+# ...
 ----
 
 .3scale parameters
diff --git a/modules/ossm-deploy-cluster-wide-control-plane-cli.adoc b/modules/ossm-deploy-cluster-wide-control-plane-cli.adoc
@@ -1,6 +1,6 @@
 // This module is included in the following assemblies:
-//
 // * service_mesh/v2x/ossm-create-smcp.adoc
+//
 
 :_mod-docs-content-type: PROCEDURE
 [id="ossm-deploy-cluster-wide-control-plane-cli_{context}"]
@@ -43,13 +43,21 @@ spec:
   mode: ClusterWide
 ----
 
-. Run the following command to deploy the {SMProductShortName} control plane, where `<istio_installation.yaml>` includes the full path to your file.
+. Run the following command to deploy the {SMProductShortName} control plane:
 +
 [source,terminal]
 ----
 $ oc create -n istio-system -f <istio_installation.yaml>
 ----
 +
+where:
++
+--
+<istio_installation.yaml>:: Specifies the full path to your file.
+--
+
+.Verification
+
 . To monitor the progress of the pod deployment, run the following command:
 +
 [source,terminal]
diff --git a/modules/ossm-deploy-cluster-wide-control-plane-console.adoc b/modules/ossm-deploy-cluster-wide-control-plane-console.adoc
@@ -58,8 +58,12 @@ spec:
 
 . 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.
 
-. To verify that the control plane installed correctly, click the *Istio Service Mesh Control Plane* tab.
-+
+.Verification
+
+* To verify that the control plane installed correctly:
+
+.. Click the *Istio Service Mesh Control Plane* tab.
+
 .. Click the name of the new `ServiceMeshControlPlane` object.
-+
+
 .. Click the *Resources* tab to see the {SMProductName} control plane resources that the Operator created and configured.
diff --git a/modules/ossm-deploying-jaeger.adoc b/modules/ossm-deploying-jaeger.adoc
@@ -56,7 +56,7 @@ spec:
 To use the default settings for the `production` deployment strategy, set `spec.addons.jaeger.install.storage.type` to `Elasticsearch` and specify additional configuration options under `install`. Note that the SMCP only supports configuring Elasticsearch resources and image name.
 
 .Control plane default Jaeger parameters (Elasticsearch)
-[source,yaml, subs="attributes"]
+[source,yaml, subs="attributes,verbatim"]
 ----
 apiVersion: maistra.io/v2
 kind: ServiceMeshControlPlane
@@ -91,7 +91,7 @@ The SMCP supports only minimal Elasticsearch parameters. To fully customize your
 Create and configure your Jaeger instance and set `spec.addons.jaeger.name` to the name of the Jaeger instance, in this example: `MyJaegerInstance`.
 
 .Control plane with linked Jaeger production CR
-[source,yaml, subs="attributes"]
+[source,yaml, subs="attributes,verbatim"]
 ----
 apiVersion: maistra.io/v2
 kind: ServiceMeshControlPlane
@@ -118,7 +118,7 @@ spec:
 To use the `streaming` deployment strategy, you create and configure your Jaeger instance first, then set `spec.addons.jaeger.name` to the name of the Jaeger instance, in this example: `MyJaegerInstance`.
 
 .Control plane with linked Jaeger streaming CR
-[source,yaml, subs="attributes"]
+[source,yaml, subs="attributes,verbatim"]
 ----
 apiVersion: maistra.io/v2
 kind: ServiceMeshControlPlane
diff --git a/modules/ossm-install-ossm-operator.adoc b/modules/ossm-install-ossm-operator.adoc
@@ -40,6 +40,9 @@ endif::openshift-rosa,openshift-dedicated[]
 +
 * The OpenShift Elasticsearch Operator is installed in the `openshift-operators-redhat` namespace and is available for all namespaces in the cluster.
 * The {JaegerName} is installed in the `openshift-distributed-tracing` namespace and is available for all namespaces in the cluster.
-* The Kiali Operator provided by Red Hat and the {SMProductName} Operator are installed in the `openshift-operators` namespace and are available for all namespaces in the cluster.
+* The Kiali Operator provided by Red Hat is installed in the `openshift-operators` namespace and is available for all namespaces in the cluster.
+* The {SMProductName} Operator is installed in the `openshift-operators` namespace and is available for all namespaces in the cluster.
 
-. After all you have installed all four Operators, click *Operators* -> *Installed Operators* to verify that your Operators installed.
+.Verification
+
+* After all you have installed all four Operators, click *Operators* -> *Installed Operators* to verify that your Operators are installed.
diff --git a/modules/ossm-install-rosa.adoc b/modules/ossm-install-rosa.adoc
@@ -3,9 +3,8 @@ This module included in the following assemblies:
 * service_mesh/v2/ossm-create-smcp.adoc
 ////
 
-:_mod-docs-content-type: REFERENCE
 [id="ossm-install-rosa_{context}"]
-= Installing on Red Hat OpenShift Service on AWS (ROSA)
+= Installing Service Mesh on Red Hat OpenShift Service on AWS (ROSA)
 
 Starting with version 2.2, {SMProductName} supports installation on Red Hat OpenShift Service on AWS (ROSA). This section documents the additional requirements when installing Service Mesh on this platform.
 
diff --git a/modules/ossm-installation-activities.adoc b/modules/ossm-installation-activities.adoc
@@ -12,5 +12,5 @@
 
 * *OpenShift Elasticsearch* - (Optional) Provides database storage for tracing and logging with the {JaegerShortName}. It is based on the open source link:https://www.elastic.co/[Elasticsearch] project.
 * *{JaegerName}* - Provides distributed tracing to monitor and troubleshoot transactions in complex distributed systems. It is based on the open source link:https://www.jaegertracing.io/[Jaeger] project.
-* *Kiali Operator provided by Red Hat* - Provides observability for your service mesh. You can view configurations, monitor traffic, and analyze traces in a single console. It is based on the open source link:https://www.kiali.io/[Kiali] project.
+* *Kiali Operator (provided by Red Hat)* - Provides observability for your service mesh. You can view configurations, monitor traffic, and analyze traces in a single console. It is based on the open source link:https://www.kiali.io/[Kiali] project.
 * *{SMProductName}* - Allows you to connect, secure, control, and observe the microservices that comprise your applications. The {SMProductShortName} Operator defines and monitors the `ServiceMeshControlPlane` resources that manage the deployment, updating, and deletion of the {SMProductShortName} components. It is based on the open source link:https://istio.io/[Istio] project.
diff --git a/modules/ossm-member-roll-create.adoc b/modules/ossm-member-roll-create.adoc
@@ -42,7 +42,7 @@ You can add one or more projects to the {SMProductShortName} member roll from th
 
 . Click *Create ServiceMeshMemberRoll*
 
-. Click *Members*, then enter the name of your project in the *Value* field. You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource.
+. Click *Members*, then enter the name of your project in the *Value* field. You can add any number of projects, but a project can only belong to one `ServiceMeshMemberRoll` resource.
 
 . Click *Create*.
 
@@ -73,7 +73,7 @@ $ oc login --username=<NAMEOFUSER> https://<HOSTNAME>:6443
 $ oc new-project <your-project>
 ----
 
-. To add your projects as members, modify the following example YAML. You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource. In this example, `istio-system` is the name of the {SMProductShortName} control plane project.
+. To add your projects as members, modify the following example YAML. You can add any number of projects, but a project can only belong to one `ServiceMeshMemberRoll` resource. In this example, `istio-system` is the name of the {SMProductShortName} control plane project.
 +
 .Example servicemeshmemberroll-default.yaml
 [source,yaml]
diff --git a/modules/ossm-member-roll-modify.adoc b/modules/ossm-member-roll-modify.adoc
diff --git a/modules/ossm-understanding-service-mesh.adoc b/modules/ossm-understanding-service-mesh.adoc
