Skip to content

Commit 4d0fda9

Browse files
ShaunaDiazShaunaDiaz
committed
OSDOCS-18945: adds troubleshooting MCP gateway
1 parent cab138f commit 4d0fda9

4 files changed

Lines changed: 210 additions & 1 deletion

‎modules/proc-mcp-gateway-ts-gateway-listener-not-working.adoc‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
2+
// Module included in the following assemblies:
3+
//
4+
// *mcp_gateway_config/mcp-gateway-troubleshooting.adoc
5+
6+
:_mod-docs-content-type: PROCEDURE
7+
[id="proc-mcp-gateway-ts-gateway-listener-not-working_{context}"]
8+
= Troubleshooting the gateway listener not working
9+
10+
[role="_abstract"]
11+
If your MCP gateway cannot reach an MCP endpoint at configured hostname, the cause might be that the `Listener` custom resource (CR) you configured is not working. You can troubleshoot this situation by using a few commands and some insight.
12+
13+
Use the following concepts in conjunction with the commands that follow to solve a non-functioning `Listener` CR:
14+
15+
* Ensure that your `Gateway` object has `Accepted` and `Programmed` conditions set to `True`.
16+
* Verify that the `hostname` in the `Listener `CR matches your DNS or hosts configuration.
17+
18+
.Prerequisites
19+
20+
* You installed {mcpg}.
21+
* You installed {prodname}.
22+
* You configured a `Gateway` object.
23+
* You configured an `HTTPRoute` object for the gateway.
24+
* You installed the {oc-first}.
25+
* You registered an MCP server.
26+
27+
.Procedure
28+
29+
. Check the general `Gateway` object configuration by running the following command:
30+
+
31+
[source,terminal]
32+
----
33+
$ oc get gateway -A
34+
----
35+
+
36+
This command returns general information about all `Gateway` objects in the cluster. If the `Gateway` object you are troubleshooting does exist, the command returns the `gatewayClassName` is it using, whether or not it has an IP address or hostname assigned, and a `status`, such as `Ready`, `Programmed`, or `Pending`.
37+
38+
. Check the full metadata and status history for one specific `Gateway` object by running the following command:
39+
+
40+
[source,terminal,subs="+quotes"]
41+
----
42+
$ oc describe gateway _<gateway_name>_ -n _<namespace>_
43+
----
44+
+
45+
* Replace `_<gateway_name>_` with the name of the `Gateway` object.
46+
* Replace `_<namespace>_` with the namespace where it is applied.
47+
* This command can help you figure out why a `Gateway` object is stuck in `Pending` by checking for port conflicts and verifying that `SSL/TLS` certificates are correctly attached to `Listener` CRs.
48+
49+
. Verify the `Listener` CR configuration by running the following command:
50+
+
51+
[source,terminal,subs="+quotes"]
52+
----
53+
$ oc get gateway _<gateway_name>_ -n _<namespace>_ -o yaml | grep -A 10 listeners
54+
----
55+
+
56+
* Replace `_<gateway_name>_` with the name of the `Gateway` object.
57+
* Replace `_<namespace>_` with the namespace where the `Gateway object` is applied.
58+
59+
. Check all of your `Listener` CR configurations at the same time by running the following command:
60+
+
61+
[source,terminal,subs="+quotes"]
62+
----
63+
$ oc get gateway _<gateway_name>_ -n _<namespace>_ -o jsonpath='{range .spec.listeners[*]}{.name}{"\t"}{.hostname}{"\t"}{.port}{"\n"}{end}' | jq
64+
----
65+
* Replace `_<gateway_name>_` with the name of the `Gateway` object.
66+
* Replace `_<namespace>_` with the namespace where your `Gateway` object is applied.
67+
* This command uses `jq` for formatting.
68+
69+
. Check that the Istio gateway pod is running by using the following command:
70+
+
71+
[source,terminal,subs="+quotes"]
72+
----
73+
$ oc get pods -n _<gateway_system>_ -l istio=ingressgateway
74+
----
75+
+
76+
* Replace `_<gateway_system>_` with the name of your `Gateway` object deployment.
77+
* This command checks the status of Envoy-proxy pods and returns pod, traffic flow, and policy errors.
78+
79+
. Verify that the port you are trying to use is not already in use by running the following command:
80+
+
81+
[source,terminal]
82+
----
83+
$ oc get gateway -A -o yaml | grep "port:"
84+
----

