diff --git a/_topic_map.yml b/_topic_map.yml index e80024ca2361..481a718eb784 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2527,8 +2527,6 @@ Topics: File: ossm-about - Name: Service Mesh 2.x release notes File: servicemesh-release-notes - - Name: Service Mesh support - File: ossm-support - Name: Service Mesh architecture File: ossm-architecture - Name: Service Mesh and Istio differences @@ -2561,6 +2559,8 @@ Topics: File: ossm-extensions - Name: Using the 3scale Istio adapter File: threescale-adapter + - Name: Troubleshooting Service Mesh + File: ossm-troubleshooting-istio - Name: SMCP configuration reference File: ossm-reference-smcp - Name: Jaeger configuration reference diff --git a/modules/ossm-about-collecting-ossm-data.adoc b/modules/ossm-about-collecting-ossm-data.adoc index 00701b08f767..701fa41128a6 100644 --- a/modules/ossm-about-collecting-ossm-data.adoc +++ b/modules/ossm-about-collecting-ossm-data.adoc @@ -9,15 +9,23 @@ 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. +.Prerequisites +* Access to the cluster as a user with the `cluster-admin` role. + +* The {product-title} CLI (`oc`) installed. + +.Precedure + +. To collect {ProductName} data with `must-gather`, you must specify the {ProductName} image. ++ [source,terminal] ---- $ oc adm must-gather --image=registry.redhat.io/openshift-service-mesh/istio-must-gather-rhel8 ---- - -To collect {ProductName} data for a specific control plane namespace with `must-gather`, you must specify the {ProductName} image and namespace. In this example, replace `` with your control plane namespace, such as `istio-system`. - ++ +. To collect {ProductName} data for a specific control plane namespace with `must-gather`, you must specify the {ProductName} image and namespace. In this example, replace `` with your control plane namespace, such as `istio-system`. ++ [source,terminal] ---- $ oc adm must-gather --image=registry.redhat.io/openshift-service-mesh/istio-must-gather-rhel8 gather diff --git a/modules/ossm-accessing-jaeger.adoc b/modules/ossm-accessing-jaeger.adoc new file mode 100644 index 000000000000..3a1ad47bbd65 --- /dev/null +++ b/modules/ossm-accessing-jaeger.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-accessing-jaeger_{context}"] += Accessing the Jaeger console +//// +(how to find the URL) +Installed Operators > Jaeger Operator > Jaeger > Jaeger Details > Resources > Route > Location = Link +Networking > Routes> search Jaeger route (Location = Link) +Kiali Console > Distributed Tracing tab +//// + +The installation process creates a route to access the Jaeger console. + +.Procedure +. Log in to the {Product-title} console. + +. Navigate to *Networking* -> *Routes* and +search for the Jaeger route, which is the URL listed under *Location*. + +. To query for details of the route using the command line, enter the following command. In this example, `istio-system` is the control plane namespace. ++ +[source,terminal] +---- +$ export JAEGER_URL=$(oc get route -n istio-system jaeger -o jsonpath='{.spec.host}') +---- ++ +. Launch a browser and navigate to ``\https://``, where `` is the route that you discovered in the previous step. + +. Log in using the same user name and password that you use to access the {Product-title} console. + +. If you have added services to the service mesh and have generated traces, you can use the filters and *Find Traces* button to search your trace data. ++ +If you are validating the console installation, there is no trace data to display. diff --git a/modules/ossm-accessing-kiali.adoc b/modules/ossm-accessing-kiali.adoc new file mode 100644 index 000000000000..9ddb33b16076 --- /dev/null +++ b/modules/ossm-accessing-kiali.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-accessing-kiali_{context}"] += Accessing the Kiali console + +//// +(how to find the URL to get to the Kiali console) +Installed Operators > Kiali Operator > Kiali > Kiali Details > Resources > Route > Location = Link +Networking > Routes> search Kiali route (Location = Link) +CLI = oc get routes +//// + +The installation process creates a route to access the Kiali console. + +.Procedure + +. Log in to the {Product-title} console. + +. Use the perspective switcher to switch to the *Administrator* perspective. + +. Click *Home* -> *Projects*. + +. Click the name of your project. For example click `bookinfo`. + +. In the *Launcher* section, click *Kiali*. + +. Log in to the Kiali console with the same user name and password that you use to access the {product-title} console. + +When you first log in to the Kiali Console, you see the *Overview* page which displays all the namespaces in your service mesh that you have permission to view. + +If you are validating the console installation, there might not be any data to display. diff --git a/modules/ossm-observability-access.adoc b/modules/ossm-observability-access.adoc index d598e02385eb..017984198e55 100644 --- a/modules/ossm-observability-access.adoc +++ b/modules/ossm-observability-access.adoc @@ -12,14 +12,16 @@ To access the Kiali console you must have {ProductName} installed and projects c .Procedure -. Use the perspective switcher to switch to the Administrator perspective. +. Use the perspective switcher to switch to the *Administrator* perspective. -. Click *Home* > *Projects*. +. Click *Home* -> *Projects*. -. Click the name of your project. For example click `bookinfo`. +. Click the name of your project. For example, click `bookinfo`. -. In the Launcher section, click `Kiali`. +. In the *Launcher* section, click *Kiali*. . Log in to the Kiali console with the same user name and password that you use to access the {product-title} console. -When you first log in to the Kiali Console, you see the Overview page which displays all the namespaces in your mesh that you have permission to view. +When you first log in to the Kiali Console, you see the *Overview* page which displays all the namespaces in your service mesh that you have permission to view. + +If you are validating the console installation, there might not be any data to display. diff --git a/modules/ossm-troubleshooting-injection.adoc b/modules/ossm-troubleshooting-injection.adoc new file mode 100644 index 000000000000..188f16d26005 --- /dev/null +++ b/modules/ossm-troubleshooting-injection.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-troubleshooting-injection_{context}"] += Troubleshooting sidecar injection + +{ProductName} does not automatically inject proxy sidecars to pods. You must opt in to sidecar injection. + +== Troubleshooting Istio sidecar injection + +Check to see if automatic injection is enabled in the Deployment for your application. If automatic injection for the Envoy proxy is enabled, there should be a `sidecar.istio.io/inject:"true"` annotation in the `Deployment` resource under `spec.template.metadata.annotations`. + +== Troubleshooting Jaeger agent sidecar injection + +Check to see if automatic injection is enabled in the Deployment for your application. If automatic injection for the Jaeger agent is enabled, there should be a `sidecar.jaegertracing.io/inject:"true"` annotation in the `Deployment` resource. diff --git a/modules/ossm-troubleshooting-operators.adoc b/modules/ossm-troubleshooting-operators.adoc new file mode 100644 index 000000000000..2914f1823287 --- /dev/null +++ b/modules/ossm-troubleshooting-operators.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-troubleshooting-operators_{context}"] += Troubleshooting service mesh Operators + +If you experience Operator issues: + +* Verify your Operator subscription status. +* Verify that you did not install a community version of the Operator, instead of the supported Red Hat version. +* Verify that you have the `cluster-admin` role to install {ProductName}. +* Check for any errors in the Operator pod logs if the issue is related to installation of Operators. + +[NOTE] +==== +You can install Operators only through the OpenShift console, the OperatorHub is not accessible from the command line. +==== + +== Viewing Operator pod logs + +You can view Operator logs by using the `oc logs` command. Red Hat may request logs to help resolve support cases. + +.Procedure + +* To view Operator pod logs, enter the command: ++ +[source,terminal] +---- +$ oc logs -n openshift-operators +---- ++ +For example, ++ +[source,terminal] +---- +$ oc logs -n openshift-operators istio-operator-bb49787db-zgr87 +---- + +//If your pod fails to start, you may need to use the `--previous` option to see the logs of the last attempt. diff --git a/modules/ossm-troubleshooting-proxy.adoc b/modules/ossm-troubleshooting-proxy.adoc new file mode 100644 index 000000000000..8e95831d8ce2 --- /dev/null +++ b/modules/ossm-troubleshooting-proxy.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-troubleshooting-proxy_{context}"] += Troubleshooting Envoy proxy + +The Envoy proxy intercepts all inbound and outbound traffic for all services in the service mesh. Envoy also collects and reports telemetry on the service mesh. Envoy is deployed as a sidecar to the relevant service in the same pod. + +== Enabling Envoy access logs + +Envoy access logs are useful in diagnosing traffic failures and flows, and help with end-to-end traffic flow analysis. + +To enable access logging for all istio-proxy containers, edit the `ServiceMeshControlPlane` (SMCP) object to add a file name for the logging output. + +.Procedure + +. Log in to the OpenShift Container Platform CLI as a user with the cluster-admin role. Enter the following command. Then, enter your username and password when prompted. ++ +[source,terminal] +---- +$ oc login https://{HOSTNAME}:6443 +---- ++ +. Change to the project where you installed the control plane, for example `istio-system`. ++ +[source,terminal] +---- +$ oc project istio-system +---- ++ +. Edit the `ServiceMeshControlPlane` file. ++ +[source,terminal] +---- +$ oc edit smcp +---- ++ +. As show in the following example, use `name` to specify the file name for the proxy log. If you do not specify a value for `name`, no log entries will be written. ++ +[source,yaml] +---- +spec: + proxy: + accessLogging: + file: + name: /dev/stdout #file name +---- diff --git a/modules/ossm-troubleshooting-smcp.adoc b/modules/ossm-troubleshooting-smcp.adoc new file mode 100644 index 000000000000..856c3f8ea39d --- /dev/null +++ b/modules/ossm-troubleshooting-smcp.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-troubleshooting-smcp_{context}"] += Troubleshooting the Service Mesh control plane + +If you are experiencing issues while deploying the Service Mesh control plane, + +* Ensure that the `ServiceMeshControlPlane` resource is installed in a project that is separate from your services and Operators. This documentation uses the `istio-system` project as an example, but you can deploy your control plane in any project as long as it is separate from the project that contains your Operators and services. + +* Ensure that the `ServiceMeshControlPlane` and `Jaeger` custom resources are deployed in the same project. For example, use the `istio-system` project for both. + +//* If you selected to install the Elasticsearch Operator in a specific namespace in the cluster instead of selecting *All namespaces in on the cluster (default)*, then OpenShift could not automatically copy the Operator to the istio-system namespace and the Jaeger Operator could not call the Elasticsearch Operator during the installation? + +//The steps for deploying the service mesh control plane (SMCP) include verifying the deployment in the OpenShift console. diff --git a/modules/ossm-understanding-versions.adoc b/modules/ossm-understanding-versions.adoc new file mode 100644 index 000000000000..c9f7936e9e00 --- /dev/null +++ b/modules/ossm-understanding-versions.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// * service_mesh/v1x/upgrading-ossm.adoc ??? +// * service_mesh/v2x/upgrading-ossm.adoc +// * service_mesh/v2x/ossm-troubleshooting.adoc + +[id="ossm-versions_{context}"] += Understanding Service Mesh versioning + +The {ProductName} 2.0 Operator supports both v1 and v2 service meshes. + +* *Operator* version - The current Operator version is {ProductVersion}. This version number only indicates the version of the currently installed Operator. This version number is controlled by the intersection of the *Update Channel* and *Approval Strategy* specified in your Operator subscription. The version of the Operator does not determine which version of the `ServiceMeshControlPlane` resource is deployed. Upgrading to the latest Operator does *not* automatically upgrade your service mesh control plane to the latest version. ++ +[IMPORTANT] +==== +Upgrading to the latest Operator version does not automatically upgrade your control plane to the latest version. +==== ++ +* *ServiceMeshControlPlane* version - The same Operator supports multiple versions of the service mesh control plane. The service mesh control plane version controls the architecture and configuration settings that are used to install and deploy {ProductName}. To set or change the service mesh control plane version, you must deploy a new control plane. When you create the service mesh control plane you can select the version in one of two ways: + +** To configure in the Form View, select the version from the *Control Plane Version* menu. + +** To configure in the YAML View, set the value for `spec.version` in the YAML file. + +* *Control Plane* version - The version parameter specified within the SMCP resource file as `spec.version`. Supported versions are v1.1 and v2.0. + +The Operator Lifecycle Manager (OLM) does not manage upgrades from v1 to v2, so the version number for your Operator and `ServiceMeshControlPlane` (SMCP) may not match, unless you have manually upgraded your SMCP. diff --git a/modules/ossm-validating-operators.adoc b/modules/ossm-validating-operators.adoc new file mode 100644 index 000000000000..5e2192798dfe --- /dev/null +++ b/modules/ossm-validating-operators.adoc @@ -0,0 +1,65 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-validating-operators_{context}"] += Validating Operator installation + +//The Operator installation steps include verifying the Operator status in the OpenShift console. + +When you install the {ProductName} Operators, OpenShift automatically creates the following objects as part of a successful Operator installation: + +* config maps +* custom resource definitions +* deployments +* pods +* replica sets +* roles +* role bindings +* secrets +* service accounts +* services + +.From the Openshift console + +You can verify that the Operator pods are available and running by using the {product-title} Console. + +. Navigate to *Workloads* -> *Pods*. +. Select the `openshift-operators` namespace. +. Verify that the following pods exist and have a status of `running`: +** `istio-operator` +** `jaeger-operator` +** `kiali-operator` +. Select the `openshift-operators-redhat` namespace. +. Verify that the `elasticsearch-operator` pod exists and has a status of `running`. + +.From the command line + +. Verify the Operator pods are available and running in the `openshift-operators` namespace with the following command: ++ +[source,terminal] +---- +$ oc get pods -n openshift-operators +---- ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +istio-operator-bb49787db-zgr87 1/1 Running 0 15s +jaeger-operator-7d5c4f57d8-9xphf 1/1 Running 0 2m42s +kiali-operator-f9c8d84f4-7xh2v 1/1 Running 0 64s +---- ++ +. Verify the Elasticsearch operator with the following command: ++ +[source,terminal] +---- +$ oc get pods -n openshift-operators-redhat +---- ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +elasticsearch-operator-d4f59b968-796vq 1/1 Running 0 15s +---- diff --git a/modules/ossm-validating-smcp.adoc b/modules/ossm-validating-smcp.adoc new file mode 100644 index 000000000000..ca9c4b28de36 --- /dev/null +++ b/modules/ossm-validating-smcp.adoc @@ -0,0 +1,100 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-validating-smcp_{context}"] += Validating the Service Mesh control plane installation + +When you create the Service Mesh control plane, the {ProductShortName} Operator uses the parameters that you have specified in the `ServiceMeshControlPlane` resource file to do the following: + +* Creates the Istio components and deploys the following pods: +** `istiod` +** `istio-ingressgateway` +** `istio-egressgateway` +** `grafana` +** `prometheus` +* Calls the Kiali Operator to create Kaili deployment based on configuration in either the SMCP or the Kiali custom resource. ++ +[NOTE] +==== +You view the Kiali components under the Kiali Operator, not the {ProductShortName} Operator. +==== ++ +* Calls the Jaeger Operator to create Jaeger components based on configuration in either the SMCP or the Jaeger custom resource. ++ +[NOTE] +==== +You view the Jaeger components under the Jaeger Operator and the Elasticsearch components under the Elasticsearch Operator, not the {ProductShortName} Operator. +==== ++ +.From the Openshift console + +You can verify the Service Mesh control plane installation in the OpenShift web console. + +. Navigate to *Operators* -> *Installed Operators*. +. Select the `` namespace. +. Select the {ProductName} Operator. +. Click the *Istio Service Mesh Control Plane* tab. +. Click the name of your control plane, for example `basic`. +. To view the resources created by the deployment, click the *Resources* tab. You can use the filter to narrow your view, for example, to check that all the *Pods* have a status of `running`. +. If the SMCP status indicates any problems, check the `status:` output in the YAML file for more information. + +.From the command line + +. Execute the following command to see if the control plane pods are available and running, where `istio-system` is the namespace where you installed the SMCP. ++ +[source,terminal] +---- +$ oc get pods -n istio-system +---- ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +grafana-6c47888749-dsztv 2/2 Running 0 37s +istio-egressgateway-85fdc5b466-dgqgt 1/1 Running 0 36s +istio-ingressgateway-844f785b79-pxbvb 1/1 Running 0 37s +istiod-basic-c89b5b4bb-5jh8b 1/1 Running 0 104s +jaeger-6ff889f874-rz2nm 2/2 Running 0 34s +prometheus-578df79589-p7p9k 3/3 Running 0 69s +---- ++ +. Check the status of the control plane deployment with the following command, where `istio-system` is the namespace where you deployed the SMCP. ++ +[source,terminal] +---- +$ oc get smcp -n +---- ++ +The installation has finished successfully when the STATUS column is `ComponentsReady`. ++ +.Example output +[source,terminal] +---- +NAME READY STATUS PROFILES VERSION AGE +basic 9/9 ComponentsReady ["default"] 2.0.1.1 19m +---- + ++ +If you have modified and redeployed your control plane, the status should read `UpdateSuccessful`. ++ +.Example output +[source,terminal] +---- +NAME READY STATUS TEMPLATE VERSION AGE +basic-install 9/9 UpdateSuccessful default v1.1 3d16h +---- ++ +. If the SMCP status indicates anything other than `ComponentsReady` check the `status:` output in the SCMP resource for more information. ++ +[source,terminal] +---- +$ oc describe smcp -n +---- ++ +.Example output ++ +[source,terminal] +---- +$ oc describe smcp basic -n istio-system +---- diff --git a/service_mesh/v2x/ossm-troubleshooting-istio.adoc b/service_mesh/v2x/ossm-troubleshooting-istio.adoc new file mode 100644 index 000000000000..6bc57d05286f --- /dev/null +++ b/service_mesh/v2x/ossm-troubleshooting-istio.adoc @@ -0,0 +1,68 @@ +[id="ossm-troubleshooting"] += Troubleshooting your service mesh +include::modules/ossm-document-attributes.adoc[] +:context: troubleshooting-ossm + +toc::[] + +This section describes how to identify and resolve common problems in {ProductName}. Use the following sections to help troubleshoot and debug problems when deploying {ProductName} on {product-title}. + +// The following include statements pull in the module files that comprise the assembly. + +include::modules/ossm-understanding-versions.adoc[leveloffset=+1] + +== Troubleshooting Operator installation + +In addition to the information in this section, be sure to review the following topics: + +* xref:../../operators/understanding/olm-what-operators-are.adoc[What are Operators?] + +* xref:../../operators/understanding/olm/olm-understanding-olm.adoc[Operator Lifecycle Management concepts]. + +* xref:../../support/troubleshooting/troubleshooting-operator-issues.adoc[OpenShift Operator troubleshooting section]. + +* xref:../../support/troubleshooting/troubleshooting-installations.adoc[OpenShift installation troubleshooting section]. + +include::modules/ossm-validating-operators.adoc[leveloffset=+2] + +include::modules/ossm-troubleshooting-operators.adoc[leveloffset=+2] + +== Troubleshooting the control plane + +The Service Mesh _control plane_ is composed of Istiod, which consolidates several previous control plane components (Citadel, Galley, Pilot) into a single binary. Deploying the `ServiceMeshControlPlane` also creates the other components that make up {ProductName} as described in the xref:../../service_mesh/v2x/ossm-architecture.adoc#ossm-architecture_ossm-architecture[architecture] topic. + +include::modules/ossm-validating-smcp.adoc[leveloffset=+2] + +include::modules/ossm-accessing-kiali.adoc[leveloffset=+3] + +include::modules/ossm-accessing-jaeger.adoc[leveloffset=+3] + +include::modules/ossm-troubleshooting-smcp.adoc[leveloffset=+2] + +== Troubleshooting the data plane + +The _data plane_ is a set of intelligent proxies that intercept and control all inbound and outbound network communications between services in the service mesh. + +{ProductName} relies on a proxy sidecar within the application’s pod to provide service mesh capabilities to the application. + +include::modules/ossm-troubleshooting-injection.adoc[leveloffset=+2] + +For more information about sidecar injection, see xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-automatic-sidecar-injection_deploying-applications-ossm[Enabling automatic injection] + +include::modules/ossm-troubleshooting-proxy.adoc[leveloffset=2] + +For more information about troubleshooting pod issues, see xref:../../support/troubleshooting/investigating-pod-issues.adoc[Investigating pod issues] + +include::modules/support.adoc[leveloffset=+1] + +include::modules/support-knowledgebase-about.adoc[leveloffset=+2] + +include::modules/support-knowledgebase-search.adoc[leveloffset=+2] + +include::modules/about-must-gather.adoc[leveloffset=+2] + +include::modules/ossm-about-collecting-ossm-data.adoc[leveloffset=+2] + +For prompt support, supply diagnostic information for both {product-title} and {ProductName}. + +include::modules/support-submitting-a-case.adoc[leveloffset=+2]