Ingress & TLS

By default 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, Let's Encrypt, and the chart-managed Ingress. 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.baseUrl in your values, mirror those changes in your ingress (the chart-managed Ingress picks them up automatically).

Two NGINX-specific annotations matter:

• nginx.ingress.kubernetes.io/proxy-buffer-size: "128k" - required for Keycloak's large authentication headers. NGINX's own default is 4k, which truncates them and breaks every login with upstream sent too big header.
• nginx.ingress.kubernetes.io/proxy-body-size: "10m" - caps API spec uploads. NGINX's own default is 1m, which rejects larger specs with 413 Request Entity Too Large.

Both are BoltMCP requirements rather than site preferences, so the chart-managed Ingress applies them for you - don't repeat them in your values file. You only set them explicitly to choose a different limit, or when you're authoring your own Ingress manifest. To change one, set the same key in ingress.annotations: your value replaces the chart default, and any other annotations you supply are merged alongside it.

The equivalent settings exist on most ingress implementations; check your platform's docs.

If you're authoring your own Ingress manifest rather than using the chart-managed one, the chart package's examples/ingress directory contains a reference manifest to start from.

Reference Ingress Setup

The rest of this page walks through one common setup: NGINX Ingress Controller, DNS-based routing, and the chart-managed Ingress tying them together, followed by cert-manager for automatic TLS in Reference TLS Setup. Skip the controller and cert-manager steps if your cluster already has them.

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

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace

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

NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)                      AGE
ingress-nginx-controller   LoadBalancer   xx.xx.xxx.xx   xxx.xx.x.x    80:32127/TCP,443:31751/TCP   7s

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

gcloud compute addresses describe boltmcp-ingress-ip \
  --region $REGION \
  --format='value(address,status)'
# Should print your EXTERNAL-IP and IN_USE

# 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.

Enable the Chart-managed Ingress

Add an ingress block to your values file. The annotations differ depending on whether or not you're terminating TLS:

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-staging

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"

# Local install only (e.g. Docker Desktop): let in-cluster pods resolve the
# public hostnames to the ingress so server-side OIDC discovery reaches
# Keycloak. Set `ip` to the ingress controller's CLUSTER-IP.
global:
  hostAliases:
    - ip: "<ingress-nginx-controller CLUSTER-IP>"
      hostnames:
        - web.boltmcp.local
        - auth.boltmcp.local
        - server.boltmcp.local
        - inspector.boltmcp.local

127.0.0.1 web.boltmcp.local auth.boltmcp.local server.boltmcp.local inspector.boltmcp.local

Apply the change using the same chart version and values file as the install (re-export HELM_REGISTRY_CONFIG and BOLTMCP_VERSION first if you're in a new shell):

helm upgrade boltmcp \
  oci://europe-west2-docker.pkg.dev/boltmcp-platform/boltmcp-alpha/charts/boltmcp \
  --version ${BOLTMCP_VERSION} \
  -n boltmcp \
  -f ./config/values-prod.yaml \
  --timeout 15m

Reference TLS Setup

These steps add automatic HTTPS to the chart-managed Ingress via cert-manager and Let's Encrypt. Skip this section entirely on a plain-HTTP install (global.tls.enabled: false), or if your cluster already terminates TLS in front of the ingress.

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

With the staging issuer in place, the certificate referenced by the chart-managed Ingress (applied in Enable the Chart-managed Ingress above) can now be provisioned. Watch it:

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.

Point the Ingress at the production issuer by updating the annotation in values-prod.yaml:

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

Run the same helm upgrade command as in the previous step, then delete the staging certificate Secret to trigger re-issuance:

kubectl delete secret boltmcp-tls -n boltmcp

Verify the new certificate:

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

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. Your browser should now show a trusted certificate without security warnings.