Skip to content

Commit 45b7d73

Browse files
mahmut-Abimahmut-Abi
committed
docs: clarify gateway repository guidance
1 parent 2c4af3d commit 45b7d73

3 files changed

Lines changed: 193 additions & 151 deletions

File tree

‎AGENTS.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Gateway Repository Guide
2+
3+
## Repository Role
4+
5+
This repository contains the Go control plane for Nantian Gateway. It watches Kubernetes Gateway API resources, translates them into internal routing state, serves admin APIs, and publishes runtime snapshots to data planes over gRPC/xDS.
6+
7+
Do not use this repository for Rust data plane, Dashboard, Helm chart, Website, or Proto source-of-truth changes. Those live in sibling repositories.
8+
9+
## Git Workflow
10+
11+
The workspace root is not a Git repository. This component directory is its own Git repository.
12+
13+
Make changes in an isolated worktree under `~/.config/superpowers/worktrees/`, not directly in the checked-out `gateway/` main checkout. Do not merge a worktree branch back to `main` until the user explicitly approves. Do not push `main` until the user explicitly asks after merge approval.
14+
15+
Root `docs/` files are workspace notes and do not need to be committed with gateway changes unless the user explicitly asks for archival handling.
16+
17+
## Commands
18+
19+
Run commands from the gateway repository root.
20+
21+
- `make build` builds all Go packages.
22+
- `make test` runs `go test -count=1 -timeout 5m ./...`.
23+
- `go test ./internal/translator` runs focused translator tests.
24+
- `go test ./internal/controller` runs focused controller tests.
25+
- `go test ./internal/admin` runs focused admin API tests.
26+
- `make e2e-smoke` runs the Kind smoke test.
27+
- `make conformance` creates a Kind cluster and runs Gateway API conformance tests.
28+
- No local protobuf generation target is currently defined here; protobuf source and generation workflow live in the sibling Proto repository.
29+
30+
Use focused `go test ./path` checks while iterating, then run the broader relevant target before committing.
31+
32+
## Project Map
33+
34+
- `cmd/manager/` starts the controller manager and wires runtime services.
35+
- `internal/controller/` watches Kubernetes resources and coordinates full or partial rebuilds.
36+
- `internal/translator/` converts Gateway API resources, policies, services, workloads, and extension objects into internal IR snapshots.
37+
- `internal/grpcserver/` publishes snapshots and status over gRPC/xDS to data planes.
38+
- `internal/admin/` serves operational, topology, metrics, and management APIs for the Dashboard and operators.
39+
- `internal/gatewayapi/` contains Gateway API helper logic, validation, encoding, and supported feature declarations.
40+
- `internal/ir/` defines the internal routing and runtime model shared by translator and gRPC publication code.
41+
- `deploy/` contains Kubernetes manifests and overlays.
42+
- `gen/` contains generated protobuf code.
43+
44+
## Generated Code
45+
46+
Do not edit generated files under `gen/` by hand. Change the source `.proto` definitions in the sibling Proto repository and bring generated output into this repository only when the source change and generation command are clear.
47+
48+
## Translator Maintenance
49+
50+
The translator package is the highest-risk package in this repository. When changing it:
51+
52+
- Preserve Gateway API semantics for parent refs, route attachment, listener validity, backend refs, filters, and status conditions.
53+
- Preserve ReferenceGrant and namespace scoping rules for cross-namespace references.
54+
- Preserve BackendTLSPolicy, BackendLBPolicy, session persistence, AIService, TokenPolicy, and WasmPlugin precedence rules.
55+
- Prefer shared indexes and support-object loaders over ad hoc list scans.
56+
- Keep full rebuild and partial rebuild behavior aligned.
57+
- Add or update focused tests for route semantics, backend policy precedence, ReferenceGrant behavior, status summaries, partial rebuild paths, and IR shape changes.
58+
59+
## Documentation And Comments
60+
61+
Use English by default for documentation and code comments. Add localized text only when editing existing localized user-facing content.
62+
63+
## Acceptance
64+
65+
Every change needs a spec, plan, and strict acceptance criteria. Record exact verification commands and results before marking work complete.
66+
67+
For documentation-only changes in this repository, run at least:
68+
69+
- `go test ./internal/translator` when touching translator documentation.
70+
- `make test` unless the plan explicitly scopes a smaller command and records why.
71+
- A local README link/path check when rewriting `README.md`.
72+
- `git diff --check origin/main...HEAD`.
73+
74+
For behavior changes, add focused tests first and then run all affected package checks.

‎README.md‎

Lines changed: 85 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Nantian Gateway
22

