From 49c74d9dbb8be08c66f17ecd4b30ec741c0b2f3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Tue, 31 Mar 2026 13:50:00 -0400 Subject: [PATCH] OSDOCS-17693: adds install to MCP gateway docs --- _topic_maps/_topic_map.yml | 2 - .../mcp-gateway-get-started.adoc | 8 - mcp_gateway_install/mcp-gateway-install.adoc | 28 ++- modules/con-mcp-gateway-dns-management.adoc | 16 ++ .../con-mcp-gateway-install-olm-ext-cr.adoc | 33 ++++ modules/proc-config-mcp-gateway-gateway.adoc | 88 +++++++++ modules/proc-config-mcp-gateway-listener.adoc | 181 ++++++++++++++++++ modules/proc-mcp-gateway-config-verify.adoc | 33 ++++ modules/proc-mcp-gateway-custom-route.adoc | 113 +++++++++++ .../proc-mcp-gateway-install-olm-ext-cr.adoc | 113 +++++++++++ modules/proc-mcp-gateway-install-olm.adoc | 90 +++++++++ modules/proc-mcp-gateway-referencegrant.adoc | 51 +++++ modules/ref-mcp-gateway-auto-route.adoc | 39 ++++ 13 files changed, 783 insertions(+), 12 deletions(-) delete mode 100644 mcp_gateway_install/mcp-gateway-get-started.adoc create mode 100644 modules/con-mcp-gateway-dns-management.adoc create mode 100644 modules/con-mcp-gateway-install-olm-ext-cr.adoc create mode 100644 modules/proc-config-mcp-gateway-gateway.adoc create mode 100644 modules/proc-config-mcp-gateway-listener.adoc create mode 100644 modules/proc-mcp-gateway-config-verify.adoc create mode 100644 modules/proc-mcp-gateway-custom-route.adoc create mode 100644 modules/proc-mcp-gateway-install-olm-ext-cr.adoc create mode 100644 modules/proc-mcp-gateway-install-olm.adoc create mode 100644 modules/proc-mcp-gateway-referencegrant.adoc create mode 100644 modules/ref-mcp-gateway-auto-route.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index b7e2e1346f7e..4a0afc181df1 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -55,8 +55,6 @@ Name: Installing the MCP gateway Dir: mcp_gateway_install Distros: rhcl Topics: -- Name: Getting started with the MCP gateway - File: mcp-gateway-get-started - Name: Installing MCP gateway File: mcp-gateway-install --- diff --git a/mcp_gateway_install/mcp-gateway-get-started.adoc b/mcp_gateway_install/mcp-gateway-get-started.adoc deleted file mode 100644 index dadfa00195ea..000000000000 --- a/mcp_gateway_install/mcp-gateway-get-started.adoc +++ /dev/null @@ -1,8 +0,0 @@ -:_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes.adoc[] -[id="mcp-gateway-get-started"] -= Getting started with {mcpg} -:context: mcp-gateway-get-started - -[role="_abstract"] -FPO assembly diff --git a/mcp_gateway_install/mcp-gateway-install.adoc b/mcp_gateway_install/mcp-gateway-install.adoc index 5ea3bc9ab464..f17254312f0e 100644 --- a/mcp_gateway_install/mcp-gateway-install.adoc +++ b/mcp_gateway_install/mcp-gateway-install.adoc @@ -1,8 +1,32 @@ :_mod-docs-content-type: ASSEMBLY include::_attributes/attributes.adoc[] [id="mcp-gateway-install"] -= Installing {mcpg} += Installing and configuring {mcpg} :context: mcp-gateway-get-install [role="_abstract"] -FPO assembly +You can get started with the MCP gateway by installing the Operator by using Operator Lifecycle Manager (OLM), and then continuing to set up connections by applying the custom resources that you require. + +:FeatureName: {mcpg} + +include::snippets/technology-preview.adoc[leveloffset=+1] + +include::modules/proc-mcp-gateway-install-olm.adoc[leveloffset=+1] + +include::modules/proc-config-mcp-gateway-gateway.adoc[leveloffset=+1] + +include::modules/proc-config-mcp-gateway-listener.adoc[leveloffset=+1] + +include::modules/con-mcp-gateway-install-olm-ext-cr.adoc[leveloffset=+1] + +include::modules/ref-mcp-gateway-auto-route.adoc[leveloffset=+2] + +include::modules/proc-mcp-gateway-referencegrant.adoc[leveloffset=+1] + +include::modules/proc-mcp-gateway-install-olm-ext-cr.adoc[leveloffset=+1] + +include::modules/con-mcp-gateway-dns-management.adoc[leveloffset=+1] + +include::modules/proc-mcp-gateway-custom-route.adoc[leveloffset=+1] + +include::modules/proc-mcp-gateway-config-verify.adoc[leveloffset=+1] diff --git a/modules/con-mcp-gateway-dns-management.adoc b/modules/con-mcp-gateway-dns-management.adoc new file mode 100644 index 000000000000..a1178ced6000 --- /dev/null +++ b/modules/con-mcp-gateway-dns-management.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-dns-management-mcp-gateway_{context}"] += DNS management with the MCP gateway + +[role="_abstract"] +You can use a variety of options to enable the resolution of `hostnames` associated within your `Gateway` object listeners, depending on the operating environment and targeted hostname. + +For example, if the `hostname` is within the DNS zone defined by a `dns.config.openshift.io/cluster` resource, you can use the OpenShift Cluster Ingress Operator to register the IP address of the `Gateway` object in the associated cloud DNS provider. You must create the `Gateway` object in the namespace where the `IngressController` object is applied. + +In environments where {ocp} is not connected to a cloud provider, you must take additional steps to manage how the `Gateway` object is exposed outside the cluster and how traffic is resolved. You can use MetalLB to advertise IP addresses associated with the `Gateway` object. You can then either perform DNS registration manually, or use automation, such as the ExternalDNS Operator. + +When `Gateway` and `MCPGatewayExtension` objects are applied in different namespaces, such as `openshift-ingress` and `mcp-system`, you must create a `ReferenceGrant` custom resource for cross-namespace communication. diff --git a/modules/con-mcp-gateway-install-olm-ext-cr.adoc b/modules/con-mcp-gateway-install-olm-ext-cr.adoc new file mode 100644 index 000000000000..1e113b2707eb --- /dev/null +++ b/modules/con-mcp-gateway-install-olm-ext-cr.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-mcp-gateway-install-olm-ext-cr_{context}"] += Understanding the MCPGatewayExtension custom resource + +[role="_abstract"] +You can deploy multiple MCP gateway instances within a single cluster by using more than one `Gateway` object, and an `MCPGatewayExtension` custom resource (CR) for each defined gateway. Each deployment of the MCP gateway manages its associated MCP servers by using the `MCPGatewayExtension` controller in the following ways: + +* Defines which `Gateway` object the MCP gateway instance is responsible for. +* Determines where configuration `Secret` objects are created. +* Enables isolation by allowing multiple MCP gateway instances in different namespaces to target different `Gateway` objects. + +[IMPORTANT] +==== +Each namespace can only have one `MCPGatewayExtension` CR. +Each `Gateway` object can have only one `MCPGatewayExtension` CR. If more than one `MCPGatewayExtension` CR targets the same `Gateway` object, the controller marks newer ones as conflicted. The oldest `MCPGatewayExtension` CR wins. +==== + +Automatic route creation:: + +The `MCPGatewayExtension` controller automatically creates an `HTTPRoute` CR named `mcp-gateway-route`. The automatically created `HTTPRoute` CR has the following characteristics: + +* Routes `/mcp` traffic to the `mcp-gateway` broker service on port `8080` +* Uses the `hostname` from the `Gateway` listener. Wildcards such as `*.example.com` become `mcp.example.com` +* References the target gateway with the correct `sectionName` +* Is owned by the `MCPGatewayExtension` controller and is cleaned up automatically if the controller is deleted + +Custom route creation:: + +If you require custom route, you can disable automatic `HTTPRoute` CR creation by setting the `spec.httpRouteManagement:` parameter to `Disabled` in your `MCPGatewayExtension` CR. After you create the `MCPGatewayExtension` CR, you can create a custom `HTTPRoute` CR. diff --git a/modules/proc-config-mcp-gateway-gateway.adoc b/modules/proc-config-mcp-gateway-gateway.adoc new file mode 100644 index 000000000000..da8e771d429b --- /dev/null +++ b/modules/proc-config-mcp-gateway-gateway.adoc @@ -0,0 +1,88 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-config-mcp-gateway-gateway_{context}"] += Creating a Gateway object for your MCP gateway + +[role="_abstract"] +You must create a `Gateway` object and configure listeners to create pods to handle your traffic, assign IP addresses, and give HTTP routes a place to connect. + +[TIP] +==== +You can attach your {prodnamefull} `DNSPolicy` CR to your `Gateway` object to automatically map your hostnames to your Gateway object's IP address. Point your `DNSPolicy` CR to your Gateway object by `name` in the `targetRef:` section. The `DNSPolicy` CR must reside in the same namespace as the `Gateway` object. +==== + +.Prerequisites + +* You installed {ocp}. +* You installed {oc-first}. +* You installed the {mcpg} Operator. + +.Procedure + +* Create a `Gateway` object by using the following example as a template: ++ +.Example Gateway CR with listeners +[source,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: mcp-gateway + namespace: gateway-namespace +spec: + gatewayClassName: openshift-default + listeners: + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: All + - name: mcp + hostname: mcp.example.com + port: 8080 + protocol: HTTP + allowedRoutes: + namespaces: + from: All + - name: https + hostname: mcp.apps.openshift.example.com + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: All + tls: + certificateRefs: + - group: '' + kind: Secret + name: default-ingress-cert + mode: Terminate +---- ++ +* The custom resource (CR) is a `Gateway` named `mcp-gateway` that exists in the `gateway-namespace` namespace and has three listeners configured. +* On {ocp}, the `spec.listeners.tls.certificateRefs:` value can specify the `Secret` CR containing the default wildcard certificate for the OpenShift Ingress controller. ++ +[IMPORTANT] +==== +You must use the `spec.listeners[].name` value in the corresponding `MCPGatewayExtension` CR `spec.targetRef.sectionName:` field. +==== + +. Optional. Verify the {prodname} `DNSPolicy` CR attachment by checking its status with the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get dnspolicy __ -n __ -o wide +---- ++ +* Replace `__` with the name of your {prodname} `DNSPolicy` CR. +* Replace `__` with the `Gateway` object namespace. ++ +.Example output +[source,text] +---- +ACCEPTED: True +---- diff --git a/modules/proc-config-mcp-gateway-listener.adoc b/modules/proc-config-mcp-gateway-listener.adoc new file mode 100644 index 000000000000..7f08d9427c6b --- /dev/null +++ b/modules/proc-config-mcp-gateway-listener.adoc @@ -0,0 +1,181 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-config-mcp-gateway-listener_{context}"] += Configuring MCP gateway listeners + +[role="_abstract"] +Connect your MCP gateway to your agentic AI systems by appending your `Gateway` custom resource (CR) with your MCP listener information. The MCP listener handles the transport protocol, opens an MCP session on the port, and establishes a security perimeter. You can also add listeners for unencrypted web traffic and secured traffic. + +.Prerequisites + +* You are logged in to your {ocp} cluster. +* You created a gateway custom resource (CR). +* You installed {mcpg}. +* You configured a gateway API provider. +* Optional. If you are adding a secure listener, you have a TLS certificate to reference. The certificate must be in the same namespace as the `Gateway` CR. + +.Procedure + +. Add an MCP gateway listener to your `Gateway` CR by appending it with the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ $ oc patch gateway __ -n __ --type='json' -p='[ + { + "op": "add", + "path": "/spec/listeners/-", + "value": { + "name": "mcp", + "hostname": "__", + "port": 8080, + "protocol": "HTTP", + "allowedRoutes": { + "namespaces": { + "from": "All" + } + } + } + } +]' +---- ++ +* Replace `__` with the name of your MCP gateway. +* Replace `__` with the namespace where your `Gateway` object is applied. +* Replace `__` with the hostname you want to use. + +. Verify that your listener is working by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get gateway __ -n __ -o yaml +---- ++ +* Replace `__` with the name of your MCP gateway deployment. +* Replace `__` with the namespace where your `Gateway` object is applied. +* The conditions `Accepted: True` and `Programmed: True` are expected in the `status` of the output. + +. Add a standard web traffic listener to your `Gateway` CR by appending it with the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc patch gateway __ -n __ --type='json' -p='[ + { + "op": "add", + "path": "/spec/listeners/-", + "value": { + "name": "http-web", + "port": 80, + "protocol": "HTTP", + "allowedRoutes": { + "namespaces": { + "from": "All" + } + } + } + } +]' +---- ++ +* Replace `__` with the name of your MCP gateway. +* Replace `__` with the namespace where your `Gateway` object is applied. +* The `listener.name` value must be a unique name within the `Gateway` object. In this example, `http-web` is used. +* The `listener.port: 80,` is the standard port for unencrypted web traffic. +* You can add a `hostname` if you want to limit incoming domain names. + +. Add a secure listener to your `Gateway` CR by appending it with the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc patch gateway __ -n __ --type='json' -p='[ + { + "op": "add", + "path": "/spec/listeners/-", + "value": { + "name": "https", + "hostname": "__", + "port": 443, + "protocol": "HTTPS", + "tls": { + "mode": "Terminate", + "certificateRefs": [ + { + "name": "mcp-tls-secret", + "kind": "Secret" + } + ] + }, + "allowedRoutes": { + "namespaces": { + "from": "All" + } + } + } + } +]' +---- ++ +* Replace `__` with the name of your MCP gateway deployment. +* Replace `__` with the namespace where your `Gateway` object is applied. +* Replace `__` with the hostname you are targeting. +* The `spec.listeners.tls.certificateRefs.name:` parameter specifies the name of your secret. This example uses `mcp-tls-secret`. +* The `spec.listeners.tls.mode: Terminate` value means that the gateway decrypts the traffic and sends it as plain text to your MCP server. You can specify the mode that you require. +* You must set a `spec.listeners.hostname` so that the relevant certificate is presented to the correct client. + +. Check that your certificates are properly linked by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get gateway __ -n __ -o jsonpath='{.status.listeners[?(@.name=="https")]}' +---- ++ +* Replace `__` with the name of your MCP gateway deployment. +* Replace `__` with the namespace where your `Gateway` object is applied. +* The `status` message outputs any errors. + +.Verification + +. Check the status your listeners and related objects by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc describe gateway __ -n __ +---- ++ +* Replace `__` with the name of your MCP gateway deployment. +* Replace `__` with the namespace where your `Gateway` object is applied. ++ +.Example output +[source,yaml] +---- +# ... +Status: + Listeners: + - Name: http-web + Supported Kinds: + Group: gateway.networking.k8s.io + Kind: HTTPRoute + Conditions: + Last Transition Time: 2026-04-01T... + Message: None + Reason: Programmed + Status: True + Type: Programmed + - Name: https + Conditions: + Reason: ResolvedRefs + Status: True + Type: ResolvedRefs +# ... +Events: + Type Reason Age From Message + Normal Synced 12m gateway-api-controller Successfully synced Gateway configuration + Normal IPAllocated 11m mcp-operator Assigned IP 192.168.1.100 to Gateway + Normal ListenerAccepted 10m gateway-api-controller Listener "http-web" accepted + Normal Programmed 10m gateway-api-controller Gateway has been successfully programmed +# ... +---- ++ +* The `Events` section of the output can also show port conflicts, problems with your `gatewayClassName:` value, missing routes, and a lack of permissions to read secrets. diff --git a/modules/proc-mcp-gateway-config-verify.adoc b/modules/proc-mcp-gateway-config-verify.adoc new file mode 100644 index 000000000000..1fc390d879b1 --- /dev/null +++ b/modules/proc-mcp-gateway-config-verify.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-mcp-gateway-config-verify_{context}"] += Verifying that an MCP endpoint is accessible through your MCP gateway + +[role="_abstract"] +You can verify that your MCP gateway is reaching your MCP endpoint by running a curl command to check for communication. + +.Prerequisites + +* You completed all of the installation steps. + +.Procedure + +* Verify that the MCP endpoint is accessible through your MCP gateway instance by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -X POST http://__ \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' +---- ++ +Replace `__` with your `__`. ++ +.Example output +[source,text] +---- +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"Kuadrant MCP Gateway","version":"0.6.0"}}} +---- diff --git a/modules/proc-mcp-gateway-custom-route.adoc b/modules/proc-mcp-gateway-custom-route.adoc new file mode 100644 index 000000000000..094eecd67add --- /dev/null +++ b/modules/proc-mcp-gateway-custom-route.adoc @@ -0,0 +1,113 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-mcp-gateway-custom-route_{context}"] += Applying a customized HTTPRoute object + +[role="_abstract"] +In many production environments, you are likely to require a custom `HTTPRoute` object for your MCP gateway. For example, if any of the following situations apply, use a custom HTTP route: + +* An identity provider protects your MCP gateway. +* You have a web-based AI chat interface that requires cross-origin resource sharing (CORS) headers so that one domain can talk to the other. +* You need additional path rules for things such as version switching, health check services, and tool dashboards. + +.Prerequisites + +* You installed {ocp}. +* You installed {oc-first}. +* You installed the {mcpg} Operator. +* You configured at least one listener. +* You created a `MCPGatewayExtension` CR. + +.Procedure + +. If you have not already done so, disable automatic route creation on your corresponding `MCPGatewayExtension` object by running the following command: ++ +[source,terminal] +---- +$ oc patch mcpgatewayextension -n __ __ \ + --type merge -p '{"spec":{"httpRouteManagement":"Disabled"}}' +---- ++ +Replace `__` with the name of your {mcpg} deployment. +Replace `__` with the name of your `MCPGatewayExtension` CR. + +. Create your customized `HTTPRoute` CR by using the following template: ++ +.Example customized HTTPRoute CR +[source,yaml,subs="+quotes"] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: __ + namespace: __ +spec: + parentRefs: + - name: __ + namespace: __ + sectionName: __ + hostnames: + - _<'mcp.example.com'>_ + rules: + - matches: + - path: + type: PathPrefix + value: /mcp + filters: + - type: ResponseHeaderModifier + responseHeaderModifier: + add: + - name: Access-Control-Allow-Origin + value: "*" + - name: Access-Control-Allow-Methods + value: "GET, POST, PUT, DELETE, OPTIONS, HEAD" + - name: Access-Control-Allow-Headers + value: "Content-Type, Authorization, Accept, Origin, X-Requested-With" + - name: Access-Control-Max-Age + value: "3600" + - name: Access-Control-Allow-Credentials + value: "true" + backendRefs: + - name: __ + port: 8080 + - matches: + - path: + type: PathPrefix + value: __ + backendRefs: + - name: __ + port: 8080 +---- ++ +* Replace the `metadata.name:` value with the name that you want to use. +* Replace the `metadata.namespace:` value with the namespace that you want to use. +* Replace the `spec.targetRef.sectionName:` parameter value with the MCP `Gateway` object listener. +* Replace the `spec.parentRefs.name:` value the name that you want to use. +* Replace `spec.parentRefs.namespace:` value with the namespace that you want to use. +* Replace the `spec.hostnames:` value or list with the values you want to use. +* Replace the `spec.rules.matches.path.value:` value with the URL path where you want to have your `Gateway` object available. +* Replace the `spec.rules.backend.Refs.name:` value with the name of your MCP gateway deployment. + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with the name that you used for your `HTTPRoute` CR. + +. Delete automatically created `HTTPRoute` CRs by running the following command: ++ +[source,terminal] +---- +$ oc delete httproute mcp-gateway-route -n mcp-system --ignore-not-found +---- ++ +[IMPORTANT] +==== +If you do not delete existing `HTTPRoute` CRs, the Gateway API chooses one based on a `spec`-defined precedence chain used when multiple `HTTPRoute` CRs match the same request. +==== diff --git a/modules/proc-mcp-gateway-install-olm-ext-cr.adoc b/modules/proc-mcp-gateway-install-olm-ext-cr.adoc new file mode 100644 index 000000000000..9aae1030af78 --- /dev/null +++ b/modules/proc-mcp-gateway-install-olm-ext-cr.adoc @@ -0,0 +1,113 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-mcp-gateway-install-olm-ext-cr_{context}"] += Applying the MCPGatewayExtension custom resource + +[role="_abstract"] +To finish your installation of the MCP gateway deployment Operator by using Operator Lifecycle Manager (OLM), create a `MCPGatewayExtension` custom resources (CR) manually and apply it to complete your initial setup. After the extension is ready, both an `HTTPRoute` object and an Envoy filter are automatically created. + +[IMPORTANT] +==== +Each namespace can only have one `MCPGatewayExtension` CR. +Each `Gateway` object can have only one `MCPGatewayExtension` CR. +==== + +.Prerequisites + +* You installed {ocp}. +* You installed {oc-first}. +* You installed the {mcpg} Operator. +* You configured at least one listener. +* If you are creating your `MCPGatewayExtension` CR in a different namespace than your `Gateway` object, you have created a `ReferenceGrant` CR. + +.Procedure + +. Create an `MCPGatewayExtension` CR by using the following example as a template: ++ +.Example MCPGatewayExtension CR +[source,yaml,subs="+quotes"] +---- +apiVersion: mcp.kuadrant.io/v1alpha1 +kind: MCPGatewayExtension +metadata: + name: __ + namespace: __ +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: __ + namespace: __ + sectionName: mcp + httpRouteManagement: Enabled +---- +* Replace the `metadata.name:` parameter value with the name you want to use. +* Replace the `metadata.namespace:` parameter value with the namespace you want to use. +* The `spec.targetRef.sectionName:` parameter value must be the same as name of the listener on the gateway. In this example, `mcp` is used. +* The `spec.targetRef.namespace:` value must be the namespace of the `Gateway` object where you created your listener. In this example, `__` is used. +* The value of the `sectionName:` parameter must match the listener `name:` value defined on your `Gateway` object in the `__` namespace. In this example, `mcp` is used. +* The default setting of `spec.httpRouteManagement: Enabled` means automatically maintained `HTTPRoute` objects to ensure that traffic for discovered MCP tools is correctly routed through the `Gateway` object. +* If you require a customized `HTTPRoute` CR, set the `spec.httpRouteManagement:` field value to `Disabled`. ++ +[IMPORTANT] +==== +In the MCP gateway Technology Preview version, `0.6.0`, you must set the `spec.httpRouteManagement:` field value to `Disabled` and create a customized managed `HTTPRoute` CR if you are using OAuth. This is a workaround for a Known Issue. See the {prodname} 1.3.3 release notes for details. +==== +//re: https://github.com/Kuadrant/mcp-gateway/issues/776 + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with name you used. + +. Wait for the `MCPGatewayExtension` controller to be ready by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc wait --for=condition=Ready mcpgatewayextension/__ -n __ +---- ++ +* Replace `__` with name you used. +* Replace `__` with name of your MCP gateway deployment. ++ +.Example successful output +[source,text] +---- +mcpgatewayextension.mcp.kuadrant.io/mcp-gateway-one condition met +---- ++ +.Example failure output +[source,text] +---- +error: timed out waiting for the condition on mcpgatewayextensions/mcp-gateway-one +---- + +. Verify that the automatic `HTTProute` object is created by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get httproute mcp-gateway-route -n mcp-system +---- ++ +.Example output +[source,text] +---- +NAME HOSTNAMES AGE +mcp-gateway-route ["mcp.example.com"] 5m +---- + +. Verify that the Envoy filter exists in the same namespace as the `Gateway` object by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get envoyfilter -n __ -l app.kubernetes.io/managed-by=mcp-gateway-controller +---- ++ +Replace `__` with the name of your `Gateway` CR namespace. diff --git a/modules/proc-mcp-gateway-install-olm.adoc b/modules/proc-mcp-gateway-install-olm.adoc new file mode 100644 index 000000000000..6107f8654ae6 --- /dev/null +++ b/modules/proc-mcp-gateway-install-olm.adoc @@ -0,0 +1,90 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-mcp-gateway-install-olm_{context}"] += Installing the MCP gateway with OLM + +[role="_abstract"] +You can install the MCP gateway deployment Operator by using Operator Lifecycle Manager (OLM) with the CLI. When choosing this path, you must create a `MCPGatewayExtension` custom resources (CR) manually and apply it to complete your initial setup. + +.Prerequisites + +* You installed {ocp}. +* You installed {oc-first}. + +.Procedure + +. Create the namespace where you want to install {mcpg} by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc create ns __ +---- ++ +Replace the default `__` with the namespace you want to use. + +. Create and apply the {mcpg} `Subscription` and `OperatorGroup` custom resources (CRs) by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -n __ -f - <_ +EOF +---- ++ +Replace `__` with the namespace you used in the earlier step. + +. Confirm that the {mcpg} installation has finished by running the following commands: ++ +[source,terminal,subs="+quotes"] +---- +$ oc wait --for=jsonpath={.status.installPlanRef.name} subscription mcp-gateway -n __ --timeout=10s +ip=$(oc get subscription mcp-gateway -n __ -o=jsonpath={.status.installPlanRef.name}) +---- ++ +Replace `__` with the namespace you used in the earlier step. ++ +[source,terminal,subs="+quotes"] +---- +$ oc wait --for=condition=Installed installplan -n __ ${ip} --timeout=60s +---- ++ +* Replace `__` with the namespace you used in the earlier step. +* Expect the status of `installplan.operators.coreos.com/install-` when {mcpg} is ready. The name of the install plan has a random suffix, for example, `4rql7`. + +.Verification + +. Wait for the controller to be ready by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc wait csv -n __ -l operators.coreos.com/mcp-gateway.__="" --for=jsonpath='{.status.phase}'=Succeeded --timeout=5m +---- ++ +Replace `__` with the namespace you used. + +.Next steps + +* Configure a listener for your `Gateway` object. +* Create a `ReferenceGrant` CR if you require cross-namespace referencing. +* Deploy the MCP gateway by creating an `MCPGatewayExtension` CR. +* Configure authentication and authorization for your connections. +* Create `MCPServerRegistration` CRs to register your MCP servers. diff --git a/modules/proc-mcp-gateway-referencegrant.adoc b/modules/proc-mcp-gateway-referencegrant.adoc new file mode 100644 index 000000000000..4b22f56aace3 --- /dev/null +++ b/modules/proc-mcp-gateway-referencegrant.adoc @@ -0,0 +1,51 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-mcp-gateway-referencegrant_{context}"] += Applying a ReferenceGrant custom resource + +[role="_abstract"] +You can isolate teams within a single cluster by applying team-specific `MCPGatewayExtension` custom resources (CRs) in individual namespaces that all target a shared `Gateway` object. When you apply an `MCPGatewayExtension` CR in a different namespace than the `Gateway` CR, you must then create a `ReferenceGrant` in the namespace of the gateway to give access. + +.Prerequisites + +* You installed {ocp}. +* You installed {oc-first}. +* You installed the {mcpg} Operator. +* You configured at least one listener. + +.Procedure + +. Create a `ReferenceGrant` CR by using the following example as a template: ++ +.Example ReferenceGrant CR +[source,yaml,subs="+quotes"] +---- +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: ReferenceGrant +metadata: + name: __ + namespace: gateway-system +spec: + from: + - group: mcp.kuadrant.io + kind: MCPGatewayExtension + namespace: __ + to: + - group: gateway.networking.k8s.io + kind: Gateway +---- ++ +* Replace the `metadata.name:` value with the name that you want to use. +* Replace the `spec.from.namespace:` value with the namespace where the `MCPGatewayExtension` CR is applied. + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with name you used. diff --git a/modules/ref-mcp-gateway-auto-route.adoc b/modules/ref-mcp-gateway-auto-route.adoc new file mode 100644 index 000000000000..67a966a0f2d3 --- /dev/null +++ b/modules/ref-mcp-gateway-auto-route.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_install/mcp-gateway-install.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-mcp-gateway-auto-route_{context}"] += Automatically created HTTPRoute example + +[role="_abstract"] +Applying the `MCPGatewayExtension` custom resources (CR) generates an automatic `HTTPRoute` CR. The following is an example of the route. + +.Example automatically generated HTTPRoute CR +[source,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: mcp-gateway-route + namespace: mcp-gateway-namespace +spec: + parentRefs: + - name: mcp-gateway + namespace: istio-system + sectionName: mcp + rules: + - matches: + - path: + type: PathPrefix + value: /mcp + backendRefs: + - name: mcp-gateway + port: 8080 +---- + +* The value of the `spec.parentRefs.name:` parameter matches your `Gateway` CR name. +* The value of the `spec.parentRefs.namespace:` parameter matches your `Gateway` namespace. +* The value of the `spec.parentRefs.sectionName:` parameter matches the `spec.listeners[*].name` value of your `Gateway` object listener. +* The value of the `spec.rules.backendRefs.name:` is the Kubernetes service for your MCP gateway. +* The value of the `spec.rules.backendRefs.port:` is the port that the MCP gateway is listening on.