‎modules/proc-mcp-gateway-ts-pods-not-starting.adoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-troubleshooting.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-mcp-gateway-ts-pods-not-starting_{context}"]
7+
= MCP gateway pods not starting
8+
9+
[role="_abstract"]
10+
When your MCP gateway pods are stuck in one of several states that indicate that they are not starting as expected, you can take several steps to diagnose the problem.
11+
12+
Common causes include the following states and indicate an associated action:
13+
14+
* `ImagePullBackOff`: Check image repository access and credentials.
15+
* `CrashLoopBackOff`: Check the logs for application errors.
16+
* `Pending:` Check resource availability and node capacity.
17+
* `Init Container Failure*:` Check RBAC permissions.
18+
19+
.Prerequisites
20+
21+
* You installed {mcpg}.
22+
* You installed {prodname}.
23+
* You configured a `Gateway` object.
24+
* You configured an `HTTPRoute` object for the gateway.
25+
* You installed the {oc-first}.
26+
* You registered an MCP server.
27+
28+
.Procedure
29+
30+
. Check the pod status by running the following command:
31+
+
32+
[source,terminal,subs="+quotes"]
33+
----
34+
$ oc get pods -n _<mcp_system>_
35+
----
36+
+
37+
Replace `_<mcp_system>_` with the name of the MCP gateway deployment that you are checking.
38+
39+
. Describe problem pods by running the following command:
40+
+
41+
[source,terminal,subs="+quotes"]
42+
----
43+
$ oc describe pod -n _<mcp_system>_ _<pod_name>_
44+
----
45+
+
46+
Replace `_<mcp_system>_` with the name of the MCP gateway deployment that you are checking.
47+
Replace `_<pod_name>_` with the name of the pod that you are checking.
48+
49+
. Check the namespace logs by running the following command:
50+
+
51+
[source,terminal,subs="+quotes"]
52+
----
53+
$ oc logs -n _<mcp_system>_ _<pod_name>_
54+
----
55+
+
56+
Replace `_<mcp_system>_` with the name of the MCP gateway deployment that you are checking.
57+
Replace `_<pod_name>_` with the name of the pod that you are checking.

‎modules/proc-mcp-gateway-ts-traffic-not-reaching-backend-server.adoc‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-troubleshooting.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-mcp-gateway-ts-traffic-not-reaching-backend-server_{context}"]
7+
= Troubleshooting traffic not reaching the backend MCP server
8+
9+
[role="_abstract"]
10+
When you are certain that an `HTTPRoute` custom resource (CR) exists for your application, but traffic is not reaching your backend MCP servers, you can take several steps to troubleshoot the problem.
11+
12+
.Prerequisites
13+
14+
* You installed {mcpg}.
15+
* You installed {prodname}.
16+
* You configured a `Gateway` object.
17+
* You configured an `HTTPRoute` object for the gateway.
18+
* You installed the {oc-first}.
19+
* You registered an MCP server.
20+
21+
.Procedure
22+
23+
. Check the `HTTPRoute` general custom resource (CR) status by running the following command:
24+
----
25+
$ oc get httproute -A
26+
----
27+
+
28+
* This command returns general information about all `HTTPRoute` objects in the cluster.
29+
* Check for the `Accepted` condition in the `HTTPRoute` CR `status` fields.
30+
31+
. Check the full metadata and status history for one specific `HTTPRoute` object by running the following command:
32+
+
33+
[source,terminal,subs="+quotes"]
34+
----
35+
$ oc describe httproute _<route_name>_ -n _<namespace>_
36+
----
37+
+
38+
* Replace `_<route_name>_` with the name of the `HTTPRoute` object.
39+
* Replace `_<namespace>_` with the namespace where the `HTTPRoute` object is applied.
40+
* Verify that the `hostnames` value in the `HTTPRoute` CR matches the gateway `Listener` CR `hostname`.
41+
* If the `Gateway` object does not allow the namespace, the `HTTPRoute` status shows `Accepted: False`.
42+
43+
. Verify the parent reference by running the following command:
44+
+
45+
[source,terminal,subs="+quotes"]
46+
----
47+
$ oc get httproute _<route_name>_ -n _<namespace>_ -o yaml | grep -A 5 parentRefs
48+
----
49+
+
50+
* Replace `_<route_name>_` with the name of the `HTTPRoute` object.
51+
* Replace `_<namespace>_` with the namespace where the `HTTPRoute` object is applied.
52+
* Ensure that the retrieved `parentRefs` value matches your `Gateway` CR name and namespace exactly.
53+
54+
. Check that the `allowedRoutes.namespaces` value in the `Gateway` CR allows the `HTTPRoute` namespace by running the following command:
55+
+
56+
[source,terminal,subs="+quotes"]
57+
----
58+
$ oc get gateway _<gateway_name>_ -n _<gateway_namespace>_ -o jsonpath='{range .spec.listeners[*]}{.name}{": "}{.allowedRoutes.namespaces.from}{"\n"}{end}'
59+
----
60+
+
61+
* Replace `_<gateway_name>_` with the name of the `Gateway` object.
62+
* Replace `_<gateway_namespace>_` with the namespace where the `Gateway` object is applied.

‎observe_troubleshoot/mcp-gateway-troubleshooting.adoc‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,10 @@ include::_attributes/attributes.adoc[]
55
:context: mcp-gateway-troubleshooting
66

77
[role="_abstract"]
8-
FPO assembly
8+
You can troubleshoot common issues with solutions when working with the MCP gateway across installation, configuration, and operation.
9+
10+
include::modules/proc-mcp-gateway-ts-pods-not-starting.adoc[leveloffset=+1]
11+
12+
include::modules/proc-mcp-gateway-ts-gateway-listener-not-working.adoc[leveloffset=+1]
13+
14+
include::modules/proc-mcp-gateway-ts-traffic-not-reaching-backend-server.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)