33
<p align="center">
4-
<strong>A modern Kubernetes Gateway API implementation with split-plane architecture, built for production.</strong>
4+
<strong>A Kubernetes Gateway API control plane for split-plane ingress, API routing, and AI gateway workloads.</strong>
55
</p>
66

77
<p align="center">
@@ -11,82 +11,40 @@
1111
<a href="https://nantian.dev"><img src="https://img.shields.io/badge/docs-nantian.dev-7c3aed" alt="Docs"></a>
1212
</p>
1313

14-
> 📖 [中文](README.zh-CN.md)
14+
> [Chinese README](README.zh-CN.md)
1515
16-
---
16+
## What Is Nantian Gateway?
1717

18-
## What is Nantian Gateway?
18+
Nantian Gateway is a Kubernetes Gateway API implementation with a Go control plane and a Rust data plane. This repository contains the control plane: it watches Gateway API resources, translates them into internal routing state, serves operational and admin APIs, and publishes runtime snapshots to data planes over gRPC/xDS.
1919

20-
Nantian Gateway is a [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) implementation that handles ingress traffic, API routing, and AI gateway features — all using standard Kubernetes resources. No custom CRDs for routing. No proprietary config language. Just Gateway API.
20+
Use Nantian Gateway when you want standard Kubernetes Gateway API resources for ingress traffic, API routing, and AI gateway workloads without inventing a custom routing CRD or proprietary configuration language.
2121

22-
**If you've used nginx ingress or Envoy Gateway** — Nantian Gateway does the same job, but with a Go control plane and a Rust data plane, targeting full Gateway API v1.5.1 conformance with 55 supported features.
23-
24-
### Why Nantian Gateway?
25-
26-
| Problem | Nantian Gateway's answer |
27-
|---|---|
28-
| **Vendor lock-in** | Standard Gateway API — switch implementations without changing route definitions |
29-
| **Complex AI routing** | Built-in AI Gateway: multi-provider proxy, API keys, rate limiting, PII masking |
30-
| **Observability gaps** | Prometheus metrics, Grafana dashboards, and admin APIs out of the box |
31-
| **Performance at scale** | Rust data plane with xDS push — sub-millisecond config propagation |
32-
| **Custom logic** | Wasm plugin system for request/response hooks without rebuilding |
33-
34-
### Architecture at a Glance
22+
## Architecture
3523

36-
```
37-
Users / Clients
38-
│
39-
▼
40-
┌───────────┐
41-
│ Data Plane │ ◄── Rust proxy (HTTP, gRPC, UDP, TLS)
42-
│ (Rust) │ Handles live traffic
43-
└─────┬─────┘
44-
│ gRPC xDS (bidirectional stream)
45-
┌─────┴─────┐
46-
│ Control │ ◄── Go process
47-
│ Plane (Go) │ Watches Gateway API resources
48-
└─────┬─────┘ Translates → xDS config → pushes to data planes
49-
│
50-
┌─────┴─────┐
51-
│ Kubernetes │ Gateway, HTTPRoute, GRPCRoute, TLSRoute…
52-
│ API │
53-
└───────────┘
24+
```text
25+
Kubernetes API
26+
Gateway, HTTPRoute, GRPCRoute, TLSRoute, policies, Services, Secrets
27+
|
28+
v
29+
Go control plane (this repository)
30+
watch -> translate -> validate/status -> publish snapshots
31+
|
32+
| gRPC/xDS
33+
v
34+
Rust data plane
35+
HTTP, gRPC, TCP, UDP, TLS, AI gateway, and Wasm runtime traffic handling
36+
|
37+
v
38+
Backends and AI providers
5439
```
5540

56-
## Quick Start
41+
The control plane is designed to stay Kubernetes-native. Gateway API resources remain the source of truth. The Rust data plane consumes the translated runtime model and handles live traffic. Optional sibling projects provide the Helm chart, Dashboard, Website, and shared Proto contract.
5742

58-
Try it in 5 minutes with a local Kind cluster:
43+
## Install
5944

60-
```bash
61-
# Clone and deploy
62-
git clone https://github.com/nantian-gw/gateway.git
63-
cd gateway
45+
### Helm
6446

