Ingress and TLS

Ingress is off by default, because a first install shouldn’t need DNS. Once you want real hostnames, the chart renders three Ingress objects for you.

Supported controllers

Controller	`className`	Status
Traefik	`traefik`	Supported — the default, and what every Swarmd-operated environment runs.
AWS Load Balancer Controller	`alb`	Supported on EKS.
ingress-nginx	`nginx`	Not supported. Not recommended.

Do not build a new deployment on ingress-nginx. Upstream has wound the project down, so it is not somewhere to put a platform you intend to run.The chart emits plain Ingress objects, so it will render against ingress-nginx and largely work — but we do not test that path, and we will not fix issues specific to it. If you are already on ingress-nginx, plan a move to Traefik; the only thing that changes in this chart is className and the annotation block.

The three hostnames

Host	Serves	Who talks to it	Override
`app.<domain>`	Platform UI	Browsers	`ui.platform.ingress.host`
`api.<domain>`	Gateway — every REST, A2A and MCP call	Agents, SDKs, your apps, people’s MCP clients	`services.gateway.ingress.host`
`auth.<domain>`	Keycloak	Browsers during login; agents for tokens; MCP clients signing in	`keycloak.ingress.host`

All three derive from global.domain unless you override them individually.

MCP clients: Claude Code, Claude Desktop, Cursor

An MCP server’s Connect card gives people a command such as claude mcp add --transport http <name> https://api.<domain>/relay/v1/mcp-servers/<id>/mcp. Their MCP client then signs in with OAuth by itself: it reads the relay’s resource metadata on api.<domain>, opens a browser login on auth.<domain>, and calls the relay with the token it gets back. So both hosts must be reachable from people’s own machines, not just from inside the cluster, and each person must be subscribed to the MCP server (its Users tab).

Ingress on: nothing to set — the chart derives the relay URL, its OAuth resource and the callback for OAuth-protected MCP servers from api.<domain>.
You expose the gateway yourself (a load balancer, a VPN hostname): set services.gateway.publicUrl: https://swarmd-api.example.com, and make Keycloak reachable at its public URL too.
Port-forward only (for example the PrismForce preset): people cannot connect MCP clients. The Connect card says no relay URL is provisioned, and helm install / helm upgrade print a note saying so. Agents in the cluster are not affected.

auth.<domain> must be reachable from outside the cluster. It is tempting to keep Keycloak internal, but browsers get redirected there during login and agents fetch tokens from it. When ingress is on, the chart switches Keycloak’s issuer to the public URL — tokens minted with an internal issuer would be rejected by anything validating them from outside — and tenant-auth signs users in through that URL, so without it every login fails.

The Keycloak Ingress routes only /realms (logins, tokens, discovery) and /resources (login page assets). The admin console under /admin is not exposed; reach it with a port-forward, or set keycloak.ingress.exposeAdminConsole: true if you need it on the public host. If you expose Keycloak some other way at the same host, set keycloak.ingress.enabled: false.

The base configuration

global:
  domain: swarmd.example.com

  ingress:
    enabled: true
    className: traefik         # must match an IngressClass in your cluster
    annotations: {}            # applied to all three Ingresses
    tls:
      enabled: true
      secretName: swarmd-tls   # must already exist — the chart issues nothing

Two things to know before the examples:

tls.secretName is a single value shared by all three Ingresses. One certificate has to cover app., api. and auth. — a SAN or wildcard cert. If you need a certificate per host, set tls.enabled: false and drive TLS from your controller’s annotations instead (that’s what the AWS example below does).
Annotations merge, with per-component winning over global. So you can set a shared block globally and add one annotation to just the gateway.

Worked examples

Traefik + cert-manager (recommended)
AWS Load Balancer Controller

Traefik reads standard Ingress objects, so className: traefik is most of the job.

global:
  domain: swarmd.example.com
  ingress:
    enabled: true
    className: traefik
    tls:
      enabled: true
      secretName: swarmd-tls
    annotations:
      traefik.ingress.kubernetes.io/router.entrypoints: websecure
      # Attach middleware by <namespace>-<name>@kubernetescrd
      traefik.ingress.kubernetes.io/router.middlewares: swarmd-compress@kubernetescrd

Using Traefik’s own ACME resolver rather than cert-manager? Then Traefik holds the certificate itself and you don’t want a tls block at all:

global:
  ingress:
    enabled: true
    className: traefik
    tls:
      enabled: false     # Traefik terminates with its own cert store
    annotations:
      traefik.ingress.kubernetes.io/router.entrypoints: websecure
      traefik.ingress.kubernetes.io/router.tls: "true"
      traefik.ingress.kubernetes.io/router.tls.certresolver: letsencrypt

Raise respondingTimeouts.readTimeout in Traefik’s static config. A multi-hop agent chain routinely runs 40–60 seconds, and the relay holds a conversation send for up to 100 s before returning 202. Leave Traefik at a 60 s default and chains fail at the proxy that the platform would have completed — as a client timeout, with nothing in the Swarmd logs to explain it.

