Repo structure to host proposals, apis by HarshithaMS005 · Pull Request #119 · kubernetes-sigs/kube-agentic-networking

HarshithaMS005 · 2026-02-26T11:14:38Z

What type of PR is this?
/kind documentation

What this PR does / why we need it:
Added repo-structure documentation so contributors know where to find and add proposals, APIs, and docs. It adds docs/REPO_STRUCTURE.md, docs/api/README.md (API types, CRDs, clients, and relation to Gateway API), updates docs/proposals/README.md, and updates the main README with links to proposals, APIs, and the structure doc. This gives a single place to look for layout and contribution conventions.

Which issue(s) this PR fixes:
*Automatically closes linked issue when PR is merged.
Fixes #14

Does this PR introduce a user-facing change?:

NONE

netlify · 2026-02-26T11:14:43Z

✅ Deploy Preview for kube-agentic-networking ready!

Name	Link
🔨 Latest commit	`61007f0`
🔍 Latest deploy log	https://app.netlify.com/projects/kube-agentic-networking/deploys/69bd590f0b72820008571d13
😎 Deploy Preview	https://deploy-preview-119--kube-agentic-networking.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

k8s-ci-robot · 2026-02-26T11:14:44Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: HarshithaMS005
Once this PR has been reviewed and has the lgtm label, please assign david-martin for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2026-02-26T11:14:47Z

Hi @HarshithaMS005. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

LiorLieberman

Looks great to me overall, left a few small nits. Thank you @HarshithaMS005 !

LiorLieberman · 2026-02-27T00:09:51Z

/ok-to-test

chuangw6

Thank you @HarshithaMS005 for your contribution!

LiorLieberman · 2026-02-28T00:23:26Z

Thanks @HarshithaMS005! ping me when you had a chance to fix the comments and I will approve

HarshithaMS005 · 2026-03-01T17:30:47Z

@LiorLieberman I have made necessary changes as per the comments please review.

HarshithaMS005 · 2026-03-13T06:29:45Z

Hi @LiorLieberman , Can you please review this PR ? I have made necessary changes.

Signed-off-by: Harshitha MS <harshitha.ms@ibm.com>

LiorLieberman · 2026-03-24T00:23:16Z

/assign @robscott can you take a look?

k8s-ci-robot · 2026-03-24T00:23:25Z

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

robscott

Thanks for the great work on this @HarshithaMS005! While there's a lot of really great content in here, I'm worried that some of it will become stale since the project is still moving pretty quickly. Have recommended omitting some portions of this for now and revisiting as the project and APIs stabilize a bit more.

robscott · 2026-03-24T00:33:22Z

@@ -0,0 +1,60 @@
+# Repository structure


While I see the value in a doc like this, unfortunately I think it would go stale very quickly, especially with such a relatively young project. Mind leaving this out of this PR?

robscott · 2026-03-24T00:35:43Z

+| 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 |


I think this is very useful to have, but again very worried about it going stale. Maybe we could autogenerate the list here? For example, Gateway API autogenerates this list for GEPs, but it does admittedly rely on a GEP metadata file. We could potentially copy most of this over, but that may be better for a standalone PR since it could get quite large: https://github.com/kubernetes-sigs/gateway-api/blob/main/tools/geps/main.go.

robscott · 2026-03-24T00:36:21Z

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


Suggested change

This document describes the design of the project’s custom APIs and how they fit with the Gateway API.

This document describes the design of the project’s custom APIs and how they fit with the Gateway API. Note that this API is still in an early alpha state and could still change significantly.

robscott · 2026-03-24T00:36:53Z

+- **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).


Recommend removing this

robscott · 2026-03-24T00:37:27Z

@@ -0,0 +1,38 @@
+# API design


Is this intended to be part of the website? If so, I'd recommend putting it in the site-src directory

robscott · 2026-03-24T00:38:33Z

+
+## 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.


Recommend leaving out any implementation details here and just focusing on what the API does

Suggested change

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.

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

robscott · 2026-03-24T00:39:17Z

+
+## 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.


Suggested change

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.

An **XAccessPolicy** is an authorization policy: it defines *who* can access *what* for the backends it targets. It targets Gateways or XBackends via `targetRefs` and contains rules that describe allowed (or denied) sources and optional authorization (e.g. which tools or methods).

robscott · 2026-03-24T00:39:47Z

+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).


These details feel like they could become stale pretty quickly, recommend omitting.

robscott · 2026-03-24T00:40:06Z

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


These details could become stale pretty quickly, recommend omitting.

k8s-ci-robot · 2026-05-06T16:55:35Z

@HarshithaMS005: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-kube-agentic-networking-gateway-api-conformance	`61007f0`	link	true	`/test pull-kube-agentic-networking-gateway-api-conformance`

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

k8s-ci-robot added the kind/documentation Categorizes issue or PR as related to documentation. label Feb 26, 2026

k8s-ci-robot requested review from LiorLieberman and david-martin February 26, 2026 11:14

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Feb 26, 2026

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Feb 26, 2026

LiorLieberman reviewed Feb 27, 2026

View reviewed changes

Comment thread docs/api/README.md Outdated

Comment thread docs/api/README.md Outdated

Comment thread docs/api/README.md Outdated

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Feb 27, 2026

chuangw6 reviewed Feb 27, 2026

View reviewed changes

Comment thread docs/api/README.md Outdated

Comment thread docs/REPO_STRUCTURE.md Outdated

Comment thread README.md Outdated

Comment thread docs/REPO_STRUCTURE.md Outdated

Comment thread docs/api/README.md Outdated

Comment thread docs/REPO_STRUCTURE.md Outdated

HarshithaMS005 force-pushed the repo-structure branch from b1f44fb to 077bbe4 Compare March 1, 2026 17:29

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 19, 2026

Repo structure to host proposals, apis

61007f0

Signed-off-by: Harshitha MS <harshitha.ms@ibm.com>

HarshithaMS005 force-pushed the repo-structure branch from 077bbe4 to 61007f0 Compare March 20, 2026 14:26

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 20, 2026

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 24, 2026

robscott reviewed Mar 24, 2026

View reviewed changes

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


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


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

Conversation

HarshithaMS005 commented Feb 26, 2026

Uh oh!

netlify Bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kube-agentic-networking ready!

Uh oh!

k8s-ci-robot commented Feb 26, 2026

Uh oh!

k8s-ci-robot commented Feb 26, 2026

Uh oh!

LiorLieberman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

LiorLieberman commented Feb 27, 2026

Uh oh!

chuangw6 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

LiorLieberman commented Feb 28, 2026

Uh oh!

HarshithaMS005 commented Mar 1, 2026

Uh oh!

HarshithaMS005 commented Mar 13, 2026

Uh oh!

LiorLieberman commented Mar 24, 2026

Uh oh!

k8s-ci-robot commented Mar 24, 2026

Uh oh!

robscott left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify Bot commented Feb 26, 2026 •

edited

Loading