65-
# Start a Kind cluster with Nantian Gateway
66-
./test/e2e/smoke/run.sh
67-
```
68-
69-
Now create your first route:
70-
71-
```yaml
72-
apiVersion: gateway.networking.k8s.io/v1
73-
kind: HTTPRoute
74-
metadata:
75-
name: my-first-route
76-
spec:
77-
parentRefs:
78-
- name: nantian-gateway
79-
rules:
80-
- backendRefs:
81-
- name: my-service
82-
port: 8080
83-
```
84-
85-
For a complete walkthrough, see our [Getting Started guide](https://nantian.dev).
86-
87-
## Installation
88-
89-
### Helm (recommended for production)
47+
Helm is the recommended production installation path:
9048

9149
```bash
9250
helm repo add nantian-gw https://nantian-gw.github.io/helm-charts
@@ -95,128 +53,104 @@ helm install nantian-gw nantian-gw/nantian-gw \
9553
--create-namespace
9654
```
9755

98-
See [Helm chart documentation](https://github.com/nantian-gw/helm-charts) for custom values.
56+
See the [Helm chart repository](https://github.com/nantian-gw/helm-charts) for values, schema validation, and chart release details.
9957

10058
### Kustomize
10159

60+
Repository-local Kubernetes overlays are available under `deploy/kubernetes/`:
61+
10262
```bash
10363
kubectl apply -k deploy/kubernetes/overlays/production
10464
```
10565

10666
### Requirements
10767

108-
- Kubernetes 1.28+
109-
- [Gateway API CRDs](https://gateway-api.sigs.k8s.io/guides/#installing-gateway-api) installed on the cluster
68+
- Kubernetes 1.28 or newer.
69+
- Gateway API CRDs installed on the cluster.
70+
- A compatible Nantian data plane deployment.
11071

111-
## Key Features
72+
## Verify Locally
11273

113-
### Gateway API v1.5.1 Support
74+
For a local smoke test with Kind, run:
11475

115-
| Route Type | Status |
116-
|---|---|
117-
| HTTPRoute | ✅ Fully supported |
118-
| GRPCRoute | ✅ Fully supported |
119-
| TCPRoute | ✅ Fully supported |
120-
| UDPRoute | ✅ Fully supported |
121-
| TLSRoute | ✅ Passthrough |
122-
| BackendTLSPolicy | ✅ Fully supported |
123-
| BackendLBPolicy | ✅ Fully supported |
124-
125-
See the [full conformance report](reports/conformance/) for details.
126-
127-
### AI Gateway
128-
129-
Route AI traffic to multiple providers with a single endpoint:
130-
131-
- **Unified proxy** — OpenAI, Anthropic, Ollama behind one endpoint
132-
- **Token counting & rate limiting** — per-user, per-model quotas
133-
- **API key management** — centralized credential storage via Kubernetes Secrets
134-
- **PII masking** — automatic detection and redaction of sensitive fields
135-
- **A/B testing** — split traffic across models or providers
136-
137-
```yaml
138-
apiVersion: gateway.nantian.dev/v1alpha1
139-
kind: AIBackend
140-
metadata:
141-
name: my-llm
142-
spec:
143-
provider: openai
144-
model: gpt-4o
145-
apiKeySecretRef:
146-
name: openai-credentials
76+
```bash
77+
make e2e-smoke
14778
```
14879

149-
→ [AI Gateway documentation](docs/design/ai-gateway/)
80+
The smoke test creates a local cluster, installs required resources, deploys the gateway stack, and verifies a basic route path. For Gateway API conformance testing, run:
15081

151-
### Wasm Plugin System
82+
```bash
83+
make conformance
84+
```
15285

153-
Extend the data plane with custom logic without rebuilding or restarting:
86+
Both commands require local Kubernetes tooling such as Kind, kubectl, and kustomize.
15487

155-
- **Request/response hooks** — modify headers, bodies, or status codes
156-
- **wasmtime runtime** — fast, sandboxed execution
157-
- **Write in any language** — compile to Wasm from Rust, Go, C, or JavaScript
88+
## Gateway API Support
15889

159-
→ [Wasm plugin documentation](docs/design/wasm/)
90+
Nantian Gateway targets Gateway API v1.5.1. Use the conformance package and supported-feature declarations as the local source of truth for exact support status:
16091

161-
### Observability
92+
- [Conformance tests](conformance/)
93+
- [Gateway API support tool](cmd/gateway-api-support/)
94+
- [Supported feature declarations](internal/gatewayapi/supported_features.go)
16295

