Skip to content

Commit f08cbf8

Browse files
ShaunaDiazShaunaDiaz
committed
OSDOCS-18945: adds troubleshooting MCP gateway
1 parent 4249b3f commit f08cbf8

8 files changed

Lines changed: 407 additions & 1 deletion

‎modules/con-mcp-gateway-ts-gateway-routing.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-troubleshooting.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="con-mcp-gateway-ts-gateway-routing_{context}"]
7+
= Gateway and routing troubleshooting
8+
9+
[role="_abstract"]
10+
When traffic is not flowing after you installed {mcpg}, you can investigate each component of the gateway routing to check system health. Depending on the errors you are receiving, you can troubleshoot at several layers. Breaks can occur at the gateway, route, or policy levels.
11+
12+
If you have a `Connection Refused/Timeout` error and your client cannot reach the IP address, the cause might be the
13+
listener. In this case, one of the following situations likely applies:
14+
15+
* The port is not open.
16+
* The load balancer has not assigned an IP address.
17+
* The TLS handshake is failing.
18+
19+
When you have this type of error, check the listener first.
20+
21+
If you can connect to the `Gateway` object, but you get an `HTTP` error, such as `404`, the cause can be a problem with the `HTTPRoute` custom resource (CR). The route exists, but the `Gateway` object has rejected it or the connection has failed. When you get these types of codes, check the `HTTPRoute` CR first.
22+
23+
If requests either fail with a `503` error or bypass the router, this means that the route is recognized, but the connection to the backend failed or was not authorized properly. In this case, start with API-level checks and narrow your investigation to Envoy filters as needed.
24+
25+
If the `EnvoyFilter` CR is not present, it usually means one of the following situations has occurred:
26+
27+
* The `Gateway` CR status is not `Programmed`.
28+
* There is a `labels` mismatch, and the `EnvoyFilter` CR is not injected into the pods.
29+
* The MCP controller component is crashing or stuck.

