ingress

Hanzo Ingress

Cloud-native L7 reverse proxy and load balancer for Hanzo AI infrastructure. Kubernetes-native with automatic TLS, dynamic configuration, and zero-downtime reloads.

Overview

Hanzo Ingress is the front door for all Hanzo production traffic. It watches Kubernetes Ingress resources, automatically provisions TLS certificates via Let's Encrypt, and routes traffic to internal services -- including Hanzo Gateway for API endpoints and direct service routing for web applications.

Deployed on the hanzo-k8s cluster as the default IngressClass (hanzo), it handles all *.hanzo.ai traffic with 2 replicas in host-network mode for direct port 80/443 binding.

Features

• Kubernetes-native -- watches Ingress resources, auto-configures routes
• Automatic TLS -- Let's Encrypt certificate provisioning and renewal (wildcard support)
• Dynamic configuration -- zero-restart config updates as Ingress resources change
• HTTP/2, gRPC, WebSocket -- full protocol support for all backend types
• Circuit breakers -- automatic failure isolation with configurable thresholds
• Retry logic -- built-in retry with exponential backoff
• Access logging -- JSON and Common Log Format output
• Metrics export -- Prometheus, Datadog, StatsD, InfluxDB, OTLP
• Web dashboard -- built-in UI for route visualization and health monitoring
• REST API -- programmatic access to configuration and status
• Single static binary -- no runtime dependencies, minimal attack surface
• Host-network mode -- direct port binding for minimal latency

Container Images

Quick Start

Docker

docker run -d \
  --name hanzo-ingress \
  -p 80:80 \
  -p 443:443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/hanzoai/ingress:latest \
  --entrypoints.web.address=:80 \
  --entrypoints.websecure.address=:443 \
  --providers.docker=true \
  --ping=true

Kubernetes

# Apply all manifests (RBAC, IngressClass, Deployment, Service)
kubectl apply -f https://raw.githubusercontent.com/hanzoai/ingress/master/k8s/hanzo/rbac.yaml
kubectl apply -f https://raw.githubusercontent.com/hanzoai/ingress/master/k8s/hanzo/ingressclass.yaml
kubectl apply -f https://raw.githubusercontent.com/hanzoai/ingress/master/k8s/hanzo/deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/hanzoai/ingress/master/k8s/hanzo/service.yaml

# Verify
kubectl -n hanzo get pods -l app=hanzo-ingress

Binary

Download a pre-built binary from GitHub Releases:

# Download latest release (Linux amd64)
curl -sL https://github.com/hanzoai/ingress/releases/latest/download/hanzo-ingress_linux_amd64.tar.gz | tar xz

# Run
./hanzo-ingress \
  --entrypoints.web.address=:80 \
  --entrypoints.websecure.address=:443 \
  --providers.kubernetesingress=true

Docker Compose

services:
  ingress:
    image: ghcr.io/hanzoai/ingress:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./acme.json:/acme.json
    command:
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--providers.docker=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=ops@hanzo.ai"
      - "--certificatesresolvers.letsencrypt.acme.storage=/acme.json"

Build from Source

make build
./hanzo-ingress --configFile=config.toml

Architecture

              Internet
                 |
        +--------+--------+
        | Cloudflare CDN  |
        | DNS, WAF, DDoS  |
        +--------+--------+
                 |
        +--------+--------+
        | Hanzo Ingress   |   L7 reverse proxy
        | (ports 80/443)  |   TLS termination
        | IngressClass:   |   Route matching
        |   "hanzo"       |   Load balancing
        +--+-+-+-+-+--+---+
           | | | | |  |
     +-----+ | | | |  +--------+
     |   +---+ | | +-----+     |
     |   |  +--+ +--+    |     |
     v   v  v       v    v     v
  +-----+-----+  +----+ +---+ +-------+  +-----+
  | Hanzo     |  | IAM| |KMS| | Cloud |  | PaaS|
  | Gateway   |  +----+ +---+ +-------+  +-----+
  | (API)     |
  +--+--+--+--+
     |  |  |
     v  v  v
  +------+------+------+
  |Engine|Search|  LLM |    Backend services
  +------+------+------+

Request Flow

1. DNS resolves *.hanzo.ai to Cloudflare
2. Cloudflare proxies to hanzo-k8s cluster LB (24.199.76.156)
3. Hanzo Ingress terminates TLS, matches host/path rules
4. Request forwarded to the matching backend service
5. For API traffic (api.hanzo.ai), Ingress routes to Hanzo Gateway for endpoint-level routing