163-
- **Prometheus metrics** — request rate, latency, errors by route and backend
164-
- **Grafana dashboards** — pre-built templates in `deploy/observability/`
165-
- **Admin API** — runtime configuration, health checks, diagnostic endpoints
96+
The public documentation site also summarizes supported scenarios at [nantian.dev](https://nantian.dev).
16697

167-
## Documentation
98+
## AI Gateway And Extensions
16899

169-
| You want to… | Go here |
170-
|---|---|
171-
| Get started | [Getting Started](https://nantian.dev/getting-started/quick-start/) |
172-
| Install in production | [Installation Guide](https://nantian.dev/installation/helm/) |
173-
| Understand concepts | [Concepts](https://nantian.dev/concepts/) |
174-
| Set up AI Gateway | [AI Gateway docs](docs/design/ai-gateway/) |
175-
| Write a Wasm plugin | [Wasm SDK docs](docs/design/wasm/) |
176-
| See what's supported | [Gateway API Support Matrix](docs/gateway-api-support.md) |
177-
| Contribute | [CONTRIBUTING.md](CONTRIBUTING.md) |
178-
| Report a bug | [Issues](https://github.com/nantian-gw/gateway/issues) |
179-
| See the roadmap | [ROADMAP.md](ROADMAP.md) |
180-
181-
[Full documentation site →](https://nantian.dev)
100+
Nantian Gateway can route AI traffic and extension behavior through Kubernetes-managed configuration:
182101

183-
## Development
102+
- AI provider routing and model selection.
103+
- Token policy and quota-oriented extension resources.
104+
- WasmPlugin resources for sandboxed request and response extension hooks.
105+
- Backend TLS and load-balancing policies for upstream behavior.
184106

185-
```bash
186-
# Prerequisites: Go 1.26+, Rust (for data plane), Kind (for e2e)
107+
Related control-plane source areas:
187108

188-
# Generate protobuf
189-
make proto
109+
- `internal/gatewayapiexperimental/`
110+
- `internal/translator/ai_service.go`
111+
- `internal/translator/token_policy.go`
112+
- `internal/translator/wasm_plugin.go`
190113

191-
# Build
192-
make build
114+
## Operations And Observability
193115

194-
# Run unit tests
195-
make test
116+
The gateway control plane exposes operational surfaces for production use:
196117

197-
# Run benchmarks
198-
make benchmarks
118+
- Admin APIs for health, topology, runtime state, and diagnostics.
119+
- Prometheus metrics for controller, admin, and gRPC publication paths.
120+
- Deployment overlays under `deploy/kubernetes/`.
121+
- Observability assets under `deploy/observability/`.
122+
- Generated admin API contracts under `docs/contracts/`.
199123

200-
# Run conformance suite (requires Kind)
124+
## Development
125+
126+
Common commands:
127+
128+
```bash
129+
make build
130+
make test
131+
go test ./internal/translator
132+
make e2e-smoke
201133
make conformance
202134
```
203135

204-
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow.
136+
Protobuf source and generation workflow live in the sibling Proto repository. Generated protobuf code under `gen/` should not be edited by hand.
137+
138+
For agent-specific repository guidance, see [AGENTS.md](AGENTS.md). For community expectations, see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
205139

206-
## Related Projects
140+
## Related Repositories
207141

208-
| Project | Description |
142+
| Repository | Purpose |
209143
|---|---|
210-
| [nantian-gw/dataplane](https://github.com/nantian-gw/dataplane) | Rust data plane (HTTP proxy, xDS client, AI gateway, Wasm runtime) |
211-
| [nantian-gw/dashboard](https://github.com/nantian-gw/dashboard) | Next.js admin console |
212-
| [nantian-gw/website](https://github.com/nantian-gw/website) | Documentation site ([nantian.dev](https://nantian.dev)) |
213-
| [nantian-gw/helm-charts](https://github.com/nantian-gw/helm-charts) | Helm charts for Kubernetes deployment |
214-
| [nantian-gw/proto](https://github.com/nantian-gw/proto) | Shared protobuf contract |
144+
| [nantian-gw/dataplane](https://github.com/nantian-gw/dataplane) | Rust data plane for traffic handling and xDS consumption. |
145+
| [nantian-gw/helm-charts](https://github.com/nantian-gw/helm-charts) | Helm chart for Kubernetes installation. |
146+
| [nantian-gw/dashboard](https://github.com/nantian-gw/dashboard) | Next.js admin console. |
147+
| [nantian-gw/website](https://github.com/nantian-gw/website) | Documentation site at [nantian.dev](https://nantian.dev). |
148+
| [nantian-gw/proto](https://github.com/nantian-gw/proto) | Shared protobuf contract. |
215149

216150
## Project Status
217151

218-
Nantian Gateway is under active development. It has a working control plane, data plane, admin interfaces, Kind smoke tests, conformance workflows, and production deployment overlays. It is not yet an officially recognized Gateway API implementation.
152+
Nantian Gateway is under active development. It has a working control plane, data plane integration, admin APIs, Kind smoke tests, conformance workflows, and production deployment overlays. It is not yet an officially recognized Gateway API implementation.
219153

220154
## License
221155

222-
Apache 2.0 — see [LICENSE](LICENSE).
156+
Apache 2.0. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)