hanzo-ingress

Hanzo Ingress is a Kubernetes-native L7 reverse proxy and load balancer that serves as the entry point for all Hanzo production traffic.

Hanzo Ingress - L7 Reverse Proxy and Load Balancer

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-k8s.md, hanzo/hanzo-deploy.md, hanzo/hanzo-static.md

Overview

Hanzo Ingress is a Kubernetes-native L7 reverse proxy and load balancer that serves as the entry point for all Hanzo production traffic. Fork of Traefik. Watches Kubernetes Ingress resources, auto-provisions TLS certificates via Let's Encrypt, routes traffic to internal services. Single static Go binary, zero runtime dependencies. Default IngressClass (hanzo) on hanzo-k8s cluster.

When to use

Routing external traffic to K8s services
TLS termination for .hanzo.ai, .hanzo.team, and other domains
Applying middleware (rate limiting, auth, compression) to routes
Load balancing across service replicas
Creating Ingress resources for new services

Hard requirements

No nginx, no caddy -- Hanzo Ingress is the only reverse proxy
IngressClass hanzo on all Ingress resources
Cloudflare DNS with full SSL proxied to cluster LB
Ports 80/443 via hostNetwork mode
cert-manager for Let's Encrypt TLS provisioning

Quick reference

| Item | Value | |------|-------| | Image | ghcr.io/hanzoai/ingress:latest | | Binary | hanzo-ingress | | IngressClass | hanzo (default) | | Controller | hanzo.ai/ingress-controller | | Health check | GET /ping on port 80 | | Replicas | 2 (production) | | Namespace | hanzo | | Network | hostNetwork (direct port binding) | | Ports | 80 (HTTP), 443 (HTTPS) | | Resources | 100m-1000m CPU, 128Mi-512Mi memory | | Upstream | Traefik | | Repo | github.com/hanzoai/ingress | | Module | github.com/hanzoai/ingress/v3 | | Go version | 1.26 | | K8s manifests | universe/infra/k8s/ (per-service Ingress) | | K8s context | do-sfo3-hanzo-k8s |

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
 +---+----+ +---+ +------+ +------+
 |Gateway | |IAM| | KMS | |Cloud |
 |(API) | +---+ +------+ +------+
 +---+----+
 |
 Backend services

Request flow

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

Routed domains (production)

| Domain | Backend Service | Port | |--------|-----------------|------| | hanzo.ai | hanzo-app | 3000 | | api.hanzo.ai, llm.hanzo.ai | Hanzo Gateway | 8000 | | hanzo.id, lux.id, zoo.id, pars.id | IAM (Hanzo IAM) | 8000 | | kms.hanzo.ai | KMS (Hanzo KMS) | 8080 | | platform.hanzo.ai | Platform (Dokploy) | 3000 | | console.hanzo.ai | Console (Langfuse) | 3000 | | cloud.hanzo.ai | Cloud (Casibase) | 8000 | | chat.hanzo.ai | Chat (LibreChat) | 3080 | | hanzo.team | Team (Huly fork) | 8087 | | billing.hanzo.ai | Billing | 80 | | o11y.hanzo.ai | Hanzo o11y | 3301 |

Create an Ingress resource

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

Middleware

Apply via Kubernetes Ingress annotations or IngressRoute CRDs:

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

Built-in middleware: auth, ratelimiter, circuitbreaker, retry, compress, headers, ipallowlist, buffering, inflightreq, redirect, stripprefix, grpcweb, observability (OTEL), metrics (Prometheus), accesslog.

K8s manifests

k8s/hanzo/
 rbac.yaml # ServiceAccount + ClusterRole
 ingressclass.yaml # IngressClass "hanzo" (default)
 deployment.yaml # 2-replica Deployment, hostNetwork
 service.yaml # LoadBalancer Service
 middlewares.yaml # Default middleware configurations

Production CLI flags

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

Build and deploy

# Build from source
make build

# Deploy to production
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

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

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Port conflict on 80/443 | Other ingress controller | Remove conflicting controller | | TLS cert not provisioned | cert-manager not configured | Install cert-manager with letsencrypt issuer | | 404 on known domain | Ingress resource missing | Check ingressClassName: hanzo | | Dashboard not loading | Disabled in production | Use port-forward or enable in non-prod | | WebSocket not working | Missing upgrade headers | Add WebSocket middleware to IngressRoute |

Related Skills

hanzo/hanzo-static.md -- Static file serving plugin
hanzo/hanzo-k8s.md -- K8s infrastructure
hanzo/hanzo-deploy.md -- Deployment workflow
hanzo/hanzo-gateway.md -- API gateway (behind Ingress)

Last Updated: 2026-03-23 Category: Hanzo Ecosystem Related: ingress, reverse-proxy, load-balancer, kubernetes, tls, traefik Prerequisites: Kubernetes, DNS, TLS basics