On EKS the ALB terminates TLS with an ACM certificate, so there is no Kubernetes TLS Secret — tls.enabled stays false and everything is driven by annotations.

global:
  domain: swarmd.example.com
  ingress:
    enabled: true
    className: alb
    tls:
      enabled: false     # ACM on the ALB, not a K8s Secret
    annotations:
      alb.ingress.kubernetes.io/scheme: internet-facing
      alb.ingress.kubernetes.io/target-type: ip
      alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
      alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:eu-west-1:123456789012:certificate/abcd-1234
      alb.ingress.kubernetes.io/ssl-redirect: "443"
      alb.ingress.kubernetes.io/healthcheck-path: /actuator/health
      # Long agent chains — the ALB default is 60s.
      alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=300
      # Put all three hosts on ONE ALB instead of three.
      alb.ingress.kubernetes.io/group.name: swarmd

Set group.name. Without it the controller provisions a separate ALB per Ingress — three load balancers, three sets of DNS, three bills. With it, all three hostnames share one.

Health check path

/actuator/health is right for the gateway. The platform UI is a static front end and doesn’t serve it — if the UI target group goes unhealthy, set a UI-specific override:

ui:
  platform:
    ingress:
      annotations:
        alb.ingress.kubernetes.io/healthcheck-path: /

Per-component annotations merge over the global block, so this replaces just that one key for the UI.

Internal-only ALB

For a private deployment reachable only inside the VPC:

      alb.ingress.kubernetes.io/scheme: internal

Remember auth.<domain> still has to resolve and be reachable from wherever your users’ browsers are — a private ALB means VPN or Direct Connect for them too.

Migrating off ingress-nginx

The chart emits standard Ingress objects, so moving is a values change rather than a redeployment:

Install Traefik and confirm its IngressClass exists — kubectl get ingressclass.
Swap global.ingress.className from nginx to traefik.
Replace the nginx.ingress.kubernetes.io/* annotations with the Traefik equivalents above. The one that matters is the read timeout — it moves from a per-Ingress annotation to Traefik’s static config.
helm upgrade, then re-point DNS at the Traefik load balancer.

Run both controllers side by side during the cutover if you can: the two IngressClasses are independent, so nothing conflicts.

DNS

The chart creates Ingress objects; it does not touch DNS. Point all three names at your ingress controller’s address:

app.swarmd.example.com   → <ingress IP or ALB hostname>
api.swarmd.example.com   → <same>
auth.swarmd.example.com  → <same>

A wildcard *.swarmd.example.com covers all three and anything you add later.

Testing on minikube without DNS? Use nip.io, which resolves any <anything>.<ip>.nip.io to that IP:

helm upgrade swarmd ... \
  --set global.ingress.enabled=true \
  --set global.domain=$(minikube ip).nip.io \
  --set global.ingress.tls.enabled=false

Verifying

kubectl -n swarmd get ingress

NAME                  CLASS     HOSTS                    ADDRESS         PORTS
swarmd-gateway        traefik   api.swarmd.example.com   203.0.113.10    80, 443
swarmd-platform-ui    traefik   app.swarmd.example.com   203.0.113.10    80, 443
swarmd-keycloak       traefik   auth.swarmd.example.com  203.0.113.10    80, 443

Then check each hop:

# Gateway is up and terminating TLS
curl -sS -o /dev/null -w '%{http_code}\n' https://api.swarmd.example.com/actuator/health

# Keycloak is serving the realm with the PUBLIC issuer
curl -sS https://auth.swarmd.example.com/realms/swarmd/.well-known/openid-configuration \
  | jq -r .issuer

That last one is the check worth doing. It must print https://auth.swarmd.example.com/realms/swarmd. If it prints an in-cluster service URL, ingress was enabled without Keycloak picking up the public hostname, and every externally-issued token will fail audience validation.

Ingress has no ADDRESS

The controller hasn’t claimed it — usually a className that matches no IngressClass in the cluster:

kubectl get ingressclass

404 from the ingress controller

The controller is answering but has no rule for that host. Check the Host header matches exactly — api.<domain>, not the bare domain — and that DNS points where you think.

Long agent calls fail at ~60 seconds

Proxy timeout, not Swarmd. Raise it — respondingTimeouts.readTimeout on Traefik, idle_timeout.timeout_seconds on ALB. The relay holds a conversation send for up to 100 s before returning 202.

Configuration

SMTP, secrets, app settings and optional components.

Presets

Ready-made values files, including HTTPS shapes.

Get started

How it works

Shape your deployment

Reference

Ingress and TLS

Ingress and TLS

Supported controllers

The three hostnames

MCP clients: Claude Code, Claude Desktop, Cursor

The base configuration

Worked examples

DNS

Verifying

Next

Configuration

Presets

​Ingress and TLS

​Supported controllers

​The three hostnames

​MCP clients: Claude Code, Claude Desktop, Cursor

​The base configuration

​Worked examples

​DNS

​Verifying

​Next

Configuration

Presets

Ingress and TLS

Supported controllers

The three hostnames

MCP clients: Claude Code, Claude Desktop, Cursor

The base configuration

Worked examples

DNS

Verifying

Next