diff --git a/_topic_map.yml b/_topic_map.yml index 5917a16f3598..2b6d6d9a5215 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -1381,6 +1381,11 @@ Topics: # File: ossm-tutorial-grafana # - Name: Prometheus tutorial # File: ossm-tutorial-prometheus +- Name: Support + Dir: service_mesh_support + Topics: + - Name: Collecting service mesh data for support + File: ossm-collecting-ossm-data - Name: 3scale adapter Dir: threescale_adapter Topics: diff --git a/modules/ossm-about-collecting-ossm-data.adoc b/modules/ossm-about-collecting-ossm-data.adoc new file mode 100644 index 000000000000..4fe10cdf8878 --- /dev/null +++ b/modules/ossm-about-collecting-ossm-data.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * service_mesh/service_mesh_support/ossm-collecting-ossm-data.adoc + +[id="ossm-about-collecting-ossm-data_{context}"] += About collecting service mesh data + +You can use the `oc adm must-gather` CLI command to collect information about your cluster, including features and objects associated with {ProductName}. + +To collect {ProductName} data with `must-gather`, you must specify the {ProductName} image: + +---- +$ oc adm must-gather --image=registry.redhat.io/openshift-service-mesh/istio-must-gather-rhel7 +---- \ No newline at end of file diff --git a/modules/ossm-control-plane-deploy.adoc b/modules/ossm-control-plane-deploy.adoc index fbb592c5c9f0..ff5dea593c53 100644 --- a/modules/ossm-control-plane-deploy.adoc +++ b/modules/ossm-control-plane-deploy.adoc @@ -46,7 +46,7 @@ Follow this procedure to deploy the {ProductName} control plane by using the web ** A `ServiceMeshControlPlane` resource ** A `ServiceMeshMemberRoll` resource -. Under *Istio Service Mesh Control Plane* click *Create New*. +. Under *Istio Service Mesh Control Plane* click *Create ServiceMeshControlPlane*. . On the *Create Service Mesh Control Plane* page, modify the YAML for the default `ServiceMeshControlPlane` template as needed. + diff --git a/modules/ossm-document-attributes.adoc b/modules/ossm-document-attributes.adoc index 1bdb784ee344..d3679656de6c 100644 --- a/modules/ossm-document-attributes.adoc +++ b/modules/ossm-document-attributes.adoc @@ -11,7 +11,7 @@ :ProductName: Red Hat OpenShift Service Mesh :ProductShortName: Service Mesh :ProductRelease: -:ProductVersion: 1.0.10 +:ProductVersion: 1.1.0 :MaistraVersion: 1.1 :product-build: :DownloadURL: registry.redhat.io diff --git a/modules/ossm-member-roll-create.adoc b/modules/ossm-member-roll-create.adoc index c29d71657d30..a1be5ed3c062 100644 --- a/modules/ossm-member-roll-create.adoc +++ b/modules/ossm-member-roll-create.adoc @@ -5,7 +5,7 @@ [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. +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`. @@ -102,3 +102,54 @@ spec: ---- + . 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 --role-namespace mesh-user . +---- + +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 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 +---- + \ No newline at end of file diff --git a/modules/ossm-operatorhub-install.adoc b/modules/ossm-operatorhub-install.adoc index 39943ed66293..13e6b439f94e 100644 --- a/modules/ossm-operatorhub-install.adoc +++ b/modules/ossm-operatorhub-install.adoc @@ -158,7 +158,7 @@ The Manual approval strategy requires a user with appropriate credentials to app . Click *Install*. -. Select the *1.0* Update Channel. +. Select the *stable* Update Channel. . Select the *Automatic* Approval Strategy. + diff --git a/modules/ossm-rn-known-issues.adoc b/modules/ossm-rn-known-issues.adoc index 638277044936..c2ecd88a37c4 100644 --- a/modules/ossm-rn-known-issues.adoc +++ b/modules/ossm-rn-known-issues.adoc @@ -13,7 +13,7 @@ Workaround (If there is one)- What can you do to avoid or negate the effects of Result - If the workaround does not completely address the problem. //// -These limitations exist in {ProductName} at this time: +These limitations exist in {ProductName}: * link:https://github.com/istio/old_issues_repo/issues/115[{ProductName} does not support IPv6], as it is not supported by the upstream Istio project, nor fully supported by OpenShift. @@ -29,7 +29,11 @@ While Kafka publisher is included in the release as part of Jaeger, it is not su [id="ossm-rn-known-issues-ossm_{context}"] == {ProductName} known issues -These are the known issues in {ProductName} at this time: +These are the known issues in {ProductName}: + +* link:https://bugzilla.redhat.com/show_bug.cgi?id=1821432[Bug 1821432] Toggle controls in {product-title} Control Resource details page do not update the CR correctly. UI Toggle controls in the Service Mesh Control Plane (SMCP) Overview page in the {product-title} web console sometimes update the wrong field in the resource. To update a SMCP, edit the YAML content directly or update the resource from the command line instead of clicking the toggle controls. + +* link:https://access.redhat.com/solutions/4970771[Jaeger/Kiali Operator upgrade blocked with operator pending] When upgrading the Jaeger or Kiali Operators with Service Mesh 1.0.x installed, the operator status shows as Pending. There is a solution in progress and a workaround. See the linked Knowledge Base article for more information. * link:https://github.com/istio/istio/issues/14743[Istio-14743] Due to limitations in the version of Istio that this release of {ProductName} is based on, there are several applications that are currently incompatible with {ProductShortName}. See the linked community issue for details. diff --git a/modules/ossm-rn-new-features.adoc b/modules/ossm-rn-new-features.adoc index c785e340bf5d..d3c09706cce1 100644 --- a/modules/ossm-rn-new-features.adoc +++ b/modules/ossm-rn-new-features.adoc @@ -17,6 +17,28 @@ Result – If changed, describe the current user experience * *Policy Enforcement* - Apply organizational policy to the interaction between services, ensure access policies are enforced and resources are fairly distributed among consumers. Policy changes are made by configuring the mesh, not by changing application code. * *Telemetry* - Gain understanding of the dependencies between services and the nature and flow of traffic between them, providing the ability to quickly identify issues. +== Component versions included in {ProductName} version {ProductVersion} + +|=== +|Component |Version + +|Istio +|1.4.6 + +|Jaeger +|1.17.1 + +|Kiali +|1.12.7 + +|3scale Istio Adapter +|1.0.0 +|=== + +== New features {ProductName} 1.1.0 + +This release of {ProductName} adds support for Istio 1.4.6 and Jaeger 1.17.1. + == New features {ProductName} 1.0.10 This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs). diff --git a/modules/ossm-tutorial-bookinfo-install.adoc b/modules/ossm-tutorial-bookinfo-install.adoc index 97d593ebe4c8..1028b9b0c32d 100644 --- a/modules/ossm-tutorial-bookinfo-install.adoc +++ b/modules/ossm-tutorial-bookinfo-install.adoc @@ -95,7 +95,7 @@ $ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistr + [NOTE] ==== -Replace `` with the name of your control plane project. +Replace `` with the name of your control plane project. In this example, the control plane project is `istio-system`. ==== + ---- diff --git a/service_mesh/service_mesh_day_two/prepare-to-deploy-applications-ossm.adoc b/service_mesh/service_mesh_day_two/prepare-to-deploy-applications-ossm.adoc index 56da194d28f6..b46a2814439d 100644 --- a/service_mesh/service_mesh_day_two/prepare-to-deploy-applications-ossm.adoc +++ b/service_mesh/service_mesh_day_two/prepare-to-deploy-applications-ossm.adoc @@ -20,7 +20,16 @@ include::modules/ossm-sidecar-injection.adoc[leveloffset=+1] include::modules/ossm-automatic-sidecar-injection.adoc[leveloffset=+2] -include::modules/ossm-mixer-policy.adoc[leveloffset=+1] +include::modules/ossm-mixer-policy.adoc[leveloffset=+2] + +[id="ossm-deploy-set-correct-np_{context}"] +== Setting the correct network policy + +{ProductShortName} creates network policies in the control plane and member namespaces to whitelist traffic between them. Before you deploy, consider the following conditions to ensure the services in your mesh that were previously exposed through an {product-title} route. + +* Traffic into the mesh must always go through the ingress-gateway for Istio to work properly. +* Deploy services external to the mesh in separate namespaces that are not in any mesh. +* Non-mesh services that need to be deployed within a service mesh enlisted namespace should label their deployments `maistra.io/expose-route: "true"`, which ensures {product-title} routes to these services still work. .Next steps diff --git a/service_mesh/service_mesh_install/removing-ossm.adoc b/service_mesh/service_mesh_install/removing-ossm.adoc index 63b5725fdba7..14514d598e49 100644 --- a/service_mesh/service_mesh_install/removing-ossm.adoc +++ b/service_mesh/service_mesh_install/removing-ossm.adoc @@ -4,7 +4,7 @@ include::modules/ossm-document-attributes.adoc[] :context: removing-ossm toc::[] -This process allows you to remove {ProductName} from an existing {product-title} instance. +This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. include::modules/ossm-control-plane-remove.adoc[leveloffset=+1] diff --git a/service_mesh/service_mesh_install/updating-ossm.adoc b/service_mesh/service_mesh_install/updating-ossm.adoc index 98623784d7a7..e14a680b0107 100644 --- a/service_mesh/service_mesh_install/updating-ossm.adoc +++ b/service_mesh/service_mesh_install/updating-ossm.adoc @@ -1,10 +1,28 @@ [id="updating-ossm"] = Updating {ProductName} include::modules/ossm-document-attributes.adoc[] -:context: installing-ossm +:context: updating-ossm toc::[] -If you selected the automatic update stream, updating {ProductName} doesn't require any extra steps. +If you're updating from {ProductName} 1.0 to 1.1, you must update the `ServiceMeshControlPlane` resource to update the control plane components to the new version. + +. In the web console, click the {ProductName} operator. + +. Click the *Project* menu and choose the project where your `ServiceMeshControlPlane` is deployed from the list, for example `istio-system`. + +. Click the name of your control plane, for example `basic-install`. + +. Click YAML and add a version field to the `spec:` of your `ServiceMeshControlPlane` resource. For example, to update to {ProductName} 1.1.0, add `version: v1.1`. + +---- +spec: + version: v1.1 + ... +---- + +The version field specifies the version of ServiceMesh to install and defaults to the latest available version. + +== Manual updates If you choose to update manually, the Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. OLM runs by default in {product-title}. OLM uses CatalogSources, which use the Operator Registry API, to query for available Operators as well as upgrades for installed Operators. diff --git a/service_mesh/service_mesh_support/ossm-collecting-ossm-data.adoc b/service_mesh/service_mesh_support/ossm-collecting-ossm-data.adoc new file mode 100644 index 000000000000..216fbc89ab6a --- /dev/null +++ b/service_mesh/service_mesh_support/ossm-collecting-ossm-data.adoc @@ -0,0 +1,19 @@ +[id="ossm-collecting-ossm-data"] += Collecting {ProductName} data for Red Hat Support +include::modules/ossm-document-attributes.adoc[] +:context: ossm-collecting-ossm-data +toc::[] + +When opening a support case, it is helpful to provide debugging +information about your cluster to Red Hat Support. + +The `must-gather` tool enables you to collect diagnostic information about your +{product-title} cluster, including virtual machines and other data related to +{ProductName}. + +For prompt support, supply diagnostic information for both {product-title} +and {ProductName}. + +include::modules/about-must-gather.adoc[leveloffset=+1] + +include::modules/ossm-about-collecting-ossm-data.adoc[leveloffset=+1]