Billy D.
832cda34bd
- Add AGENT-ONBOARDING.md for AI agents - Add ARCHITECTURE.md with full system overview - Add TECH-STACK.md with complete technology inventory - Add DOMAIN-MODEL.md with entities and bounded contexts - Add CODING-CONVENTIONS.md with patterns and practices - Add GLOSSARY.md with terminology reference - Add C4 diagrams (Context and Container levels) - Add 10 ADRs documenting key decisions: - Talos Linux, NATS, MessagePack, Multi-GPU strategy - GitOps with Flux, KServe, Milvus, Dual workflow engines - Envoy Gateway - Add specs directory with JetStream configuration - Add diagrams for GPU allocation and data flows Based on analysis of homelab-k8s2 and llm-workflows repositories and kubectl cluster-info dump data.
2.5 KiB
2.5 KiB
Use Envoy Gateway for Ingress
- Status: accepted
- Date: 2025-12-01
- Deciders: Billy Davies
- Technical Story: Selecting ingress controller for cluster
Context and Problem Statement
We need an ingress solution that supports:
- Gateway API (modern Kubernetes standard)
- gRPC for ML inference
- WebSocket for real-time chat/voice
- Header-based routing for A/B testing
- TLS termination
Decision Drivers
- Gateway API support (HTTPRoute, GRPCRoute)
- WebSocket support
- gRPC support
- Performance at edge
- Active development
- Envoy ecosystem familiarity
Considered Options
- NGINX Ingress Controller
- Traefik
- Envoy Gateway
- Istio Gateway
- Contour
Decision Outcome
Chosen option: "Envoy Gateway", because it's the reference implementation of Gateway API with full Envoy feature set.
Positive Consequences
- Native Gateway API support
- Full Envoy feature set
- WebSocket and gRPC native
- No Istio complexity
- CNCF graduated project (Envoy)
- Easy integration with observability
Negative Consequences
- Newer than alternatives
- Less documentation than NGINX
- Envoy configuration learning curve
Pros and Cons of the Options
NGINX Ingress
- Good, because mature
- Good, because well-documented
- Good, because familiar
- Bad, because limited Gateway API
- Bad, because commercial features gated
Traefik
- Good, because auto-discovery
- Good, because good UI
- Good, because Let's Encrypt
- Bad, because Gateway API experimental
- Bad, because less gRPC focus
Envoy Gateway
- Good, because Gateway API native
- Good, because full Envoy features
- Good, because extensible
- Good, because gRPC/WebSocket native
- Bad, because newer project
- Bad, because less community content
Istio Gateway
- Good, because full mesh features
- Good, because Gateway API
- Bad, because overkill without mesh
- Bad, because resource heavy
Contour
- Good, because Envoy-based
- Good, because lightweight
- Bad, because Gateway API evolving
- Bad, because smaller community
Configuration Example
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: companions-chat
spec:
parentRefs:
- name: eg-gateway
namespace: network
hostnames:
- companions-chat.lab.daviestechlabs.io
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: companions-chat
port: 8080