Traefik

Overview

Traefik serves as the reverse proxy and Kubernetes ingress controller for AKKO. It handles TLS termination, automatic service routing via Ingress resources, and OAuth2 forward-auth middleware for services that lack native OIDC support.

Architecture

  Internet / Browser
        │
        ▼
  Traefik (:443 / :80)
    ├── TLS termination (self-signed or Let's Encrypt)
    ├── Forward-auth middleware ──→ OAuth2 Proxy ──→ Keycloak
    │
    ├──→ akko.local             ──→ akko-cockpit:80
    ├──→ federation.akko.local       ──→ akko-trino:8080
    ├──→ jupyterhub.akko.local  ──→ akko-jupyterhub:8000
    ├──→ orchestrator.akko.local     ──→ akko-airflow-webserver:8080
    ├──→ bi.akko.local    ──→ akko-superset:8088
    ├──→ identity.akko.local    ──→ akko-keycloak:8080
    ├──→ grafana.akko.local     ──→ akko-grafana:3000
    ├──→ minio.akko.local       ──→ akko-minio:9001
    ├──→ experiments.akko.local      ──→ akko-mlflow:5000
    └──→ ...                    ──→ (all other services)

Every AKKO service is accessed through Traefik — no service exposes ports directly to the host network.

Ports

Port	Purpose	Exposed
80	HTTP — redirects all traffic to HTTPS (port 443)	Yes (NodePort / LoadBalancer)
443	HTTPS — TLS-terminated entry point for all services	Yes (NodePort / LoadBalancer)
8080	Traefik dashboard (disabled in production)	Internal only

Key Features

• Automatic ingress routing — reads Kubernetes Ingress resources and configures routes without restart
• TLS termination — uses self-signed certificates in dev (k3d), supports Let's Encrypt / cert-manager in production
• Forward-auth middleware — protects services without native OIDC (Dashboards, MLflow, LiteLLM, Cockpit) by delegating authentication to OAuth2 Proxy
• HTTP-to-HTTPS redirect — all port 80 traffic is redirected to 443
• Middleware chains — supports rate limiting, headers, and compression via Kubernetes middleware CRDs

Configuration

Ingress Resource Example

Each service defines its own Ingress resource in its Helm sub-chart:

ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: akko-superset
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"
spec:
  rules:
    - host: bi.akko.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: akko-superset
                port:
                  number: 8088

Forward-Auth Middleware

Services that need OAuth2 protection use a Traefik middleware annotation:

metadata:
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: >-
      akko-oauth2-proxy-forward-auth@kubernetescrd

This forwards every request to OAuth2 Proxy, which validates the session against Keycloak before allowing access.

Helm Chart

Traefik is deployed via the official Traefik community Helm chart:

Chart.yaml (dependency)

- name: traefik
  version: "34.3.0"
  repository: https://traefik.github.io/charts

Key Values

values.yaml

traefik:
  ports:
    web:
      redirectTo:
        port: websecure
    websecure:
      tls:
        enabled: true
  providers:
    kubernetesIngress:
      enabled: true
  logs:
    general:
      level: INFO

k3d Port Mapping

In k3d development clusters, ports 80 and 443 are mapped to the host via k3d cluster create --port "80:80@loadbalancer" --port "443:443@loadbalancer". The k3d-create.sh script handles this automatically.

Troubleshooting

Common Issues

• 502 Bad Gateway: The target service pod is not ready or the Service name/port is incorrect. Check kubectl get endpoints <service-name> to verify endpoints exist. Also verify the service's readiness probe is passing.
• Redirect loop with OAuth2: Ensure the OAuth2 Proxy cookie domain matches the ingress hostname. In k3d, all services must share the same base domain (.akko.local). Check that the Keycloak client has the correct redirect URI.
• TLS certificate errors in Safari: Self-signed certificates require manual trust on macOS. Add the CA to Keychain Access, or use --insecure for CLI tools. For k3d, the deploy.sh script generates and trusts a local CA.