From 1e4862e955bb861c02c134ab964debbb2893d3bc Mon Sep 17 00:00:00 2001 From: Vikram Goyal Date: Mon, 16 Aug 2021 09:34:46 +1000 Subject: [PATCH] sync up SM/Jaeger --- .../jaeger_arch/rhbjaeger-architecture.adoc | 2 +- .../jaeger_install/rhbjaeger-deploying.adoc | 14 ++--- .../rhbjaeger-installation.adoc | 6 +-- jaeger/jaeger_install/rhbjaeger-removing.adoc | 2 +- jaeger/jaeger_install/rhbjaeger-updating.adoc | 4 +- service_mesh/v1x/installing-ossm.adoc | 11 ++-- service_mesh/v1x/ossm-architecture.adoc | 5 +- service_mesh/v1x/ossm-config.adoc | 24 +++++++++ service_mesh/v1x/ossm-custom-resources.adoc | 1 + service_mesh/v1x/ossm-observability.adoc | 10 +--- service_mesh/v1x/ossm-traffic-manage.adoc | 8 ++- service_mesh/v1x/ossm-vs-community.adoc | 5 ++ .../prepare-to-deploy-applications-ossm.adoc | 4 +- .../v1x/preparing-ossm-installation.adoc | 3 +- service_mesh/v1x/removing-ossm.adoc | 9 ++-- service_mesh/v1x/threescale-adapter.adoc | 8 +++ service_mesh/v2x/installing-ossm.adoc | 52 ++++--------------- service_mesh/v2x/ossm-about.adoc | 8 +++ service_mesh/v2x/ossm-architecture.adoc | 7 +-- service_mesh/v2x/ossm-config.adoc | 30 +++++++++++ service_mesh/v2x/ossm-create-mesh.adoc | 31 +++++++++++ service_mesh/v2x/ossm-create-smcp.adoc | 21 ++++++++ service_mesh/v2x/ossm-deploy-production.adoc | 19 +++++++ service_mesh/v2x/ossm-deployment-models.adoc | 14 +++++ service_mesh/v2x/ossm-dist-trac.adoc | 14 +++++ service_mesh/v2x/ossm-extensions.adoc | 46 +++------------- service_mesh/v2x/ossm-observability.adoc | 28 ++++++---- .../v2x/ossm-performance-scalability.adoc | 15 ++++++ service_mesh/v2x/ossm-profiles-users.adoc | 13 +++++ service_mesh/v2x/ossm-reference-jaeger.adoc | 34 ++++++++++++ service_mesh/v2x/ossm-reference-smcp.adoc | 19 +++++++ service_mesh/v2x/ossm-security.adoc | 22 ++++---- service_mesh/v2x/ossm-support.adoc | 22 ++++++++ service_mesh/v2x/ossm-traffic-manage.adoc | 30 +++++++++-- service_mesh/v2x/ossm-vs-community.adoc | 16 +++--- .../prepare-to-deploy-applications-ossm.adoc | 34 +++++------- .../v2x/preparing-ossm-installation.adoc | 19 ++----- service_mesh/v2x/removing-ossm.adoc | 11 ++-- .../v2x/servicemesh-release-notes.adoc | 26 ---------- service_mesh/v2x/threescale-adapter.adoc | 10 +++- service_mesh/v2x/upgrading-ossm.adoc | 25 ++++----- 41 files changed, 451 insertions(+), 231 deletions(-) create mode 100644 service_mesh/v1x/ossm-config.adoc create mode 100644 service_mesh/v2x/ossm-about.adoc create mode 100644 service_mesh/v2x/ossm-config.adoc create mode 100644 service_mesh/v2x/ossm-create-mesh.adoc create mode 100644 service_mesh/v2x/ossm-create-smcp.adoc create mode 100644 service_mesh/v2x/ossm-deploy-production.adoc create mode 100644 service_mesh/v2x/ossm-deployment-models.adoc create mode 100644 service_mesh/v2x/ossm-dist-trac.adoc create mode 100644 service_mesh/v2x/ossm-performance-scalability.adoc create mode 100644 service_mesh/v2x/ossm-profiles-users.adoc create mode 100644 service_mesh/v2x/ossm-reference-jaeger.adoc create mode 100644 service_mesh/v2x/ossm-reference-smcp.adoc create mode 100644 service_mesh/v2x/ossm-support.adoc diff --git a/jaeger/jaeger_arch/rhbjaeger-architecture.adoc b/jaeger/jaeger_arch/rhbjaeger-architecture.adoc index 1e1e7e4d8780..ccd4920c65f2 100644 --- a/jaeger/jaeger_arch/rhbjaeger-architecture.adoc +++ b/jaeger/jaeger_arch/rhbjaeger-architecture.adoc @@ -5,7 +5,7 @@ include::modules/jaeger-document-attributes.adoc[] toc::[] -Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate in order to produce a response. +Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate to produce a response. Jaeger lets you perform distributed tracing, which records the path of a request through various microservices that make up an application. _Distributed tracing_ is a technique that is used to tie the information about different units of work together — usually executed in different processes or hosts — to understand a whole chain of events in a distributed transaction. diff --git a/jaeger/jaeger_install/rhbjaeger-deploying.adoc b/jaeger/jaeger_install/rhbjaeger-deploying.adoc index 195f3772d449..5f79153703a5 100644 --- a/jaeger/jaeger_install/rhbjaeger-deploying.adoc +++ b/jaeger/jaeger_install/rhbjaeger-deploying.adoc @@ -40,7 +40,7 @@ The streaming strategy requires an additional Red Hat subscription for AMQ Strea [NOTE] ==== -There are two ways to install and use Jaeger, as part of a service mesh or as a stand alone component. If you have installed Jaeger as part of Red Hat OpenShift Service Mesh, you can configure and deploy Jaeger as part of the xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-custom-resources-v2x[ServiceMeshControlPlane] or configure Jaeger and then xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-deploying-jaeger-streaming[reference your Jaeger configuration in the SMCP]. +There are two ways to install and use Jaeger, as part of a service mesh or as a stand alone component. If you have installed Jaeger as part of Red Hat OpenShift Service Mesh, you can configure and deploy Jaeger as part of the xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[ServiceMeshControlPlane] or configure Jaeger and then xref:../../service_mesh/v2x/ossm-observability.html#ossm-config-external-jaeger_observability[reference your Jaeger configuration in the ServiceMeshControlPlane]. ==== @@ -48,13 +48,15 @@ There are two ways to install and use Jaeger, as part of a service mesh or as a include::modules/jaeger-deploy-default.adoc[leveloffset=+1] -include::modules/jaeger-deploy-production-es.adoc[leveloffset=1] +include::modules/jaeger-deploy-production-es.adoc[leveloffset=+1] -include::modules/jaeger-deploy-streaming.adoc[leveloffset=1] +include::modules/jaeger-deploy-streaming.adoc[leveloffset=+1] [id="customizing-jaeger-deployment"] == Customizing Jaeger deployment +include::modules/jaeger-deployment-best-practices.adoc[leveloffset=+2] + include::modules/jaeger-config-default.adoc[leveloffset=+2] include::modules/jaeger-config-collector.adoc[leveloffset=+2] @@ -70,8 +72,8 @@ include::modules/jaeger-config-ingester.adoc[leveloffset=+2] [id="injecting-sidecars"] == Injecting sidecars -{ProductName} relies on a proxy sidecar within the application’s pod to provide the agent. The Jaeger Operator can inject Jaeger Agent sidecars into Deployment workloads. You can enable automatic sidecar injection or manage it manually. +{ProductName} relies on a proxy sidecar within the application's pod to provide the agent. The Jaeger Operator can inject Jaeger Agent sidecars into Deployment workloads. You can enable automatic sidecar injection or manage it manually. -include::modules/jaeger-sidecar-automatic.adoc[leveloffset=2] +include::modules/jaeger-sidecar-automatic.adoc[leveloffset=+2] -include::modules/jaeger-sidecar-manual.adoc[leveloffset=2] +include::modules/jaeger-sidecar-manual.adoc[leveloffset=+2] diff --git a/jaeger/jaeger_install/rhbjaeger-installation.adoc b/jaeger/jaeger_install/rhbjaeger-installation.adoc index 749e204ea5a1..101729839a9d 100644 --- a/jaeger/jaeger_install/rhbjaeger-installation.adoc +++ b/jaeger/jaeger_install/rhbjaeger-installation.adoc @@ -7,9 +7,9 @@ toc::[] You can install Jaeger on {product-title} in either of two ways: -* You can install Jaeger as part of Red Hat OpenShift Service Mesh. Jaeger is included by default in the Service Mesh installation. To install Jaeger as part of a service mesh, follow the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Red Hat Service Mesh Installation] instructions. +* You can install Jaeger as part of Red Hat OpenShift Service Mesh. Jaeger is included by default in the Service Mesh installation. To install Jaeger as part of a service mesh, follow the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Red Hat Service Mesh Installation] instructions. Jaeger must be installed in the same namespace as your service mesh, that is, the `ServiceMeshControlPlane` and the Jaeger resources must be in the same namespace. -* If you do not want to install a service mesh, you can use the Jaeger Operator to install the Red Hat build of Jaeger by itself. To install Jaeger without a service mesh, use the following instructions. +* If you do not want to install a service mesh, you can use the Jaeger Operator to install {ProductName} by itself. To install Jaeger without a service mesh, use the following instructions. == Prerequisites @@ -25,7 +25,7 @@ Before you can install {ProductName}, review the installation activities, and en ** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Install {product-title} {product-version} on user-provisioned AWS] ** xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install {product-title} {product-version} on bare metal] ** xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Install {product-title} {product-version} on vSphere] -* Install the version of the {product-title} command line utility (the `oc` client tool) that matches your {product-title} version and add it to your path. +* Install the version of the OpenShift CLI (`oc`) that matches your {product-title} version and add it to your path. * An account with the `cluster-admin` role. diff --git a/jaeger/jaeger_install/rhbjaeger-removing.adoc b/jaeger/jaeger_install/rhbjaeger-removing.adoc index 1a24540c5646..eaa8aeebc80d 100644 --- a/jaeger/jaeger_install/rhbjaeger-removing.adoc +++ b/jaeger/jaeger_install/rhbjaeger-removing.adoc @@ -24,4 +24,4 @@ include::modules/jaeger-removing-instance-cli.adoc[leveloffset=+1] * Remove the Jaeger Operator. -* After the Jaeger Operator has been removed, if appropriate, remove the Elasticsearch Operator. +* After the Jaeger Operator has been removed, if appropriate, remove the OpenShift Elasticsearch Operator. diff --git a/jaeger/jaeger_install/rhbjaeger-updating.adoc b/jaeger/jaeger_install/rhbjaeger-updating.adoc index 421eca48c71d..80b0a46a0b0c 100644 --- a/jaeger/jaeger_install/rhbjaeger-updating.adoc +++ b/jaeger/jaeger_install/rhbjaeger-updating.adoc @@ -9,4 +9,6 @@ The Operator Lifecycle Manager (OLM) controls the installation, upgrade, and rol The OLM queries for available Operators as well as upgrades for installed Operators. For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager] documentation. -The update approach used by the Jaeger Operator upgrades the managed Jaeger instances to the version associated with the Operator. Whenever a new version of the Jaeger Operator is installed, all the Jaeger application instances managed by the Operator will be upgraded to the Operator’s version. For example, if version 1.10 is installed (both Operator and backend components) and the Operator is upgraded to version 1.11, then as soon as the Operator upgrade has completed, the Operator will scan for running Jaeger instances and upgrade them to 1.11 as well. +The update approach used by the Jaeger Operator upgrades the managed Jaeger instances to the version associated with the Operator. Whenever a new version of the Jaeger Operator is installed, all the Jaeger application instances managed by the Operator will be upgraded to the Operator's version. For example, if version 1.10 is installed (both Operator and backend components) and the Operator is upgraded to version 1.11, then as soon as the Operator upgrade has completed, the Operator will scan for running Jaeger instances and upgrade them to 1.11 as well. + +For specific instructions for how to update the OpenShift Elasticsearch Operator, refer to xref:../../logging/cluster-logging-upgrading.adoc#cluster-logging-upgrading_cluster-logging-upgrading[Updating OpenShift Logging]. diff --git a/service_mesh/v1x/installing-ossm.adoc b/service_mesh/v1x/installing-ossm.adoc index 6d743249bdbe..3f61f66d56ca 100644 --- a/service_mesh/v1x/installing-ossm.adoc +++ b/service_mesh/v1x/installing-ossm.adoc @@ -2,13 +2,14 @@ = Installing {ProductName} include::modules/ossm-document-attributes-1x.adoc[] :context: installing-ossm-v1x + toc::[] -Installing the {ProductShortName} involves installing the Elasticsearch, Jaeger, Kiali and {ProductShortName} Operators, creating and managing a `ServiceMeshControlPlane` resource to deploy the control plane, and creating a `ServiceMeshMemberRoll` resource to specify the namespaces associated with the {ProductShortName}. +Installing the {ProductShortName} involves installing the OpenShift Elasticsearch, Jaeger, Kiali and {ProductShortName} Operators, creating and managing a `ServiceMeshControlPlane` resource to deploy the control plane, and creating a `ServiceMeshMemberRoll` resource to specify the namespaces associated with the {ProductShortName}. [NOTE] ==== -Mixer’s policy enforcement is disabled by default. You must enable it to run policy tasks. See xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-mixer-policy-1x_deploying-applications-ossm-v1x[Update Mixer policy enforcement] for instructions on enabling Mixer policy enforcement. +Mixer's policy enforcement is disabled by default. You must enable it to run policy tasks. See xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-mixer-policy-1x_deploying-applications-ossm-v1x[Update Mixer policy enforcement] for instructions on enabling Mixer policy enforcement. ==== [NOTE] @@ -18,7 +19,7 @@ Multi-tenant control plane installations are the default configuration starting [NOTE] ==== -The {ProductShortName} documentation uses `istio-system` as the example project, but you may deploy the service mesh to any project. +The {ProductShortName} documentation uses `istio-system` as the example project, but you can deploy the service mesh to any project. ==== == Prerequisites @@ -27,7 +28,7 @@ The {ProductShortName} documentation uses `istio-system` as the example project, The {ProductShortName} installation process uses the link:https://operatorhub.io/[OperatorHub] to install the `ServiceMeshControlPlane` custom resource definition within the `openshift-operators` project. The {ProductName} defines and monitors the `ServiceMeshControlPlane` related to the deployment, update, and deletion of the control plane. -Starting with {ProductName} {ProductVersion}, you must install the Elasticsearch Operator, the Jaeger Operator, and the Kiali Operator before the {ProductName} Operator can install the control plane. +Starting with {ProductName} {ProductVersion}, you must install the OpenShift Elasticsearch Operator, the Jaeger Operator, and the Kiali Operator before the {ProductName} Operator can install the control plane. include::modules/jaeger-install-elasticsearch.adoc[leveloffset=+1] @@ -56,6 +57,4 @@ include::modules/ossm-update-app-sidecar.adoc[leveloffset=+2] == Next steps -* xref:../../service_mesh/v1x/customizing-installation-ossm.adoc#customize-installation-ossm-v1x[Customize the {ProductName} installation]. - * xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm-v1x[Prepare to deploy applications] on {ProductName}. diff --git a/service_mesh/v1x/ossm-architecture.adoc b/service_mesh/v1x/ossm-architecture.adoc index 95973e84796f..476e209b1e25 100644 --- a/service_mesh/v1x/ossm-architecture.adoc +++ b/service_mesh/v1x/ossm-architecture.adoc @@ -2,6 +2,7 @@ = Understanding {ProductName} include::modules/ossm-document-attributes-1x.adoc[] :context: ossm-architecture-v1x + toc::[] {ProductName} provides a platform for behavioral insight and operational control over your networked microservices in a service mesh. With {ProductName}, you can connect, secure, and monitor microservices in your {product-title} environment. @@ -22,11 +23,11 @@ include::modules/ossm-kiali-features.adoc[leveloffset=+2] == Understanding Jaeger -Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate in order to produce a response. +Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate to produce a response. The path of this request is a distributed transaction. Jaeger lets you perform distributed tracing, which follows the path of a request through various microservices that make up an application. -*Distributed tracing* is a technique that is used to tie the information about different units of work together—usually executed in different processes or hosts—in order to understand a whole chain of events in a distributed transaction. +*Distributed tracing* is a technique that is used to tie the information about different units of work together—usually executed in different processes or hosts—to understand a whole chain of events in a distributed transaction. Distributed tracing lets developers visualize call flows in large service oriented architectures. It can be invaluable in understanding serialization, parallelism, and sources of latency. diff --git a/service_mesh/v1x/ossm-config.adoc b/service_mesh/v1x/ossm-config.adoc new file mode 100644 index 000000000000..cb0c8c6b976d --- /dev/null +++ b/service_mesh/v1x/ossm-config.adoc @@ -0,0 +1,24 @@ +[id="ossm-config-v1x"] += Configuring {ProductName} +include::modules/ossm-document-attributes-1x.adoc[] +:context: ossm-config-v1x + +toc::[] + +After you create a `ServiceMeshControlPlane` resource, configure the resource to suit your environment and requirements. + +This guide references the Bookinfo sample application to provide examples of security in an example application. Install the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm[Bookinfo application] to learn how these routing examples work. + +include::modules/ossm-config-security.adoc[leveloffset=+1] + +include::modules/ossm-security-mtls-1x.adoc[leveloffset=+2] + +include::modules/ossm-security-cipher.adoc[leveloffset=+2] + +include::modules/ossm-security-cert-manage.adoc[leveloffset=+2] + +include::modules/ossm-config-dist-trac.adoc[leveloffset=+1] + +include::modules/ossm-config-sampling.adoc[leveloffset=+2] + +include::modules/ossm-config-external-jaeger.adoc[leveloffset=+2] diff --git a/service_mesh/v1x/ossm-custom-resources.adoc b/service_mesh/v1x/ossm-custom-resources.adoc index 5e5ea8581e91..333a43e84c49 100644 --- a/service_mesh/v1x/ossm-custom-resources.adoc +++ b/service_mesh/v1x/ossm-custom-resources.adoc @@ -2,6 +2,7 @@ = Custom resources include::modules/ossm-document-attributes.adoc[] :context: ossm-controler-items-v1x + toc::[] You can customize your {ProductName} by modifying the default {ProductShortName} custom resource or by creating a new custom resource. diff --git a/service_mesh/v1x/ossm-observability.adoc b/service_mesh/v1x/ossm-observability.adoc index 950cf49500ce..3a8cc269ed08 100644 --- a/service_mesh/v1x/ossm-observability.adoc +++ b/service_mesh/v1x/ossm-observability.adoc @@ -7,15 +7,9 @@ toc::[] You can view your application's topology, health and metrics in the Kiali console. If your service is having issues, the Kiali console offers ways to visualize the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. It also provides an interactive graph view of your namespace in real time. -You can observe the data flow through your application if you have one installed. If you don't have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm-v1x[Bookinfo sample application]. +.Before you begin -After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command a few times: - ----- -$ curl http://$GATEWAY_URL/productpage ----- - -If your sample application is configured correctly, this command simulates a user visiting the `productpage` microservice of the application. +You can observe the data flow through your application if you have an application installed. If you don't have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm-v1x[Bookinfo sample application]. include::modules/ossm-observability-access.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/ossm-traffic-manage.adoc b/service_mesh/v1x/ossm-traffic-manage.adoc index b9b6d6ad719e..fafb4afdbbbb 100644 --- a/service_mesh/v1x/ossm-traffic-manage.adoc +++ b/service_mesh/v1x/ossm-traffic-manage.adoc @@ -11,8 +11,14 @@ This guide references the Bookinfo sample application to provide examples of rou include::modules/ossm-routing.adoc[leveloffset=+1] -include::modules/ossm-routing-ingress.adoc[leveloffset=+1] +include::modules/ossm-routing-gateways.adoc[leveloffset=+1] include::modules/ossm-routing-bookinfo-example.adoc[leveloffset=+1] +include::modules/ossm-routing-ingress.adoc[leveloffset=+1] + include::modules/ossm-auto-route-1x.adoc[leveloffset=+1] + +== Links + +For more information about configuring an {product-title} wildcard policy, see xref:../../networking/ingress-operator.adoc#using-wildcard-routes_configuring-ingress[Using wildcard routes]. diff --git a/service_mesh/v1x/ossm-vs-community.adoc b/service_mesh/v1x/ossm-vs-community.adoc index e83eb0454fa2..20260a9ec426 100644 --- a/service_mesh/v1x/ossm-vs-community.adoc +++ b/service_mesh/v1x/ossm-vs-community.adoc @@ -14,6 +14,11 @@ The current release of {ProductName} differs from the current upstream Istio com include::modules/ossm-multitenant.adoc[leveloffset=+1] include::modules/ossm-vs-istio-1x.adoc[leveloffset=+1] +[discrete] +[id="additional-resources_ossm-vs-istio-v1x"] +==== Additional resources + +* xref:../../service_mesh/v1x/ossm-traffic-manage.adoc#ossm-auto-route-1x_routing-traffic-v1x[Automatic route creation] include::modules/ossm-kiali-service-mesh.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc b/service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc index 50da4199a5c2..99063d72c58a 100644 --- a/service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc +++ b/service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc @@ -15,9 +15,9 @@ When you deploy an application into the {ProductShortName}, there are several di include::modules/ossm-control-plane-templates-1x.adoc[leveloffset=+1] -include::modules/ossm-sidecar-injection.adoc[leveloffset=+1] +include::modules/ossm-automatic-sidecar-injection.adoc[leveloffset=+1] -include::modules/ossm-automatic-sidecar-injection.adoc[leveloffset=+2] +include::modules/ossm-sidecar-injection-env-var.adoc[leveloffset=+1] include::modules/ossm-mixer-policy-1x.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/preparing-ossm-installation.adoc b/service_mesh/v1x/preparing-ossm-installation.adoc index 54e84c103903..d33980485392 100644 --- a/service_mesh/v1x/preparing-ossm-installation.adoc +++ b/service_mesh/v1x/preparing-ossm-installation.adoc @@ -2,6 +2,7 @@ = Preparing to install {ProductName} include::modules/ossm-document-attributes-1x.adoc[] :context: preparing-ossm-installation-v1x + toc::[] Before you can install {ProductName}, review the installation activities, ensure that you meet the prerequisites: @@ -30,7 +31,7 @@ include::modules/ossm-installation-activities.adoc[leveloffset=+1] [WARNING] ==== -Please see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] for details on configuring the default Jaeger parameters for Elasticsearch in a production environment. +See xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] for details on configuring the default Jaeger parameters for Elasticsearch in a production environment. ==== == Next steps diff --git a/service_mesh/v1x/removing-ossm.adoc b/service_mesh/v1x/removing-ossm.adoc index 0bfd4aec6a59..79618a9a7846 100644 --- a/service_mesh/v1x/removing-ossm.adoc +++ b/service_mesh/v1x/removing-ossm.adoc @@ -2,12 +2,13 @@ = Removing {ProductName} include::modules/ossm-document-attributes-1x.adoc[] :context: removing-ossm-v1x -toc::[] -This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. +toc::[] -include::modules/ossm-member-roll-delete.adoc[leveloffset=+1] +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] -include::modules/ossm-operatorhub-remove.adoc[leveloffset=+1] +include::modules/ossm-remove-operators.adoc[leveloffset=+1] + +include::modules/ossm-remove-cleanup-1x.adoc[leveloffset=+2] diff --git a/service_mesh/v1x/threescale-adapter.adoc b/service_mesh/v1x/threescale-adapter.adoc index 9a7c90a42afc..12493bae9b19 100644 --- a/service_mesh/v1x/threescale-adapter.adoc +++ b/service_mesh/v1x/threescale-adapter.adoc @@ -2,6 +2,7 @@ = Using the 3scale Istio adapter include::modules/ossm-document-attributes-1x.adoc[] :context: threescale-adapter-v1x + toc::[] The 3scale Istio Adapter is an optional adapter that allows you to label a service running within the {ProductName} and integrate that service with the 3scale API Management solution. @@ -25,3 +26,10 @@ include::modules/ossm-threescale-caching.adoc[leveloffset=+1] include::modules/ossm-threescale-authentication.adoc[leveloffset=+1] include::modules/ossm-threescale-metrics-1x.adoc[leveloffset=+1] + +include::modules/ossm-threescale-istio-adapter-verification.adoc[leveloffset=+1] + +.Additional resources +* link:https://docs.openshift.com/container-platform/4.7/support/troubleshooting/investigating-pod-issues.html#inspecting-pod-and-container-logs_investigating-pod-issues[Inspecting pod and container logs]. + +include::modules/ossm-threescale-istio-adapter-troubleshooting-checklist.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/installing-ossm.adoc b/service_mesh/v2x/installing-ossm.adoc index 307248f2740d..1d7a9c52389f 100644 --- a/service_mesh/v2x/installing-ossm.adoc +++ b/service_mesh/v2x/installing-ossm.adoc @@ -1,56 +1,22 @@ [id="installing-ossm"] -= Installing {ProductName} += Installing the Operators include::modules/ossm-document-attributes.adoc[] :context: installing-ossm -toc::[] - -Installing the {ProductShortName} involves installing the Elasticsearch, Jaeger, Kiali and {ProductShortName} Operators, creating and managing a `ServiceMeshControlPlane` resource to deploy the control plane, and creating a `ServiceMeshMemberRoll` resource to specify the namespaces associated with the {ProductShortName}. - -[NOTE] -==== -Multi-tenant control plane installations are the default configuration starting with {ProductName} 1.0. -==== - -[NOTE] -==== -The {ProductShortName} documentation uses `istio-system` as the example project, but you may deploy the service mesh to any project. -==== -== Prerequisites -* Follow the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Preparing to install {ProductName}] process. -* An account with the `cluster-admin` role. - -The {ProductShortName} installation process uses the link:https://operatorhub.io/[OperatorHub] to install the `ServiceMeshControlPlane` custom resource definition within the `openshift-operators` project. The {ProductName} defines and monitors the `ServiceMeshControlPlane` related to the deployment, update, and deletion of the control plane. +toc::[] -Starting with {ProductName} {ProductVersion}, you must install the Elasticsearch Operator, the Jaeger Operator, and the Kiali Operator before the {ProductName} Operator can install the control plane. +To install {ProductName}, first install the required Operators on {product-title} and then create a `ServiceMeshControlPlane` resource to deploy the control plane. -include::modules/jaeger-install-elasticsearch.adoc[leveloffset=+1] +.Prerequisites +* Read the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Preparing to install {ProductName}] process. +* An account with the `cluster-admin` role. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role. -include::modules/jaeger-install.adoc[leveloffset=+1] +The following steps show how to install a basic instance of {ProductName} on {product-title}. -include::modules/ossm-install-kiali.adoc[leveloffset=+1] +include::modules/ossm-installation-activities.adoc[leveloffset=+1] include::modules/ossm-install-ossm-operator.adoc[leveloffset=+1] -include::modules/ossm-control-plane-deploy.adoc[leveloffset=+1] - -For a multitenant installation, {ProductName} supports multiple independent control planes within the cluster. You can create reusable configurations with `ServiceMeshControlPlane` profiles. For more information, see xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-control-plane-profiles_deploying-applications-ossm[Creating control plane profiles]. - -include::modules/ossm-member-roll-create.adoc[leveloffset=+1] - -include::modules/ossm-member-roll-modify.adoc[leveloffset=+1] - -== 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. - -* For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-overview_olm-understanding-olm[Operator Lifecycle Manager] documentation. - -include::modules/ossm-update-app-sidecar.adoc[leveloffset=+2] - == Next steps -* xref:../../service_mesh/v2x/customizing-installation-ossm.adoc#customize-installation-ossm-v2x[Customize the {ProductName} installation]. - -* xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm[Prepare to deploy applications] on {ProductName}. +Create a `ServiceMeshControlPlane` resource to configure the components of {ProductShortName}. For more information, see xref:../../service_mesh/v2x/ossm-create-smcp.adoc#ossm-create-smcp[Creating the ServiceMeshControlPlane]. diff --git a/service_mesh/v2x/ossm-about.adoc b/service_mesh/v2x/ossm-about.adoc new file mode 100644 index 000000000000..20a2873b310c --- /dev/null +++ b/service_mesh/v2x/ossm-about.adoc @@ -0,0 +1,8 @@ +[id="ossm-about"] += About OpenShift Service Mesh +include::modules/ossm-document-attributes.adoc[] +:context: ossm-about + +toc::[] + +include::modules/ossm-servicemesh-overview.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-architecture.adoc b/service_mesh/v2x/ossm-architecture.adoc index 70a04f15be08..7d9fb88a0957 100644 --- a/service_mesh/v2x/ossm-architecture.adoc +++ b/service_mesh/v2x/ossm-architecture.adoc @@ -2,6 +2,7 @@ include::modules/ossm-document-attributes.adoc[] = Understanding {ProductName} :context: ossm-architecture + toc::[] {ProductName} provides a platform for behavioral insight and operational control over your networked microservices in a service mesh. With {ProductName}, you can connect, secure, and monitor microservices in your {product-title} environment. @@ -22,15 +23,15 @@ include::modules/ossm-kiali-features.adoc[leveloffset=+2] == Understanding Jaeger -Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate in order to produce a response. +Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate to produce a response. The path of this request is a distributed transaction. Jaeger lets you perform distributed tracing, which follows the path of a request through various microservices that make up an application. -*Distributed tracing* is a technique that is used to tie the information about different units of work together—usually executed in different processes or hosts—in order to understand a whole chain of events in a distributed transaction. +*Distributed tracing* is a technique that is used to tie the information about different units of work together—usually executed in different processes or hosts—to understand a whole chain of events in a distributed transaction. Distributed tracing lets developers visualize call flows in large service oriented architectures. It can be invaluable in understanding serialization, parallelism, and sources of latency. -Jaeger records the execution of individual requests across the whole stack of microservices, and presents them as traces. A *trace* is a data/execution path through the system. An end-to-end trace is comprised of one or more spans. +Jaeger records the execution of individual requests across the whole stack of microservices, and presents them as traces. A *trace* is a data/execution path through the system. An end-to-end trace comprises one or more spans. A *span* represents a logical unit of work in Jaeger that has an operation name, the start time of the operation, and the duration. Spans may be nested and ordered to model causal relationships. diff --git a/service_mesh/v2x/ossm-config.adoc b/service_mesh/v2x/ossm-config.adoc new file mode 100644 index 000000000000..73a90cb6ea29 --- /dev/null +++ b/service_mesh/v2x/ossm-config.adoc @@ -0,0 +1,30 @@ +[id="ossm-config-v2x"] += Configuring Service Mesh +include::modules/ossm-document-attributes.adoc[] +:context: ossm-config-v2x + +toc::[] + +After you create a `ServiceMeshControlPlane` resource, configure the resource to suit your environment and requirements. + +This guide references the Bookinfo sample application to provide examples of security in a sample application. Install the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm[Bookinfo application] to learn how these routing examples work. + +include::modules/ossm-config-security.adoc[leveloffset=+1] + +include::modules/ossm-security-mtls.adoc[leveloffset=+2] + +include::modules/ossm-config-sec-mtls-mesh.adoc[leveloffset=+3] + +include::modules/ossm-config-sidecar-mtls.adoc[leveloffset=+3] + +include::modules/ossm-config-sidecar-out-mtls.adoc[leveloffset=+3] + +include::modules/ossm-config-mtls-min-max.adoc[leveloffset=+3] + +include::modules/ossm-security-auth-policy.adoc[leveloffset=+2] + +include::modules/ossm-security-cipher.adoc[leveloffset=+2] + +include::modules/ossm-security-cert-manage.adoc[leveloffset=+2] + + diff --git a/service_mesh/v2x/ossm-create-mesh.adoc b/service_mesh/v2x/ossm-create-mesh.adoc new file mode 100644 index 000000000000..74cc94f40e64 --- /dev/null +++ b/service_mesh/v2x/ossm-create-mesh.adoc @@ -0,0 +1,31 @@ +[id="ossm-create-mesh"] += Adding services to a service mesh +include::modules/ossm-document-attributes.adoc[] +:context: ossm-create-mesh + +After installing the Operators and `ServiceMeshControlPlane` resource, add applications, workloads, or services to your mesh by creating a `ServiceMeshMemberRoll` resource and specifying the namespaces where your content is located. If you already have an application, workflow, or service to add to a `ServiceMeshMemberRoll` resource, use the following steps. Or, to install a sample application called Bookinfo and add it to a `ServiceMeshMemberRoll` resource, skip to the tutorial for installing the xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-tutorial-bookinfo-overview_ossm-create-mesh[Bookinfo example application] to see how an application works in {ProductName}. + +The items listed in the `ServiceMeshMemberRoll` resource are the applications and workflows that are managed by the `ServiceMeshControlPlane` resource. The control plane, which includes the {ProductShortName} Operators, Istiod, and `ServiceMeshControlPlane`, and the data plane, which includes applications and Envoy proxy, must be in separate namespaces. + +[NOTE] +==== +After you add the namespace to the `ServiceMeshMemberRoll`, access to services or pods in that namespace will not be accessible to callers outside the service mesh. +==== + +include::modules/ossm-member-roll-create.adoc[leveloffset=+1] + +include::modules/ossm-member-roll-modify.adoc[leveloffset=+1] + +include::modules/ossm-tutorial-bookinfo-overview.adoc[leveloffset=+1] + +include::modules/ossm-tutorial-bookinfo-install.adoc[leveloffset=+2] + +include::modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc[leveloffset=+2] + +include::modules/ossm-tutorial-bookinfo-verify-install.adoc[leveloffset=+2] + +include::modules/ossm-tutorial-bookinfo-removing.adoc[leveloffset=+2] + +== Next steps + +* To continue the installation process, you must xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm[enable sidecar injection]. diff --git a/service_mesh/v2x/ossm-create-smcp.adoc b/service_mesh/v2x/ossm-create-smcp.adoc new file mode 100644 index 000000000000..2bb64342fe13 --- /dev/null +++ b/service_mesh/v2x/ossm-create-smcp.adoc @@ -0,0 +1,21 @@ +[id="ossm-create-smcp"] += Creating the ServiceMeshControlPlane +include::modules/ossm-document-attributes.adoc[] +:context: ossm-create-smcp + +You can deploy a basic installation of the `ServiceMeshControlPlane` by using either the {product-title} web console or from the command line using the `oc` client tool. + +[NOTE] +==== +The {ProductShortName} documentation uses `istio-system` as the example project, but you can deploy the service mesh to any project. +==== + +include::modules/ossm-control-plane-web.adoc[leveloffset=+1] + +include::modules/ossm-control-plane-cli.adoc[leveloffset=+1] + +{ProductName} supports multiple independent control planes within the cluster. You can create reusable configurations with `ServiceMeshControlPlane` profiles. For more information, see xref:../../service_mesh/v2x/ossm-profiles-users.adoc#ossm-control-plane-profiles_ossm-profiles-users[Creating control plane profiles]. + +== Next steps + +Create a `ServiceMeshMemberRoll` resource to specify the namespaces associated with the {ProductShortName}. For more information, see xref:../../service_mesh/v2x/ossm-create-mesh.adoc#ossm-create-mesh[Adding services to a service mesh]. diff --git a/service_mesh/v2x/ossm-deploy-production.adoc b/service_mesh/v2x/ossm-deploy-production.adoc new file mode 100644 index 000000000000..215117d07ada --- /dev/null +++ b/service_mesh/v2x/ossm-deploy-production.adoc @@ -0,0 +1,19 @@ +[id="ossm-production"] +include::modules/ossm-document-attributes.adoc[] += Configuring Service Mesh for production +:context: ossm-architecture +toc::[] + +When you are ready to move from a basic installation to production, you must configure your control plane, tracing, and security certificates to meet production requirements. + +.Prerequisites + +* Install and configure {ProductName}. +* Test your configuration in a staging environment. + +include::modules/ossm-smcp-prod.adoc[leveloffset=+1] + +[id="additional-resources_ossm-production"] +== Additional resources + +* For more information about tuning {ProductShortName} for performance, see xref:../../service_mesh/v2x/ossm-performance-scalability.adoc#ossm-performance-scalability[Performance and scalability]. diff --git a/service_mesh/v2x/ossm-deployment-models.adoc b/service_mesh/v2x/ossm-deployment-models.adoc new file mode 100644 index 000000000000..6880e07e4fca --- /dev/null +++ b/service_mesh/v2x/ossm-deployment-models.adoc @@ -0,0 +1,14 @@ +[id="ossm-deployment-models"] += Service mesh deployment models +include::modules/ossm-document-attributes.adoc[] +:context: ossm-deployment-models + +{ProductName} supports several different deployment models that can be combined in different ways to best suit your business requirements. + +include::modules/ossm-deploy-single-mesh.adoc[leveloffset=+1] + +include::modules/ossm-deploy-single-tenant.adoc[leveloffset=+1] + +include::modules/ossm-deploy-multitenant.adoc[leveloffset=+1] + +include::modules/ossm-deploy-multi-mesh.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-dist-trac.adoc b/service_mesh/v2x/ossm-dist-trac.adoc new file mode 100644 index 000000000000..1e7066321707 --- /dev/null +++ b/service_mesh/v2x/ossm-dist-trac.adoc @@ -0,0 +1,14 @@ +[id="ossm-dist-trac"] += Distributed tracing +include::modules/ossm-document-attributes.adoc[] +:context: ossm-dist-trac + +toc::[] + +Distributed Tracing is the process of tracking the performance of individual services in an application by tracing the path of the service calls in the application. Each time a user takes action in an application, a request is executed that might require many services to interact to produce a response. The path of this request is called a distributed transaction. + +As a developer, you can use Jaeger to visualize call flows in a microservice application with {ProductName}. + +include::modules/ossm-config-sampling.adoc[leveloffset=+1] + +include::modules/ossm-config-external-jaeger.adoc[leveloffset=+1] \ No newline at end of file diff --git a/service_mesh/v2x/ossm-extensions.adoc b/service_mesh/v2x/ossm-extensions.adoc index 6182b5bd5dd7..940ed2bcff9d 100644 --- a/service_mesh/v2x/ossm-extensions.adoc +++ b/service_mesh/v2x/ossm-extensions.adoc @@ -3,6 +3,8 @@ include::modules/ossm-document-attributes.adoc[] :context: ossm-extensions +toc::[] + You can use WebAssembly extensions to add new features directly into the {ProductName} proxies, allowing you to move even more common functionality out of your applications, and implement them in a single language that compiles to WebAssembly bytecode. == WebAssembly extensions @@ -61,7 +63,7 @@ priority: 100 module: extension.wasm ---- -.manifest.yml Field Reference +.Field Reference for manifest.yml |=== | Field | Description @@ -89,45 +91,11 @@ module: extension.wasm === Example Rust extension -For a complete example that was built using the Rust SDK, take a look at the link:https://github.com/maistra/header-append-filter[header-append-filter]. It is a very simple filter that appends a header, `custom-header`, to all responses, with the value depending on its configuration. - -=== Enabling WebAssembly extension support - -Support for WebAssembly extensions to {ProductName} is currently in Tech Preview, so it must be explicitly enabled for your `ServiceMeshControlPlane`. Set `spec.techPreview.wasmExtensions.enabled` in your SMCPv2 to `true`. Here's an example: +For a complete example that was built using the Rust SDK, take a look at the link:https://github.com/maistra/header-append-filter[header-append-filter]. The filter appends a header, called `custom-header`, to all responses, with the value depending on its configuration. -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: openid-connect - namespace: istio-system -spec: - techPreview: - wasmExtensions: - enabled: true ----- +include::modules/ossm-extensions-wasm-support.adoc[leveloffset=+2] -=== Deploying extensions - -{ProductName} extensions can be enabled using the `ServiceMeshExtension` resource. The following snippet is an example resource. - -[source,yaml] ----- -apiVersion: maistra.io/v1alpha1 -kind: ServiceMeshExtension -metadata: - name: header-append - namespace: istio-system -spec: - workloadSelector: - labels: - app: httpbin - config: test - image: quay.io/maistra-dev/header-append-filter:latest - phase: PostAuthZ - priority: 100 ----- +include::modules/ossm-extensions-wasm-deploy.adoc[leveloffset=+2] .ServiceMeshExtension Field Reference |=== @@ -140,7 +108,7 @@ spec: |The `spec.workloadSelector` field has the same semantic as the `spec.selector` field of the link:https://istio.io/v1.6/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource]. It will match a workload based on its Pod labels. If no `workloadSelector` is specified, the extension will be applied to all workloads in the namespace. |spec.config -|This is a pass-through string field that will be handed over to the extension, so syntax and semantics are dependant on the extension you're deploying. +|This is a pass-through string field that is handed over to the extension. Syntax and semantics are dependent on the extension that you are deploying. |spec.image |A container image URI pointing to the image that holds the extension. diff --git a/service_mesh/v2x/ossm-observability.adoc b/service_mesh/v2x/ossm-observability.adoc index acb6d0d30c93..98dfabe0b7be 100644 --- a/service_mesh/v2x/ossm-observability.adoc +++ b/service_mesh/v2x/ossm-observability.adoc @@ -1,22 +1,30 @@ [id="ossm-observability"] -= Data visualization and observability += Metrics and traces include::modules/ossm-document-attributes.adoc[] :context: observability toc::[] -You can view your application's topology, health and metrics in the Kiali console. If your service is having issues, the Kiali console offers ways to visualize the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. It also provides an interactive graph view of your namespace in real time. +You can view your application's topology, health, and metrics in the Kiali console. If your service is experiencing problems, the Kiali console allows you to view the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. It also provides an interactive graph view of your namespace in real time. -You can observe the data flow through your application if you have one installed. If you don't have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm[Bookinfo sample application]. +You can observe the data flow through your application if you have an application installed. If you do not have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_ossm-create-mesh[Bookinfo sample application]. -After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command a few times: +include::modules/ossm-observability-cli.adoc[leveloffset=+1] ----- -$ curl http://$GATEWAY_URL/productpage ----- +include::modules/ossm-observability-access.adoc[leveloffset=+1] -If your sample application is configured correctly, this command simulates a user visiting the `productpage` microservice of the application. +include::modules/ossm-observability-visual.adoc[leveloffset=+2] -include::modules/ossm-observability-access.adoc[leveloffset=+1] +include::modules/ossm-config-dist-trac.adoc[leveloffset=+1] + +include::modules/ossm-tutorial-jaeger-generating-traces.adoc[leveloffset=+2] + +include::modules/ossm-config-sampling.adoc[leveloffset=+2] + +include::modules/ossm-config-external-jaeger.adoc[leveloffset=+2] + +For more information about configuring Jaeger, see the xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc#jaeger-deploy-default_jaeger-deploying[Jaeger documentation]. + +include::modules/ossm-access-grafana.adoc[leveloffset=+1] -include::modules/ossm-observability-visual.adoc[leveloffset=+1] +include::modules/ossm-access-prometheus.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-performance-scalability.adoc b/service_mesh/v2x/ossm-performance-scalability.adoc new file mode 100644 index 000000000000..5d0a8e67991a --- /dev/null +++ b/service_mesh/v2x/ossm-performance-scalability.adoc @@ -0,0 +1,15 @@ +[id="ossm-performance-scalability"] += Performance and scalability +include::modules/ossm-document-attributes.adoc[] +:context: performance-scalability + +toc::[] + +The default `ServiceMeshControlPlane` settings are not intended for production use; they are designed to install successfully on a default {product-title} installation, which is a resource-limited environment. After you have verified a successful SMCP installation, you should modify the settings defined within the SMCP to suit your environment. + +// The following include statements pull in the module files that comprise the assembly. + +include::modules/ossm-recommended-resources.adoc[leveloffset=+1] + +include::modules/ossm-load-test-results.adoc[leveloffset=+1] + diff --git a/service_mesh/v2x/ossm-profiles-users.adoc b/service_mesh/v2x/ossm-profiles-users.adoc new file mode 100644 index 000000000000..69039b2b854d --- /dev/null +++ b/service_mesh/v2x/ossm-profiles-users.adoc @@ -0,0 +1,13 @@ +[id="ossm-profiles-users"] += Managing users and profiles +include::modules/ossm-document-attributes.adoc[] +:context: ossm-profiles-users + +toc::[] + +include::modules/ossm-members.adoc[leveloffset=+1] + +include::modules/ossm-control-plane-profiles.adoc[leveloffset=+1] + +include::modules/ossm-config-network-policy.adoc[leveloffset=+1] + diff --git a/service_mesh/v2x/ossm-reference-jaeger.adoc b/service_mesh/v2x/ossm-reference-jaeger.adoc new file mode 100644 index 000000000000..3f8f4ebc2936 --- /dev/null +++ b/service_mesh/v2x/ossm-reference-jaeger.adoc @@ -0,0 +1,34 @@ +[id="jaeger-config-ref"] += Jaeger configuration reference +include::modules/ossm-document-attributes.adoc[] +:context: jaeger-config-ref + +toc::[] + +When the {ProductShortName} Operator deploys the `ServiceMeshControlPlane` resource, it can also create the resources for distributed tracing. {ProductShortName} uses Jaeger for distributed tracing. + +include::modules/ossm-enabling-jaeger.adoc[leveloffset=+1] + +include::modules/ossm-configuring-jaeger.adoc[leveloffset=+1] + +include::modules/ossm-deploying-jaeger.adoc[leveloffset=+1] + +include::modules/ossm-configuring-external-jaeger.adoc[leveloffset=+1] + +include::modules/jaeger-deployment-best-practices.adoc[leveloffset=+2] + +include::modules/jaeger-config-default.adoc[leveloffset=+2] + +include::modules/jaeger-config-collector.adoc[leveloffset=+2] + +include::modules/jaeger-config-sampling.adoc[leveloffset=+2] + +include::modules/jaeger-config-storage.adoc[leveloffset=+2] + +For more information about configuring Elasticsearch with {product-title}, see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] or xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc[Configuring and deploying Jaeger]. + +For information about connecting to an external Elasticsearch instance, see xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc#jaeger-config-external-es_jaeger-deploying[Connecting to an existing Elasticsearch instance]. + +include::modules/jaeger-config-query.adoc[leveloffset=+2] + +include::modules/jaeger-config-ingester.adoc[leveloffset=+2] diff --git a/service_mesh/v2x/ossm-reference-smcp.adoc b/service_mesh/v2x/ossm-reference-smcp.adoc new file mode 100644 index 000000000000..b4e2950c9c90 --- /dev/null +++ b/service_mesh/v2x/ossm-reference-smcp.adoc @@ -0,0 +1,19 @@ +[id="ossm-reference"] += SMCP configuration reference +include::modules/ossm-document-attributes.adoc[] +:context: ossm-reference + +include::modules/ossm-cr-example.adoc[leveloffset=+1] + +include::modules/ossm-cr-threescale.adoc[leveloffset=+1] + +[id="additional-resources_ossm-reference"] +== Additional resources + +* For more information about how to configure the features in the `ServiceMeshControlPlane`, see the following links: + +** xref:../../service_mesh/v2x/ossm-security.adoc#ossm-security-mtls_ossm-security[Security] + +** xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-routing-bookinfo_routing-traffic[Traffic management] + +** xref:../../service_mesh/v2x/ossm-observability.adoc#ossm-observability[Metrics and traces] diff --git a/service_mesh/v2x/ossm-security.adoc b/service_mesh/v2x/ossm-security.adoc index 727b121828b1..f48dafc1d88c 100644 --- a/service_mesh/v2x/ossm-security.adoc +++ b/service_mesh/v2x/ossm-security.adoc @@ -1,25 +1,29 @@ [id="ossm-security"] -= Customizing security in a Service Mesh += Security include::modules/ossm-document-attributes.adoc[] :context: ossm-security toc::[] -If your service mesh application is constructed with a complex array of microservices, you can use {ProductName} to customize the security of the communication between those services. The infrastructure of {product-title} along with the traffic management features of {ProductShortName} can help you manage the complexity of your applications and provide service and identity security for microservices. -.Before you begin +If your service mesh application is constructed with a complex array of microservices, you can use {ProductName} to customize the security of the communication between those services. The infrastructure of {product-title} along with the traffic management features of {ProductShortName} help you manage the complexity of your applications and secure microservices. -If you have a project, add your project to the xref:../../service_mesh/v2x/installing-ossm.adoc#ossm-member-roll-modify_installing-ossm[`ServiceMeshMemberRoll` resource]. +.Before you begin -[NOTE] -==== -After you add the namespace to the `ServiceMeshMemberRoll`, access to services or pods in that namespace will not be accessible to callers outside the mesh. -==== +If you have a project, add your project to the xref:../../service_mesh/v2x/installing-ossm.adoc#ossm-member-roll-modify_ossm-create-mesh[`ServiceMeshMemberRoll` resource]. -If you don't have a project, install the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm[Bookinfo sample application] and add it to the `ServiceMeshMemberRoll` resource. The sample application helps illustrate security concepts. +If you don't have a project, install the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_ossm-create-mesh[Bookinfo sample application] and add it to the `ServiceMeshMemberRoll` resource. The sample application helps illustrate security concepts. include::modules/ossm-security-mtls.adoc[leveloffset=+1] +include::modules/ossm-config-sec-mtls-mesh.adoc[leveloffset=+2] + +include::modules/ossm-config-sidecar-mtls.adoc[leveloffset=+3] + +include::modules/ossm-config-sidecar-out-mtls.adoc[leveloffset=+2] + +include::modules/ossm-config-mtls-min-max.adoc[leveloffset=+2] + include::modules/ossm-security-auth-policy.adoc[leveloffset=+1] include::modules/ossm-security-cipher.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-support.adoc b/service_mesh/v2x/ossm-support.adoc new file mode 100644 index 000000000000..dc34c3fe8da1 --- /dev/null +++ b/service_mesh/v2x/ossm-support.adoc @@ -0,0 +1,22 @@ +[id="ossm-support"] += Getting support +include::modules/ossm-document-attributes.adoc[] +:context: ossm-support + +toc::[] + +include::modules/support.adoc[leveloffset=+1] + +The `must-gather` tool enables you to collect diagnostic information about your +{product-title} cluster, including virtual machines and other data related to +{ProductName}. You can send that diagnostic information to support for both {product-title} and {ProductName}. + +include::modules/about-must-gather.adoc[leveloffset=+1] + +=== Prerequisites + +* Access to the cluster as a user with the `cluster-admin` role. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role. + +* The {product-title} CLI (`oc`) installed. + +include::modules/ossm-about-collecting-ossm-data.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-traffic-manage.adoc b/service_mesh/v2x/ossm-traffic-manage.adoc index 3d83b2f91acb..8a097a80ac50 100644 --- a/service_mesh/v2x/ossm-traffic-manage.adoc +++ b/service_mesh/v2x/ossm-traffic-manage.adoc @@ -1,18 +1,38 @@ [id="ossm-routing-traffic"] -= Traffic management += Configuring traffic management include::modules/ossm-document-attributes.adoc[] :context: routing-traffic toc::[] -You can control the flow of traffic and API calls between services in {ProductName}. For example, some services in your service mesh may need to communicate within the mesh and others may need to be hidden. Manage the traffic to hide specific backend services, expose services, create testing or versioning deployments, or add a security layer on a set of services. +{ProductName} allows you to control the flow of traffic and API calls between services. Some services in your service mesh may need to communicate within the mesh and others may need to be hidden. Manage the traffic to hide specific backend services, expose services, create testing or versioning deployments, or add a security layer on a set of services. -This guide references the Bookinfo sample application to provide examples of routing in an example application. Install the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm[Bookinfo application] to learn how these routing examples work. +This guide references the Bookinfo sample application to provide examples of routing in an example application. Install the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_ossm-create-mesh[Bookinfo application] to learn how these routing examples work. + +include::modules/ossm-routing-bookinfo-example.adoc[leveloffset=+1] + +include::modules/ossm-routing-bookinfo-applying.adoc[leveloffset=+2] + +include::modules/ossm-routing-bookinfo-test.adoc[leveloffset=+2] + +include::modules/ossm-routing-bookinfo-route.adoc[leveloffset=+2] include::modules/ossm-routing.adoc[leveloffset=+1] include::modules/ossm-routing-ingress.adoc[leveloffset=+1] -include::modules/ossm-routing-bookinfo-example.adoc[leveloffset=+1] +include::modules/ossm-routing-gateways.adoc[leveloffset=+1] + +[id="ossm-auto-route_{context}"] +== Automatic routes + +OpenShift routes for Istio Gateways are automatically managed in {ProductShortName}. Every time an Istio Gateway is created, updated or deleted inside the service mesh, an OpenShift route is created, updated or deleted. + +[id="ossm-auto-route-subdomains_{context}"] +=== Subdomains + +{ProductName} creates the route with the subdomain, but {product-title} must be configured to enable it. Subdomains, for example `*.domain.com`, are supported but not by default. Configure an {product-title} wildcard policy before configuring a wildcard host Gateway. For more information, see xref:../../networking/ingress-operator.adoc#using-wildcard-routes_configuring-ingress[Using wildcard routes]. + +include::modules/ossm-auto-route.adoc[leveloffset=+2] -include::modules/ossm-auto-route.adoc[leveloffset=+1] \ No newline at end of file +include::modules/ossm-routing-sc.adoc[leveloffset=+2] diff --git a/service_mesh/v2x/ossm-vs-community.adoc b/service_mesh/v2x/ossm-vs-community.adoc index 0829dfeb8836..a070aa7717a8 100644 --- a/service_mesh/v2x/ossm-vs-community.adoc +++ b/service_mesh/v2x/ossm-vs-community.adoc @@ -5,17 +5,19 @@ include::modules/ossm-document-attributes.adoc[] toc::[] -An installation of {ProductName} differs from upstream Istio community installations in multiple ways. The modifications to {ProductName} are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on {product-title}. - -The current release of {ProductName} differs from the current upstream Istio community release in the following ways: +{ProductName} differs from an installation of Istio to provide additional features or to handle differences when deploying on {product-title}. // The following include statements pull in the module files that comprise the assembly. -include::modules/ossm-multitenant.adoc[leveloffset=+1] - include::modules/ossm-vs-istio.adoc[leveloffset=+1] +[discrete] +[id="additional-resources_ossm-vs-istio-v2x"] +==== Additional resources -include::modules/ossm-kiali-service-mesh.adoc[leveloffset=+2] +* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-auto-route_routing-traffic[Automatic route creation] + +include::modules/ossm-multitenant.adoc[leveloffset=+1] -include::modules/ossm-jaeger-service-mesh.adoc[leveloffset=+2] +include::modules/ossm-kiali-service-mesh.adoc[leveloffset=+1] +include::modules/ossm-jaeger-service-mesh.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc b/service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc index cb101e29424f..925042cb77b7 100644 --- a/service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc +++ b/service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc @@ -1,35 +1,29 @@ [id="deploying-applications-ossm"] -= Deploying applications on {ProductName} += Enabling sidecar injection include::modules/ossm-document-attributes.adoc[] :context: deploying-applications-ossm toc::[] -When you deploy an application into the {ProductShortName}, there are several differences between the behavior of applications in the upstream community version of Istio and the behavior of applications within a {ProductName} installation. - -== Prerequisites - -* Review xref:../../service_mesh/v2x/ossm-vs-community.adoc#ossm-vs-community[{ProductName} and Istio differences] - -* Review xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[Installing {ProductName}] +After adding your services to a mesh, enable automatic sidecar injection in the deployment resource for your application. You must enable automatic sidecar injection for each deployment. +If you have installed the Bookinfo sample application, the application was deployed and the sidecars were injected. If you are using your own project and service, deploy your applications on {product-title}. For more information, see xref:../../applications/deployments/what-deployments-are.html[Understanding Deployment and DeploymentConfig objects]. -include::modules/ossm-control-plane-profiles.adoc[leveloffset=+1] - -include::modules/ossm-sidecar-injection.adoc[leveloffset=+1] - -include::modules/ossm-automatic-sidecar-injection.adoc[leveloffset=+2] +== Prerequisites -include::modules/ossm-config-network-policy.adoc[leveloffset=+1] +* xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[Adding services to a service mesh] +* A deployment resource for your project -include::modules/ossm-tutorial-bookinfo-overview.adoc[leveloffset=+1] +include::modules/ossm-automatic-sidecar-injection.adoc[leveloffset=+1] -include::modules/ossm-tutorial-bookinfo-install.adoc[leveloffset=+2] +include::modules/ossm-update-app-sidecar.adoc[leveloffset=+1] -include::modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc[leveloffset=+2] +include::modules/ossm-sidecar-injection-env-var.adoc[leveloffset=+1] -include::modules/ossm-tutorial-bookinfo-verify-install.adoc[leveloffset=+2] +== Next steps -include::modules/ossm-tutorial-bookinfo-removing.adoc[leveloffset=+2] +Configure {ProductName} features for your environment. -include::modules/ossm-tutorial-jaeger-generating-traces.adoc[leveloffset=+1] +* xref:../../service_mesh/v2x/ossm-security.adoc#ossm-security[Security] +* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-routing-traffic[Traffic management] +* xref:../../service_mesh/v2x/ossm-observability.adoc#ossm-observability[Metrics and traces] diff --git a/service_mesh/v2x/preparing-ossm-installation.adoc b/service_mesh/v2x/preparing-ossm-installation.adoc index b14a50ce4d26..ce486eb2c625 100644 --- a/service_mesh/v2x/preparing-ossm-installation.adoc +++ b/service_mesh/v2x/preparing-ossm-installation.adoc @@ -2,15 +2,16 @@ = Preparing to install {ProductName} include::modules/ossm-document-attributes.adoc[] :context: preparing-ossm-installation + toc::[] -Before you can install {ProductName}, review the installation activities, ensure that you meet the prerequisites: +Before you can install {ProductName}, you must subscribe to {product-title} and install {product-title} in a supported configuration. == Prerequisites -* Possess an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information. +* Maintain an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information. * Review the xref:../../architecture/architecture-installation.adoc#installation-overview_architecture-installation[{product-title} {product-version} overview]. -* Install {product-title} {product-version}. +* Install {product-title} {product-version}. If you are installing {ProductName} on a xref:../../installing/installing-preparing.adoc#supported-installation-methods-for-different-platforms[restricted network], follow the instructions for your chosen {product-title} infrastructure. ** xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Install {product-title} {product-version} on AWS] ** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Install {product-title} {product-version} on user-provisioned AWS] ** xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install {product-title} {product-version} on bare metal] @@ -18,23 +19,11 @@ Before you can install {ProductName}, review the installation activities, ensure ** xref:../../installing/installing_ibm_z/installing-ibm-z.adoc#installing-ibm-z[Install {product-title} 4.6 on IBM Z and LinuxONE] ** xref:../../installing/installing_ibm_power/installing-ibm-power.adoc#installing-ibm-power[Install {product-title} 4.6 on IBM Power Systems] + -[NOTE] -==== -If you are installing {ProductName} on a xref:../../installing/installing-preparing.adoc#supported-installation-methods-for-different-platforms[restricted network], follow the instructions for your chosen {product-title} infrastructure. -==== -+ * Install the version of the {product-title} command line utility (the `oc` client tool) that matches your {product-title} version and add it to your path. ** If you are using {product-title} {product-version}, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-about-cli_cli-developer-commands[About the OpenShift CLI]. include::modules/ossm-supported-configurations.adoc[leveloffset=+1] -include::modules/ossm-installation-activities.adoc[leveloffset=+1] - -[WARNING] -==== -Please see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] for details on configuring the default Jaeger parameters for Elasticsearch in a production environment. -==== - == Next steps * xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[Install {ProductName}] in your {product-title} environment. diff --git a/service_mesh/v2x/removing-ossm.adoc b/service_mesh/v2x/removing-ossm.adoc index 0118f63a769e..d97a24cf32ff 100644 --- a/service_mesh/v2x/removing-ossm.adoc +++ b/service_mesh/v2x/removing-ossm.adoc @@ -1,13 +1,14 @@ [id="removing-ossm"] -= Removing {ProductName} += Uninstalling {ProductName} include::modules/ossm-document-attributes.adoc[] :context: removing-ossm -toc::[] -This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. +toc::[] -include::modules/ossm-member-roll-delete.adoc[leveloffset=+1] +To uninstall {ProductName} from an existing {product-title} instance and remove its resources, you must delete the control plane, delete the Operators, and run commands to manually remove some resources. include::modules/ossm-control-plane-remove.adoc[leveloffset=+1] -include::modules/ossm-operatorhub-remove.adoc[leveloffset=+1] +include::modules/ossm-remove-operators.adoc[leveloffset=+1] + +include::modules/ossm-remove-cleanup.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/servicemesh-release-notes.adoc b/service_mesh/v2x/servicemesh-release-notes.adoc index 04f642040a49..eb1d50ddac84 100644 --- a/service_mesh/v2x/servicemesh-release-notes.adoc +++ b/service_mesh/v2x/servicemesh-release-notes.adoc @@ -7,32 +7,6 @@ toc::[] // The following include statements pull in the module files that comprise 2.x release notes. -include::modules/ossm-servicemesh-overview.adoc[leveloffset=+1] - -include::modules/support.adoc[leveloffset=+1] - -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=+2] - -=== Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -* The {product-title} CLI (`oc`) installed. - -include::modules/ossm-about-collecting-ossm-data.adoc[leveloffset=+2] - -include::modules/ossm-supported-configurations.adoc[leveloffset=+1] - include::modules/ossm-rn-new-features.adoc[leveloffset=+1] include::modules/ossm-rn-technology-preview.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/threescale-adapter.adoc b/service_mesh/v2x/threescale-adapter.adoc index bd816da1d48f..28c36ff987de 100644 --- a/service_mesh/v2x/threescale-adapter.adoc +++ b/service_mesh/v2x/threescale-adapter.adoc @@ -2,6 +2,7 @@ = Using the 3scale Istio adapter include::modules/ossm-document-attributes.adoc[] :context: threescale-adapter + toc::[] The 3scale Istio Adapter is an optional adapter that allows you to label a service running within the {ProductName} and integrate that service with the 3scale API Management solution. @@ -9,7 +10,7 @@ It is not required for {ProductName}. [IMPORTANT] ==== -If you want to enable 3scale backend cache with the 3scale Istio adapter, you must also enable Mixer policy and Mixer telemetry. See xref:../../service_mesh/v2x/installing-ossm.adoc#ossm-control-plane-deploy_installing-ossm[Deploying the Red Hat OpenShift Service Mesh control plane]. +If you want to enable 3scale backend cache with the 3scale Istio adapter, you must also enable Mixer policy and Mixer telemetry. See xref:../../service_mesh/v2x/ossm-create-smcp.adoc#ossm-create-smcp[Deploying the Red Hat OpenShift Service Mesh control plane]. ==== include::modules/ossm-threescale-integrate.adoc[leveloffset=+1] @@ -33,3 +34,10 @@ include::modules/ossm-threescale-metrics.adoc[leveloffset=+1] include::modules/threescale-backend-cache.adoc[leveloffset=+1] include::modules/threescale-istio-adapter-apicast.adoc[leveloffset=+1] + +include::modules/ossm-threescale-istio-adapter-verification.adoc[leveloffset=+1] + +.Additional resources +* link:https://docs.openshift.com/container-platform/4.7/support/troubleshooting/investigating-pod-issues.html#inspecting-pod-and-container-logs_investigating-pod-issues[Inspecting pod and container logs]. + +include::modules/ossm-threescale-istio-adapter-troubleshooting-checklist.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/upgrading-ossm.adoc b/service_mesh/v2x/upgrading-ossm.adoc index ff434bd24c62..98643502099c 100644 --- a/service_mesh/v2x/upgrading-ossm.adoc +++ b/service_mesh/v2x/upgrading-ossm.adoc @@ -2,9 +2,10 @@ = Upgrading {ProductName} from version 1.1 to version 2.0 include::modules/ossm-document-attributes.adoc[] :context: upgrading-ossm + toc::[] -To access the most current features of {ProductName}, upgrade to the current version, 2.0. Upgrading from version 1.1 to 2.0 requires manual steps that migrate your workloads and apps to a new instance of {ProductName} running the new version. +Upgrading from version 1.1 to 2.0 requires manual steps that migrate your workloads and application to a new instance of {ProductName} running the new version. .Prerequisites @@ -54,7 +55,7 @@ $ oc patch smcp.v1.maistra.io --type json --patch '[{"op": "replace" $ oc edit smcp.v1.maistra.io ---- + -. Back up your control plane configuration. Switch to the project that contains your `ServiceMeshControlPlane` resource. +. Back up your control plane configuration. Switch to the project that contains your `ServiceMeshControlPlane` resource. In this example, `istio-system` is the name of the control plane project. + [source,terminal] ---- @@ -101,7 +102,7 @@ Alternatively, you can use the console to create the control plane. In the {prod .. Click *Create*. [id="ossm-upgrading-differences_{context}"] -== Configuring the 2.0 `ServiceMeshControlPlane` +== Configuring the 2.0 ServiceMeshControlPlane The `ServiceMeshControlPlane` resource has been changed for {ProductName} version 2.0. After you created a v2 version of the `ServiceMeshControlPlane` resource, modify it to take advantage of the new features and to fit your deployment. Consider the following changes to the specification and behavior of {ProductName} 2.0 as you're modifying your `ServiceMeshControlPlane` resource. You can also refer to the {ProductName} 2.0 product documentation for new information to features you use. The v2 resource must be used for {ProductName} 2.0 installations. @@ -123,7 +124,7 @@ The following annotations are no longer supported in v2.0. If you are using one * `sidecar.maistra.io/proxyMemoryLimit` has been replaced with `sidecar.istio.io/proxyMemoryLimit` * `sidecar.istio.io/discoveryAddress` is no longer supported. Also, the default discovery address has moved from `pilot..svc:15010` (or port 15011, if mtls is enabled) to `istiod-..svc:15012`. * The health status port is no longer configurable and is hard-coded to 15021. * If you were defining a custom status port, for example, `status.sidecar.istio.io/port`, you must remove the override before moving the workload to a v2.0 control plane. Readiness checks can still be disabled by setting the status port to `0`. -* Kubernetes Secret resources are no longer used to distribute client certificates for sidecars. Certificates are now distributed through Istiod’s SDS service. If you were relying on mounted secrets, they are longer available for workloads in v2.0 control planes. +* Kubernetes Secret resources are no longer used to distribute client certificates for sidecars. Certificates are now distributed through Istiod's SDS service. If you were relying on mounted secrets, they are longer available for workloads in v2.0 control planes. [id="ossm-upgrading-differences-behavior_{context}"] === Behavioral changes @@ -144,7 +145,7 @@ Policy resources must be migrated to new resource types for use with v2.0 contro .Mutual TLS -Mutual TLS enforcement is accomplished using the `security.istio.io/v1beta1` PeerAuthentication resource. The legacy `spec.peers.mtls.mode` field maps directly to the new resource’s `spec.mtls.mode` field. Selection criteria has changed from specifying a service name in `spec.targets[x].name` to a label selector in `spec.selector.matchLabels`. In PeerAuthentication, the labels must match the selector on the services named in the targets list. Any port-specific settings will need to be mapped into `spec.portLevelMtls`. +Mutual TLS enforcement is accomplished using the `security.istio.io/v1beta1` PeerAuthentication resource. The legacy `spec.peers.mtls.mode` field maps directly to the new resource's `spec.mtls.mode` field. Selection criteria has changed from specifying a service name in `spec.targets[x].name` to a label selector in `spec.selector.matchLabels`. In PeerAuthentication, the labels must match the selector on the services named in the targets list. Any port-specific settings will need to be mapped into `spec.portLevelMtls`. .Authentication @@ -173,7 +174,7 @@ AuthorizationPolicy includes configuration for both the selector to which the co .ServiceMeshRbacConfig (maistra.io/v1) -This resource is replaced by using a `security.istio.io/v1beta1` AuthorizationPolicy resource with an empty spec.selector in the control plane’s namespace. This policy will be the default authorization policy applied to all workloads in the mesh. For specific migration details, see RbacConfig above. +This resource is replaced by using a `security.istio.io/v1beta1` AuthorizationPolicy resource with an empty spec.selector in the control plane's namespace. This policy will be the default authorization policy applied to all workloads in the mesh. For specific migration details, see RbacConfig above. [id="ossm-upgrading-mig-mixer_{context}"] === Mixer plugins @@ -209,7 +210,7 @@ When using mTLS with workload specific PeerAuthentication policies, a correspond Auto mTLS is enabled by default, but can be disabled by setting `spec.security.dataPlane.automtls` to false in the `ServiceMeshControlPlane` resource. When disabling auto mTLS, DestinationRules may be required for proper communication between services. For example, setting PeerAuthentication to `STRICT` for one namespace may prevent services in other namespaces from accessing them, unless a DestinationRule configures TLS mode for the services in the namespace. -For information about mTLS, see xref:../../service_mesh/v2x/ossm-security.adoc#ossm-security-mtls_ossm-security[Enabling mutual Transport Layer Security (mTLS)] +For information about mTLS, see xref:../../service_mesh/v2x/ossm-security.html#ossm-security-mtls_ossm-security[Enabling mutual Transport Layer Security (mTLS)] ==== Other mTLS Examples @@ -362,12 +363,12 @@ Mutual TLS for data plane communication is configured through `spec.security.dat [id="ossm-upgrading-config-sign-key_{context}"] === Custom signing key -Istiod manages client certificates and private keys used by service proxies. By default, Istiod uses a self-signed certificate for signing, but you can configure a custom certificate and private key. For more information about how to configure signing keys, see xref:../../service_mesh/v2x/ossm-security.html#ossm-cert-manage_ossm-security[Adding an external certificate authority key and certificate] +Istiod manages client certificates and private keys used by service proxies. By default, Istiod uses a self-signed certificate for signing, but you can configure a custom certificate and private key. For more information about how to configure signing keys, see xref:../../service_mesh/v2x/ossm-security.adoc#ossm-cert-manage_ossm-security[Adding an external certificate authority key and certificate] [id="ossm-upgrading-config-tracing_{context}"] === Tracing -_Tracing_ is configured under `spec.tracing`. Currently, the only type of tracer that is supported is `Jaeger`. Sampling is a scaled integer representing 0.01% increments, for example, 1 is 0.01% and 10000 is 100%. The tracing implementation and sampling rate can be specified: +Tracing is configured in `spec.tracing`. Currently, the only type of tracer that is supported is `Jaeger`. Sampling is a scaled integer representing 0.01% increments, for example, 1 is 0.01% and 10000 is 100%. The tracing implementation and sampling rate can be specified: [source,yaml] ---- @@ -377,7 +378,7 @@ spec: type: Jaeger ---- -_Jaeger_ is configured under the addons section of the SMCP spec. +Jaeger is configured in the addons section of the `ServiceMeshControlPlane` resource. [source,yaml] ---- @@ -429,7 +430,7 @@ spec: install: {} # customize install ---- -The Grafana and Kiali installations can be somewhat customized through their respective `install` fields. Container customization, such as resource limits, is configured in `spec.runtime.components.kiali` and `spec.runtime.components.grafana`. If an existing Kiali resource matching the value of name exists, the control plane configures the Kiali resource for use with the control plane. Some fields in the Kiali resource are overridden, such as the `accessible_namespaces` list, as well as the endpoints for Grafana, Prometheus, and tracing. Use an existing resource to fully customize your Kiali installation. +The Grafana and Kiali installations can be customized through their respective `install` fields. Container customization, such as resource limits, is configured in `spec.runtime.components.kiali` and `spec.runtime.components.grafana`. If an existing Kiali resource matching the value of name exists, the control plane configures the Kiali resource for use with the control plane. Some fields in the Kiali resource are overridden, such as the `accessible_namespaces` list, as well as the endpoints for Grafana, Prometheus, and tracing. Use an existing resource to fully customize your Kiali installation. === Resource utilization and scheduling @@ -515,7 +516,7 @@ Resources are configured under `spec.runtime.`. The following compone |v2.0 - tech preview |=== -For an example, of how to configure Pilot resource scheduling see xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-cr-pilot_ossm-custom-resources-v2x[Istio Pilot configuration] +Some components support resource limiting and scheduling. For more information, see xref:../../service_mesh/v2x/ossm-performance-scalability.adoc#ossm-performance-scalability[Performance and scalability]. [id="ossm-upgrading-mig-apps_{context}"] == Next steps for migrating your applications and workflows