Kubernetes Deployment

This guide deploys the Gateway on Kubernetes as an ordinary stateless Deployment. It works on managed Kubernetes (EKS, GKE, AKS) and on self-managed clusters.

There is nothing unusual to model: no StatefulSet, no persistent volume, no leader election. All state lives in Postgres, so the Gateway is a plain horizontally-scaled web workload.

Overview

You’ll create these in a dedicated britive-mcp-gateway namespace:

• A Secret holding the tenant, pool token, and database URL. That is the whole of the pod’s configuration; every other setting comes from the gateway pool on your Britive tenant.
• A Deployment of two Gateway replicas, with startup, readiness, and liveness probes.
• A Service exposing them inside the cluster.
• An Ingress as one way to get traffic in.

Architecture

    flowchart LR
  Clients["MCP clients and agents"]
  Britive["Britive tenant"]
  Backends["Backend MCP servers"]

  subgraph ns["Namespace: britive-mcp-gateway"]
    Ing["Ingress<br/>TLS termination"]
    Svc["Service<br/>ClusterIP"]
    P1["Gateway pod"]
    P2["Gateway pod"]
    Ing --> Svc
    Svc --> P1
    Svc --> P2
  end

  DB[("Postgres<br/>(yours)")]

  Clients -->|"HTTPS"| Ing
  P1 --> DB
  P2 --> DB
  P1 --> Britive
  P1 --> Backends
  

Before You Begin

You need:

• A Kubernetes cluster and kubectl configured for it.
• A Postgres 14+ database the pods can reach. Not created by this manifest - a managed service is the expected choice.
• An ingress controller or another way to expose a Service, plus a TLS certificate.
• A Britive tenant and pool token.

Deploy

https://mcp-gateway.example.internal

kubectl apply -f mcp-gateway-k8s.yaml
kubectl -n britive-mcp-gateway rollout status deploy/mcp-gateway

kubectl -n britive-mcp-gateway get pods
kubectl -n britive-mcp-gateway logs deploy/mcp-gateway --tail=50

Verify

kubectl -n britive-mcp-gateway port-forward svc/mcp-gateway 8080:80
curl -s http://localhost:8080/healthz

Then through the Ingress:

• GET /healthz returns 200 at your hostname.
• Signing in at the root URL reaches the admin console.
• Deleting one pod leaves you signed in, and the replacement serves traffic - proof the pods share state through Postgres rather than holding it locally.

kubectl -n britive-mcp-gateway delete pod <one-pod-name>

Ingress Settings That Matter

The manifest sets three annotations because the defaults break real usage. They are written for nginx-ingress; use your controller’s equivalents.

nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
nginx.ingress.kubernetes.io/proxy-buffering: "off"

The timeouts. A Britive checkout that needs human approval can take longer than a default 60 seconds. An ingress that cuts the connection at 60s fails those tool calls, and it looks like a Gateway problem.

Buffering off. MCP holds a stream open for server-to-client messages. Buffering it makes a working call look like a hang.

Scaling and Upgrades

kubectl -n britive-mcp-gateway scale deploy/mcp-gateway --replicas=4

The Deployment uses maxUnavailable: 0, so a rolling upgrade brings up a new pod before removing an old one and the service stays up:

kubectl -n britive-mcp-gateway set image deploy/mcp-gateway \
  gateway=britive/mcp-gateway:<tag>
kubectl -n britive-mcp-gateway rollout status deploy/mcp-gateway

Schema migrations run on startup, so there is no migration Job to run. The startupProbe gives that first run room to finish before the liveness probe starts counting failures.

Changing Settings

Nothing beyond those three Secret keys is configured in the cluster. Audit sinks, rate limits, inspection, backend policy - all of it lives on the gateway pool in the Britive tenant portal, and every pod picks a change up on its next sync, within five minutes by default. No ConfigMap, no rollout, no restart.

That is deliberate: the person who changes a setting is a platform administrator, and the person who can kubectl rollout restart is frequently someone else. See Configuration.

Troubleshoot

Next Steps