diff --git a/README.md b/README.md index 697887b6..a0e03982 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,10 @@ This subproject aims to deliver the following: You can find a quick start guide [here](https://kube-agentic-networking.sigs.k8s.io/guides/quickstart/). +## Repository structure + +See [docs/design/repo_structure.md](docs/design/repo_structure.md) for where to find and add proposals, APIs, documentation, and code. + ## Community, discussion, contribution, and support Our community meetings are held weekly on Thursday at 8:00 AM PT (Pacific Time) ([Convert to your timezone](http://www.thetimezoneconverter.com/?t=08%3A00&tz=PT%20%28Pacific%20Time%29)). diff --git a/docs/design/api.md b/docs/design/api.md new file mode 100644 index 00000000..f99fb20e --- /dev/null +++ b/docs/design/api.md @@ -0,0 +1,38 @@ +# API design + +This document describes the design of the project’s custom APIs and how they fit with the Gateway API. + +## Overview + +The project extends the [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) with two main custom resources: + +- **XBackend** — describes a backend (e.g. an MCP server) that HTTPRoutes can reference via BackendRef. +- **XAccessPolicy** — describes who can access what: it targets one or more XBackends and defines rules (sources and authorization) that the data plane enforces. + +Type definitions and generated code live under [`api/`](../../api/) and [`k8s/`](../../k8s/). For a short “what lives where” guide, see [repo_structure.md](repo_structure.md). + +## XBackend + +An **XBackend** represents a backend that agents or tools call into—for example, an MCP server. It is namespaced and is referenced by HTTPRoute `BackendRef`s (and by XAccessPolicy targetRefs). The controller and translator use XBackends to configure the data plane (e.g. clusters, RBAC) so that traffic to that backend is correctly routed and authorized. + +Key design points: + +- One XBackend per logical backend (e.g. one MCP server). +- Backend identity can be specified by Kubernetes Service name (in-cluster) or by hostname (external). +- The data plane uses XBackend to know where to send traffic and how to secure it (e.g. mTLS, path). + +## XAccessPolicy + +An **XAccessPolicy** is an authorization policy: it defines *who* can access *what* for the backends it targets. It targets XBackends via `targetRefs` and contains rules that describe allowed (or denied) sources and optional authorization (e.g. which tools or methods). The translator turns XAccessPolicy into data-plane configuration (e.g. Envoy RBAC) so that only allowed callers can reach the targeted backends. + +Key design points: + +- Targets one or more XBackends via `targetRefs`. +- Rules combine a source (e.g. service account, namespace) with optional authorization (e.g. allowed tools/methods). +- If no XAccessPolicy targets an XBackend, the data plane does not enforce RBAC for that backend (allow-all behaviour). If at least one XAccessPolicy targets it, the translated rules are enforced. + +## Relationship to Gateway API + +The project is built on top of the Gateway API and works with Gateway resources (Gateway, GatewayClass, and route types such as HTTPRoute; GRPCRoute may be supported later). Route resources can reference XBackends via BackendRef. **XBackend** and **XAccessPolicy** are custom resources that work with these Gateway resources and the data plane: BackendRef → XBackend, and XAccessPolicy → RBAC (or equivalent) for those backends. + +Proposals that introduce or change these APIs are under [docs/proposals/](../proposals/). diff --git a/docs/design/repo_structure.md b/docs/design/repo_structure.md new file mode 100644 index 00000000..b7f2d5d8 --- /dev/null +++ b/docs/design/repo_structure.md @@ -0,0 +1,60 @@ +# Repository structure + +This document describes where to find and where to add proposals, APIs, documentation, and code in this repo. + +## Top-level layout + +``` +├── api/ # API type definitions (Go structs) +├── cmd/ # Application entrypoints (e.g. controller main) +├── docs/ # Design docs, proposals, and repo documentation +├── hack/ # Build, codegen, and CI helpers +├── k8s/ # Generated clients, CRDs, and deploy manifests +├── pkg/ # Go packages (controller, translator, infra, etc.) +├── quickstart/ # Quickstart examples (agents, MCP server, policy) +├── site-src/ # MkDocs source for the published docs site +└── tests/ # Tests (CEL, CRD validation, examples) +``` + +## Proposals + +**Location:** [`docs/proposals/`](../proposals/) + +Design proposals and enhancement docs live here. Each proposal is a markdown file. + +- **Naming:** `NNNN-short-title.md` (e.g. `0008-ToolAuthAPI.md`). Use the 4-digit PR number once the PR exists; use a placeholder like `XXXX-my-proposal` during development. +- **Index and practices:** See [docs/design/proposals.md](proposals.md). + +## APIs + +**Type definitions:** [`api/`](../../api/) (Go) + +- `api/v0alpha0/` — Current API version (e.g. `backend_types.go`, `accesspolicy_types.go`). Run `make generate` after editing. + +**CRDs (manifests):** [`k8s/crds/`](../../k8s/crds/) + +- Installed YAML for XBackend, XAccessPolicy, etc. Generated from `api/`. + +**Generated clients:** [`k8s/client/`](../../k8s/client/) + +- Clientsets, listers, informers for the API types. Regenerated via project Makefile/codegen. + +For an overview of the APIs and design, see [api.md](api.md). + +## Documentation + +- **Design docs (this folder):** [`docs/design/`](.) — API design, repo structure, control plane, data plane. +- **Repo docs (proposals, api):** [`docs/`](../) — Markdown in the repo; good for GitHub browsing and linking from the docs site. +- **Published docs site:** [`site-src/`](../../site-src/) — MkDocs source; built output goes to `site/`. Add user-facing pages, guides, and links to proposals/APIs here. Config: [`mkdocs.yml`](../../mkdocs.yml). + +## Code + +- **Controller and business logic:** [`pkg/controller/`](../../pkg/controller/), [`pkg/translator/`](../../pkg/translator/) +- **Infrastructure (xDS, Envoy, pod certificate signer):** [`pkg/infra/`](../../pkg/infra/) +- **Constants and shared config:** [`pkg/constants/`](../../pkg/constants/) +- **Entrypoint:** [`cmd/`](../../cmd/) + +## Quickstart and examples + +- **Quickstart:** [`quickstart/`](../../quickstart/) — ADK agent, MCP server, and policy examples (e.g. `quickstart/policy/e2e.yaml`). +- **CRD examples (valid/invalid):** [`tests/crd/examples/`](../../tests/crd/examples/) diff --git a/docs/proposals/README.md b/docs/proposals/README.md index 6527cf22..cf2a32b0 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -1,5 +1,24 @@ -# Proposals Best Practices +# Proposals +Design proposals and enhancement documents for Kubernetes Agentic Networking. + +## Index + +| Proposal | Description | +|----------|-------------| +| [0008-ToolAuthAPI.md](0008-ToolAuthAPI.md) | Tool Authorization API | +| [0017-DynamicAuth.md](0017-DynamicAuth.md) | Dynamic Auth | +| [0059-AccessPolicyTargetRefs.md](0059-AccessPolicyTargetRefs.md) | AccessPolicy TargetRefs | ## Naming -The directory of the proposal should lead with a 4-digit PR number (will move to 5,6,... should our PR count get that high), followed by kebab-cased title. The PR number is not known until the PR is cut, so development can use a placeholder, ex. XXXX-my-proposal. PR number is used b/c it is unique & chronological, allowing the default ordering of proposals to follow the timeline of development. + +- Use a **4-digit number** (PR number when available) followed by a **kebab-cased title**: `NNNN-short-title.md`. +- Examples: `0008-ToolAuthAPI.md`, `0059-AccessPolicyTargetRefs.md`. +- While developing, you can use a placeholder (e.g. `XXXX-my-proposal.md`) and rename to the PR number when the PR is opened. +- The number gives a chronological order to proposals. + +## Adding a new proposal + +1. Create a new markdown file under `docs/proposals/` with the naming above. +2. Include: context, goals, design (API changes, behavior), and alternatives considered. +3. Add the new proposal to the **Index** table in this README.