‎modules/proc-mcp-gateway-register-mcp-server.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,11 @@ spec:
9393
* Replace the `spec.targetRef.namespace:` field value with the namespace where your `HTTPRoute` CR is applied. In this example, `_<mcp_test>_` is used.
9494
* Replace the `credentialRef.name:` field value with the name of your `Secret` CR. In this example, `_<mcp_server_one_secret>_` is used. You can omit this parameter if your MCP server does not require authentication or authorization.
9595
* For more information about these parameters, see "Understanding the `MCPServerRegistration` custom resource."
96+
+
97+
[IMPORTANT]
98+
====
99+
A `toolPrefix` value can only contain alphanumeric characters, hyphens (-), and underscores (_).
100+
====
96101
97102
. Apply the CR by running the following command:
98103
+

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

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
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_{context}"]
8+
= Troubleshooting the gateway listener
9+
10+
[role="_abstract"]
11+
If your {mcpg} cannot reach an MCP endpoint at the configured hostname, the `Listener` custom resource (CR) you configured might not be working. You can troubleshoot this situation by using a few commands and some insight.
12+
13+
Use the following concepts 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` parameter value in the `Listener` CR matches your DNS or hosts configuration.
17+
18+
.Prerequisites
19+
20+
* You installed {mcpg}.
21+
* You installed the {oc-first}.
22+
* You configured a `Gateway` object.
23+
* You configured an `HTTPRoute` object for the gateway.
24+
25+
.Procedure
26+
27+
. Check the general `Gateway` object configuration by running the following command:
28+
+
29+
[source,terminal]
30+
----
31+
$ oc get gateway -A
32+
----
33+
+
34+
This command returns general information about all `Gateway` objects in the cluster. If the `Gateway` object you are troubleshooting exists, the command returns the following information:
35+
+
36+
* The `gatewayClassName` is it using, whether or not it has an IP address or hostname assigned
37+
* The `status`, such as `Ready`, `Programmed`, or `Pending`
38+
39+
. Check the full metadata and status history for one specific `Gateway` object by running the following command:
40+
+
41+
[source,terminal,subs="+quotes"]
42+
----
43+
$ oc describe gateway _<gateway_system>_ -n _<namespace>_
44+
----
45+
+
46+
* Replace `_<gateway_system>_` with the name of the `Gateway` object.
47+
* Replace `_<namespace>_` with the namespace where the `Gateway` object is applied.
48+
* 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.
49+
50+
. Verify the `Listener` CR configuration by running the following command:
51+
+
52+
[source,terminal,subs="+quotes"]
53+
----
54+
$ oc get gateway _<gateway_name>_ -n _<gateway_system>_ -o yaml | grep -A 10 listeners
55+
----
56+
+
57+
* Replace `_<gateway_name>_` with the name of the `Gateway` object.
58+
* Replace `_<gateway_system>_` with the namespace where the `Gateway` object is applied.
59+
60+
. Check all of your `Listener` CR configurations at the same time by running the following command:
61+
+
62+
[source,terminal,subs="+quotes"]
63+
----
64+
$ oc get gateway _<gateway_name>_ -n _<gateway_system>_ -o jsonpath='{range .spec.listeners[*]}{.name}{"\t"}{.hostname}{"\t"}{.port}{"\n"}{end}'
65+
----
66+
+
67+
* Replace `_<gateway_name>_` with the name of the `Gateway` object.
68+
* Replace `_<gateway_system>_` with the namespace where the `Gateway` object is applied.
69+
70+
. Check that the Istio gateway pod is running by using the following command:
71+
+
72+
[source,terminal,subs="+quotes"]
73+
----
74+
$ oc get pods -n _<gateway_system>_ -l gateway.istio.io/managed=istio.io-gateway-controller
75+
----
76+
+
77+
* Replace `_<gateway_system>_` with the name of your `Gateway` object deployment.
78+
* This command checks the status of Envoy-proxy pods and returns pod, traffic flow, and policy errors.
79+
80+
. Verify that the port you are trying to use is not already in use by running the following command:
81+
+
82+
[source,terminal]
83+
----
84+
$ oc get gateway -A -o yaml | grep "port:"
85+
----

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
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+
= {mcpg} pods not starting
8+
9+
[role="_abstract"]
10+
After installation, if your {mcpg} 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 the {oc-first}.
23+
* You configured a `Gateway` object.
24+
* You configured an `HTTPRoute` object for the gateway.
25+
26+
.Procedure
27+
28+
. Check the pod status by running the following command:
29+
+
30+
[source,terminal,subs="+quotes"]
31+
----
32+
$ oc get pods -n _<mcp_system>_
33+
----
34+
+
35+
Replace `_<mcp_system>_` with the name of the {mcpg} deployment that you are checking.
36+
37+
. Describe problem pods by running the following command:
38+
+
39+
[source,terminal,subs="+quotes"]
40+
----
41+
$ oc describe pod -n _<mcp_system>_ _<pod_name>_
42+
----
43+
+
44+
* Replace `_<mcp_system>_` with the name of the {mcpg} deployment that you are checking.
45+
* Replace `_<pod_name>_` with the name of the pod that you are checking.
46+
47+
. Check the pod logs by running the following command:
48+
+
49+
[source,terminal,subs="+quotes"]
50+
----
51+
$ oc logs -n _<mcp_system>_ _<pod_name>_
52+
----
53+
+
54+
* Replace `_<mcp_system>_` with the name of the {mcpg} deployment that you are checking.
55+
* Replace `_<pod_name>_` with the name of the pod that you are checking.

‎modules/proc-mcp-gateway-ts-requests-fail-or-bypass-router.adoc‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
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-requests-fail-or-bypass-router_{context}"]
7+
= Troubleshooting requests failing or bypassing the router
8+
9+
[role="_abstract"]
10+
When you are certain that an `MCPGatewayExtension` custom resource (CR) exists for your MCP server, but requests either fail or bypass the router, it might mean that the `EnvoyFilter` CR is not applied properly. You can take several steps to troubleshoot the problem.
11+
12+
The `EnvoyFilter` CR is automatically created in the `Gateway` CR namespace by the MCP gateway controller component when an `MCPGatewayExtension` CR is `Ready`.
13+
14+
[IMPORTANT]
15+
====
16+
You can look closely at the `EnvoyFilter` CR during deep troubleshooting, but do not manually edit or delete the CR.
17+
====
18+
19+
.Prerequisites
20+
21+
* You installed {mcpg}.
22+
* You installed the {oc-first}.
23+
* You configured a `Gateway` object.
24+
* You configured an `HTTPRoute` object for the gateway.
25+
* You registered an MCP server.
26+
27+
.Procedure
28+
29+
. Ensure that the `Gateway` object exists and is in the expected namespace by checking 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 exists, 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+
. Verify that the `MCPGatewayExtension` CR is `Ready` by running the following command:
39+
+
40+
[source,terminal]
41+
----
42+
$ oc get mcpgatewayextension -A
43+
----
44+
45+
. Verify that a `ReferenceGrant` CR exists if the `MCPGatewayExtension` CR is in a different namespace than the `Gateway` object by running the following command:
46+
+
47+
[source,terminal,subs="+quotes"]
48+
----
49+
$ oc get referencegrant _<referencegrant_name>_ -n _<gateway_system>_ -o yaml
50+
----
51+
+
52+
* Replace `_<referencegrant_name>_` with the names of the `ReferenceGrant` CR.
53+
* Replace `_<gateway_system>_` with the namespace where the `Gateway` object is applied.
54+
55+
. Check the `HTTPRoute` CR by running the following command:
56+
+
57+
[source,terminal,subs="+quotes"]
58+
----
59+
$ oc describe httproute _<httproute_name>_ -n _<httproute_namespace>_
60+
----
61+
+
62+
* Replace `_<httproute_namespace>_` with the namespace where the `HTTPRoute` CR is applied.
63+
* Replace `_<httproute_name>_` with the names of the `HTTPRoute` CR.
64+
* If the `HTTPRoute` CR is not `Accepted` by the `Gateway` object, the route is not programmed into Envoy, causing a `404`.
65+
* The conditions `Status.Parents.Conditions: Accepted: True` and `Programmed: True` show that the route is correct.
66+
67+
. If any of the CRs you just checked are not `Ready`, check the controller logs for `EnvoyFilter` creation errors by running the following command:
68+
+
69+
[source,terminal,subs="+quotes"]
70+
----
71+
$ oc logs -n _<mcp_system>_ deployment/mcp-gateway-controller
72+
----
73+
+
74+
* Replace `_<mcp_system>_` with the name of your MCP gateway deployment.
75+
* This step verifies that the MCP controller is successfully generating the underlying Istio configurations.
76+
77+
. Check that the `EnvoyFilter` exists in the `Gateway` namespace by running the following command:
78+
+
79+
[source,terminal,subs="+quotes"]
80+
----
81+
$ oc get envoyfilter -n _<gateway_namespace>_ -l app.kubernetes.io/managed-by=mcp-gateway-controller
82+
----
83+
+
84+
* Replace `_<gateway_namespace>_` with the namespace where the `Gateway` object is applied.
85+
86+
. Verify the `EnvoyFilter` configuration by running the following command:
87+
+
88+
[source,terminal,subs="+quotes"]
89+
----
90+
$ oc describe envoyfilter -n _<gateway_namespace>_ -l app.kubernetes.io/managed-by=mcp-gateway-controller
91+
----
92+
+
93+
* Replace `_<gateway_namespace>_` with the namespace where the `Gateway` object is applied.
94+
* The `workloadSelector` labels must match your `Gateway` pods, or your policies are bypassed.
95+
96+
. Compare the `EnvoyFilter` labels against your pod labels by running the following command:
97+
+
98+
[source,terminal,subs="+quotes"]
99+
----
100+
$ oc get pods -n _<gateway_namespace>_ --show-labels
101+
----
102+
+
103+
* Replace `_<gateway_namespace>_` with the namespace where the `Gateway` object is applied.
104+
105+
. Identify the port that the `Gateway` object is configured to use by running the following command:
106+
+
107+
[source,terminal,subs="+quotes"]
108+
----
109+
$ oc get gateway _<gateway_name>_ -n _<gateway_namespace>_ -o jsonpath='{range .spec.listeners[*]}{.name}{": "}{.port}{"\n"}{end}'
110+
----
111+
+
112+
* Replace `_<gateway_name>_` with the name of the `Gateway` object.
113+
* Replace `_<gateway_namespace>_` with the namespace where the `Gateway` object is applied.
114+
115+
. Verify the `EnvoyFilter` chain binding by running the following command:
116+
+
117+
[source,terminal,subs="+quotes"]
118+
----
119+
$ oc exec -n _<gateway_namespace>_ deploy/_<gateway_name>_-istio -- curl -s localhost:15000/config_dump | jq '.configs[] | select(.["@type"] | contains("ListenersConfigDump")) | .dynamic_listeners[0.0.0.0_8080] | select(.name | contains("_<gateway_port>_"))'
120+
----
121+
+
122+
* Replace `_<gateway_name>_` with the name of the `Gateway` object.
123+
* Replace `_<gateway_namespace>_` with the namespace where the `Gateway` object is applied.
124+
* Replace `_<gateway_port>_` with the port your Gateway object is configured to use.
125+
* Check for `envoy.filters.http.ext_proc`.
126+
127+
. Check the Istio gateway pod configuration by running the following command:
128+
+
129+
[source,terminal,subs="+quotes"]
130+
----
131+
$ oc exec -n _<gateway_namespace>_ deploy/_<gateway_name>_-istio -- curl localhost:15000/config_dump | grep ext_proc
132+
----
133+
+
134+
* Replace `_<gateway_namespace>_` with the namespace where the `Gateway` object is applied.
135+
* Replace `_<gateway_name>_` with the names of the `Gateway` object.
136+
* If this command returns empty, the `EnvoyFilter` CR is not active on this pod. Traffic is bypassing your policies.
137+
138+
. Restart the Istio gateway to force a configuration reload by running the following command:
139+
+
140+
[source,terminal,subs="+quotes"]
141+
----
142+
$ oc rollout restart deployment/_<gateway_name>_-istio -n _<gateway_namespace>_
143+
----
144+
* Replace `_<gateway_namespace>_` with the namespace where the `Gateway` object is applied.
145+
* Replace `_<gateway_name>_` with the names of the `Gateway` object.

0 commit comments

Comments
 (0)