Middleware Reference

Hanzo Ingress ships with a full suite of built-in middlewares that can be composed via annotations or configuration.

Middlewares are applied via Kubernetes Ingress annotations:

metadata:
  annotations:
    hanzo.ai/ingress-ratelimit-average: "100"
    hanzo.ai/ingress-ratelimit-burst: "200"

Or via TOML/YAML configuration for non-Kubernetes providers.

Kubernetes Deployment

IngressClass

Hanzo Ingress registers as the default IngressClass on the cluster:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: hanzo
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: hanzo.ai/ingress-controller

Any Ingress resource without an explicit ingressClassName is automatically picked up.

K8s Manifests

k8s/hanzo/
  rbac.yaml             # ServiceAccount, ClusterRole, ClusterRoleBinding
  ingressclass.yaml     # IngressClass "hanzo" (default)
  deployment.yaml       # 2 replicas, hostNetwork, ports 80/443
  service.yaml          # LoadBalancer service

Creating Ingress Resources

Once deployed, create standard Kubernetes Ingress resources to route traffic:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-service
  namespace: hanzo
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
spec:
  ingressClassName: hanzo
  tls:
  - hosts:
    - my-service.hanzo.ai
    secretName: my-service-tls
  rules:
  - host: my-service.hanzo.ai
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 8080

Production Deployment

Hanzo Ingress runs on the hanzo-k8s DOKS cluster (24.199.76.156) as the sole ingress controller for all Hanzo services.

Deploy / Update

kubectl --context do-sfo3-hanzo-k8s apply -f k8s/hanzo/

# Verify pods
kubectl --context do-sfo3-hanzo-k8s -n hanzo get pods -l app=hanzo-ingress

# Check service
kubectl --context do-sfo3-hanzo-k8s -n hanzo get svc hanzo-ingress

# View logs
kubectl --context do-sfo3-hanzo-k8s -n hanzo logs -l app=hanzo-ingress --tail=100 -f

Routed Domains (hanzo-k8s)

All domains below resolve through Cloudflare to this ingress instance:

Service Discovery

Hanzo Ingress supports multiple provider backends:

Production runs exclusively with the Kubernetes Ingress provider.

Configuration

CLI Flags (Production)

./hanzo-ingress \
  --providers.kubernetesingress=true \
  --providers.kubernetesingress.ingressendpoint.publishedservice=hanzo/hanzo-ingress \
  --providers.kubernetesingress.allowemptyservices=true \
  --entrypoints.web.address=:80 \
  --entrypoints.websecure.address=:443 \
  --entrypoints.websecure.http.tls=true \
  --ping=true \
  --ping.entryPoint=web \
  --api.dashboard=false \
  --log.level=INFO \
  --accesslog=true

Configuration File

[entryPoints]
  [entryPoints.web]
    address = ":80"
  [entryPoints.websecure]
    address = ":443"
    [entryPoints.websecure.http.tls]

[providers]
  [providers.kubernetesIngress]
    [providers.kubernetesIngress.ingressEndpoint]
      publishedService = "hanzo/hanzo-ingress"

[ping]
  entryPoint = "web"

[log]
  level = "INFO"

[accessLog]

See the sample configuration files in the repository root for full examples.

Repository Structure

cmd/                    # Binary entry point
internal/               # Core routing, middleware, provider logic
pkg/                    # Public packages and configuration types
webui/                  # Built-in dashboard (React)
k8s/
  hanzo/                # Production K8s manifests
    rbac.yaml           # ServiceAccount + ClusterRole
    ingressclass.yaml   # IngressClass "hanzo" (default)
    deployment.yaml     # 2-replica Deployment
    service.yaml        # LoadBalancer Service
integration/            # Integration test suite
contrib/                # Community contributed configs
docs/                   # Extended documentation
Dockerfile              # Multi-stage build (Node webui + Go binary)
Makefile                # Build, test, Docker targets

PaaS Integration

Hanzo Ingress serves as the ingress layer for Hanzo Platform (PaaS). Applications deployed through the platform automatically get:

• Ingress resource creation with proper host rules
• TLS certificate provisioning
• Load balancing across application replicas
• Access logging and metrics

Documentation

Full documentation is available at docs.hanzo.ai/docs/services/ingress.

Related Projects

Hanzo Ingress is part of the Hanzo AI infrastructure stack:

Internet -> Ingress (TLS/L7) -> Gateway (API routing) -> Engine (inference) / Cloud API / Services
                                                          Edge (on-device, client-side)

License

MIT -- see LICENSE.md.