7298-IstioAdapterTroubleshooting: Added a troubleshooting section for the 3scale Istio Adapter.

Author: dfennessy

modules/ossm-threescale-istio-adapter-troubleshooting-checklist.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc
+// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc
+
+[id="ossm-threescale-istio-adapter-troubleshooting-checklist_{context}"]
+= 3scale Istio adapter troubleshooting checklist
+
+As the administrator installing the 3scale Istio adapter, there are a number of scenarios that might be causing your integration to not function properly. Use the following list to troubleshoot your installation:
+
+* Incorrect YAML indentation.
+* Missing YAML sections.
+* Forgot to apply the changes in the YAML to the cluster.
+* Forgot to label the service workloads with the `service-mesh.3scale.net/credentials` key.
+* Forgot to label the service workloads with `service-mesh.3scale.net/service-id` when using handlers that do not contain a `service_id` so they are reusable per account.
+* The _Rule_ custom resource points to the wrong handler or instance custom resources, or the references lack the corresponding namespace suffix.
+* The _Rule_ custom resource `match` section cannot possibly match the service you are configuring, or it points to a destination workload that is not currently running or does not exist.
+* Wrong access token or URL for the 3scale Admin Portal in the handler.
+* The _Instance_ custom resource's `params/subject/properties` section fails to list the right parameters for `app_id`, `app_key`, or `client_id`, either because they specify the wrong location such as the query parameters, headers, and authorization claims, or the parameter names do not match the requests used for testing.
+* Failing to use the configuration generator without realizing that it actually lives in the adapter container image and needs `oc exec` to invoke it.

modules/ossm-threescale-istio-adapter-verification.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc
+// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc
+
+[id="ossm-threescale-istio-adapter-verification_{context}"]
+= 3scale Istio adapter verification
+
+You might want to check whether the 3scale Istio adapter is working as expected. If your adapter is not working, use the following steps to help troubleshoot the problem.
+
+.Procedure
+
+. Ensure the _3scale-adapter_ pod is running in the control plane namespace:
++
+[source,terminal]
+----
+$ oc get pods -n <istio-system>
+----
+. Check that the _3scale-adapter_ pod has printed out information about itself booting up, such as its version:
++
+[source,terminal]
+----
+$ oc logs <istio-system>
+----
+. When performing requests to the services protected by the 3scale adapter integration, always try requests that lack the right credentials and ensure they fail. Check the 3scale adapter logs to gather additional information.

service_mesh/v1x/threescale-adapter.adoc

@@ -26,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]

service_mesh/v2x/threescale-adapter.adoc

@@ -34,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]