Ingress & TLS

The BoltMCP chart doesn't manage cluster ingress. It expects you to provision your own ingress / gateway / load balancer that terminates TLS and routes the BoltMCP hostnames to the in-cluster services.

If your platform team handles ingress, hand them the hostnames table below and skip the rest of this page. The walkthrough that follows is a reference setup using NGINX Ingress Controller, cert-manager, and Let's Encrypt - adapt it for your environment, or replace it entirely with whatever ingress your cluster already runs.

What BoltMCP needs from your ingress

For every value of global.domain you set in values-prod.yaml, the chart configures the workloads to expect these public hostnames, terminating TLS, routed to these in-cluster Services:

If you've overridden any of web.baseUrl, mcpServer.baseUrl, mcpInspector.baseUrl, or keycloak.hostname in your values, mirror those changes in your ingress.

One NGINX-specific annotation is commonly needed:

• nginx.ingress.kubernetes.io/proxy-buffer-size: "128k" - required for Keycloak's large authentication headers.

The equivalent setting exists on most ingress implementations; check your platform's docs.

Reference setup

The rest of this page walks through one common setup: NGINX Ingress Controller, cert-manager for automatic TLS, and DNS-based routing. Skip if your cluster already has these.

Install NGINX Ingress Controller

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.externalTrafficPolicy=Local

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.externalTrafficPolicy=Local \
  --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-scheme"=internet-facing

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.externalTrafficPolicy=Local

Wait for the external IP:

kubectl get svc ingress-nginx-controller -n ingress-nginx -w

Expected output:

NAME                       TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)                      AGE
ingress-nginx-controller   LoadBalancer   xx.x.xxx.xx   x.xxx.xxx.xxx   80:32695/TCP,443:30691/TCP   2m8s

NAME                       TYPE           CLUSTER-IP    EXTERNAL-IP                         PORT(S)                      AGE
ingress-nginx-controller   LoadBalancer   xx.xxx.x.xx   xx-xx.eu-west-2.elb.amazonaws.com   80:30454/TCP,443:31623/TCP   2m8s

NAME                       TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)                      AGE
ingress-nginx-controller   LoadBalancer   xx.x.xxx.xx   x.xxx.xxx.xxx   80:32695/TCP,443:30691/TCP   2m8s

Reserve a Stable Address

Give the load balancer a stable address so your DNS records stay valid across restarts. Whether you need to do anything here depends on your cloud:

REGION=$(gcloud container clusters describe <cluster-name> \
  --format="get(location)" | sed 's/-[a-z]$//')

CURRENT_IP=$(kubectl get svc ingress-nginx-controller \
  -n ingress-nginx \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

gcloud compute addresses create boltmcp-ingress-ip \
  --addresses $CURRENT_IP \
  --region $REGION

# Create a static public IP in the node resource group
NODE_RG=$(az aks show \
  --resource-group boltmcp-rg \
  --name boltmcp-cluster \
  --query nodeResourceGroup -o tsv)

az network public-ip create \
  --resource-group $NODE_RG \
  --name boltmcp-ingress-ip \
  --sku Standard \
  --allocation-method Static \
  --zone 1 2 3 \
  --location westeurope

helm upgrade ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --reuse-values \
  --set controller.service.loadBalancerIP=<static-ip>

Configure DNS

Point each BoltMCP subdomain at the load balancer. The record type depends on what the previous steps gave you, and the hostname values depend on whether your global.domain matches the DNS hosted zone.

• If your load balancer is an IP address (GKE, AKS, or an EKS NLB+EIP), create A records.
• If it's a DNS hostname (the default EKS Classic ELB), create CNAME records - a raw hostname can't go in an A record.

In the tables below, <lb-endpoint> is the EXTERNAL-IP you noted earlier (an IP or a hostname) and <record-type> is A for an IP or CNAME for a hostname.

Verify propagation across all four subdomains:

for h in web auth server inspector; do
  printf "%s -> " "$h.<domain>"
  dig +short "$h.<domain>" @8.8.8.8 || echo "(none)"
done

Each line should resolve to your load balancer - directly to the IP for A records, or to the load balancer hostname (and, below it, the IPs it points to) for CNAME records. Replace <domain> with your global.domain value.

Install cert-manager

helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

Wait for all cert-manager pods to be running:

kubectl get pods -n cert-manager

Create a ClusterIssuer

Start with a staging issuer for testing (avoids Let's Encrypt rate limits):

kubectl apply -f ./config/cluster-issuer-staging.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-staging-account-key
    solvers:
      - http01:
          ingress:
            class: nginx

Replace your-email@example.com with a mailbox you actually monitor. Let's Encrypt uses this address to warn you when a certificate is approaching expiry without having auto-renewed - it's your only signal that renewal is broken before the cert goes down.

Verify:

kubectl get clusterissuer
# READY should be True

Create the Ingress Resource

kubectl apply -f ./config/boltmcp-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: boltmcp-ingress
  namespace: boltmcp
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-staging
    nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - web.boltmcp.example.com
        - auth.boltmcp.example.com
        - server.boltmcp.example.com
        - inspector.boltmcp.example.com
      secretName: boltmcp-tls
  rules:
    - host: web.boltmcp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: boltmcp-web
                port:
                  number: 3000
    - host: auth.boltmcp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: boltmcp-keycloak
                port:
                  number: 8080
    - host: server.boltmcp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: boltmcp-mcp-server
                port:
                  number: 3001
    - host: inspector.boltmcp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: boltmcp-mcp-inspector
                port:
                  number: 6274

The proxy-buffer-size annotation is required for Keycloak's large authentication headers.

Watch certificate provisioning:

kubectl get certificates -n boltmcp -w
# Wait for READY to become True

Switch to Production Certificates

Once everything works with staging certificates, create a production issuer:

kubectl apply -f ./config/cluster-issuer-production.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-production
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-production-account-key
    solvers:
      - http01:
          ingress:
            class: nginx

Again, replace your-email@example.com with a monitored mailbox so you receive Let's Encrypt's renewal-failure warnings.

Update the ingress annotation in boltmcp-ingress.yaml (edit the file on disk, not the live resource):

annotations:
  cert-manager.io/cluster-issuer: letsencrypt-production

Delete the staging certificate to trigger re-issuance:

kubectl delete secret boltmcp-tls -n boltmcp
kubectl apply -f ./config/boltmcp-ingress.yaml

Verify the new certificate:

kubectl get certificates -n boltmcp -w
# Wait for READY = True

Your browser should now show a trusted certificate without security warnings.

Congratulations

You've successfully exposed BoltMCP to the public internet with TLS-secured ingress. Your cluster is now reachable at your configured hostnames with valid, auto-renewing certificates.