Chapter 2. Troubleshoot isolated MCP gateway deployments

Procedure

1. Check the status of the MCPGatewayExtension CR by running the following command:

   $ oc get mcpgatewayextension -n <namespace> -o yaml

   Replace <namespace> with the namespace where the MCPGatewayExtension CR is applied.

2. Look for the following condition in the output:

   conditions:
     - type: Ready
       status: "False"
       reason: ReferenceGrantRequired
       message: "invalid: ReferenceGrant required in %s to allow cross-namespace reference from %s"

3. Create a ReferenceGrant CR in the Gateway object namespace:

   apiVersion: gateway.networking.k8s.io/v1beta1
   kind: ReferenceGrant
   metadata:
     name: <team_a_refgrant>
     namespace: <gateway_namespace>
   spec:
     from:
       - group: mcp.kuadrant.io
         kind: MCPGatewayExtension
         namespace: <team_namespace>
     to:
       - group: gateway.networking.k8s.io
         kind: Gateway
         name: <team_a_gateway>

   • Replace the metadata.name value with the name of your team.
   • Replace the metadata.namespace value with the namespace where the Gateway object is applied.
   • Replace the spec.from.namespace value with the namespace where the MCPGatewayExtension CR is applied.
   • Replace the spec.to.name value with the name of the team Gateway object.

4. Verify the MCPGatewayExtension CR is ready by running the following command:

   $ oc wait --for=condition=Ready mcpgatewayextension/<extension_name> -n <namespace> --timeout=60s

Procedure

1. Verify that the target Gateway object exists by running the following command:

   $ oc get gateway <gateway_name> -n <gateway_namespace>

   • Replace <gateway_name> with the name of the Gateway object.
   • Replace <gateway_namespace> with the namespace where the Gateway object is applied.

2. Check for conflicting MCPGatewayExtension CRs that target the same Gateway object by running the following command:

   $ oc get mcpgatewayextension -A

   Only one MCPGatewayExtension CR can target a given Gateway object. If multiple extensions target the same Gateway object, the controller marks newer ones as conflicted. The oldest extension by creation timestamp takes precedence.

3. If a conflict exists, update the newer MCPGatewayExtension CR to target a different Gateway object, or delete the conflicting extension.

Procedure

1. Check the status of the MCPServerRegistration CR by running the following command:

   $ oc get mcpserverregistration -n <namespace> -o yaml

   Replace <namespace> with the namespace where the MCPServerRegistration CR is applied.

2. Verify the following conditions:

   1. The HTTPRoute CR exists and references the correct Gateway object, and its status is accepted.
   2. An MCPGatewayExtension CR exists that targets the same Gateway object.

   3. The MCPGatewayExtension CR is in Ready state by running the following command:

      $ oc get mcpgatewayextension -n <namespace>

Procedure

1. Check the contents of the configuration Secret object by running the following command:

   $ oc get secret mcp-gateway-config -n <namespace> -o jsonpath='{.data.config\.yaml}' | base64 -d

   Replace <namespace> with the namespace where the MCPGatewayExtension CR is applied.

2. Verify that MCPServerRegistration CRs exist and are in Ready state by running the following command:

   $ oc get mcpserverregistration -n <namespace>

   If no MCPServerRegistration CRs exist or none are in Ready state, register MCP servers for this gateway instance.