R A U T A

AI-native Kubernetes API gateway. Lock-free. Agent-operable.

---

RAUTA is a Rust Kubernetes Gateway API controller and L7 HTTP proxy. It routes traffic with Maglev consistent hashing, manages backends with lock-free circuit breakers and rate limiters, and exposes everything to AI agents via MCP.

cargo build --release -p control      # gateway
cargo build --release -p rauta-cli    # CLI + kubectl plugin
cargo test --workspace                # 220+ tests, 5 crates

---

How it works

RAUTA watches Kubernetes Gateway API resources (GatewayClass, Gateway, HTTPRoute, EndpointSlice, Secret) and translates them into a routing table. Every HTTP request hitting the proxy gets:

1. Routed — radix tree path match, then Maglev consistent hash to pick a backend
2. Filtered — request/response header modification, redirects, timeouts, retries
3. Protected — lock-free circuit breaker + rate limiter before forwarding
4. Forwarded — HTTP/1.1 or HTTP/2 via per-worker connection pools

Client ──► Listener ──► Router ──► Filters ──► Forwarder ──► Backend
                                      │
              :9091 Admin API ◄───────┘
              MCP Tools (11)
              Diagnostics Engine (7 rules)
              Prometheus /metrics

The admin server on :9091 is completely separate from the data plane — you can always query gateway state even under load.

---

Lock-free hot path

Every request goes through the hot path. No locks touch health data or rate/circuit state:

What	Old	New
Circuit breaker state check	5 RwLock reads	1 AtomicU64 load
Rate limiter token acquire	3 RwLock writes	1 AtomicU64 CAS
Backend health + drain check	2 RwLock reads	1 ArcSwap load (~1ns)
Tried-backends tracking	HashSet (heap alloc)	u32 bitmask (stack)
Hop-by-hop header check	to_lowercase() (heap)	eq_ignore_ascii_case (zero-alloc)
Filter cloning for RouteMatch	Deep clone	Arc::clone (~1ns)

The circuit breaker packs state, failure_count, success_count, and half_open_requests into a single u64 and uses CAS loops for all transitions. The rate limiter packs tokens (16.16 fixed-point) and a timestamp into another u64.

---

Agent API

Three ways to talk to a running gateway. Same data, different interfaces:

MCP — for AI agents

11 tools for Claude Code, Cursor, or any MCP-compatible client:

rauta_status                 rauta_list_routes           rauta_get_route
rauta_list_circuit_breakers  rauta_list_rate_limiters    rauta_diagnose
rauta_drain_backend          rauta_undrain_backend       rauta_cache_stats
rauta_list_listeners         rauta_metrics_snapshot

CLI — for humans and scripts

rauta status                                  # table (default)
rauta routes list --format=json               # machine
rauta diagnose circuit-breaker-cascade --format=agent  # LLM-optimized
rauta backends drain 10.0.1.5:8080

The --format=agent output includes _meta and _hints blocks designed for LLM consumption. The binary is also available as kubectl-rauta.

REST — for everything else

GET  /api/v1/status          POST /api/v1/diagnose?symptom=...
GET  /api/v1/routes          GET  /api/v1/cache
GET  /healthz

---

Diagnostics engine

Deterministic rules. No LLM. Each produces a structured diagnosis with a causal chain, evidence, and actionable commands:

Rule	What it detects	Severity
RAUTA-CB-001	2+ circuit breakers open simultaneously (cascade)	Critical
RAUTA-CB-002	Single circuit breaker open	Warning
RAUTA-RL-001	Rate limit bucket exhausted (0 tokens)	Warning
RAUTA-BE-001	Route with zero healthy backends	Critical
RAUTA-BE-002	All backends draining on a route	Warning
RAUTA-CACHE-001	Route cache hit rate below 50%	Info
RAUTA-LISTEN-001	Multiple listeners competing for same port	Info

$ rauta diagnose circuit-breaker-cascade
[Critical] RAUTA-CB-001 (circuit-breaker-cascade)
  Cause: 2 backends have open circuit breakers
  Cause: Multiple simultaneous failures suggest upstream dependency issue
  Evidence: Backend 10.0.1.1:8080 is Open (failures: 5)
  Evidence: Backend 10.0.1.2:8080 is Open (failures: 5)
  Action: Check if backends share a common upstream dependency (rauta backends health)

---

Gateway API

Full Kubernetes Gateway API v1:

• Resources: GatewayClass, Gateway, HTTPRoute, EndpointSlice, Secret
• Matching: path prefix (radix tree), headers (exact + regex), query params, methods
• Filters: request/response header modification, redirects (301/302), timeouts, retries with exponential backoff
• Load balancing: Maglev consistent hashing — O(1) lookup, weighted, sticky via (client_ip, port) hash, ~1/N disruption on backend changes

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/v1
    backendRefs:
    - name: api-service
      port: 8080
      weight: 90
    - name: api-canary
      port: 8080
      weight: 10

---

Project layout

rauta/
  common/         no_std shared types — HttpMethod, Backend, Maglev, RouteKey
  control/        gateway controller + proxy + admin server (main binary)
  agent-api/      GatewayQuery trait, snapshot types, diagnostics engine
  mcp-server/     MCP tool definitions for AI agent integration
  rauta-cli/      CLI + kubectl-rauta plugin
  deploy/         K8s manifests, Grafana dashboards, Prometheus config
  docs/           architecture docs, research, ADRs
  scripts/        dev scripts, load tests, git hooks
  manifests/      raw K8s YAML (namespace, RBAC, DaemonSet)
  docker/         Dockerfiles for various build targets

---

Quick start

# standalone (no K8s)
RAUTA_BACKEND_ADDR=127.0.0.1:9090 ./target/release/control

# kubernetes
RAUTA_K8S_MODE=true ./target/release/control

# admin API always available
curl localhost:9091/api/v1/status

Variable	Default	Purpose
RAUTA_K8S_MODE	false	Start K8s controllers
RAUTA_BIND_ADDR	0.0.0.0:8080	Proxy listen
RAUTA_BACKEND_ADDR	—	Standalone backend
RAUTA_ADMIN_PORT	9091	Admin server
RAUTA_TLS_CERT / _KEY	—	TLS termination
RAUTA_GATEWAY_CLASS	rauta	GatewayClass to watch
RUST_LOG	info	Log level

---

Development

cargo test --workspace                                    # all tests
cargo clippy --all-targets --all-features -- -D warnings  # lint
cargo fmt --all -- --check                                # format check
make ci-local                                             # full CI

Pre-commit and pre-push hooks enforce fmt, clippy, and tests.

---

Built with

hyper · tokio · kube-rs · rustls · matchit · arc-swap · jemalloc · prometheus

---

Part of FALSE Systems

Tool	Finnish	Role
RAUTA	iron	API gateway
AHTI	god of the sea	Causality engine
POLKU	path	Event transport
KULTA	gold	Progressive delivery
TAPIO	forest god	Infrastructure management

---

Apache 2.0