Initial docs infra

rramkumar1 · rramkumar1 · commit 3f0542e23b6b · 2025-11-03T18:02:43.000Z
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,26 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+bin/*
+Dockerfile.cross
+# Test binary, built with `go test -c`
+*.test
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+# Go workspace file
+go.work
+go.work.sum
+# Kubernetes Generated files - skip generated files, except for vendored files
+!vendor/**/zz_generated.*
+# editor and IDE paraphernalia
+.idea
+.vscode
+*.swp
+*.swo
+*~
+
+# generated docs
+site
diff --git a/Makefile b/Makefile
@@ -0,0 +1,21 @@
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
+##@Docs
+
+.PHONY: build-docs
+build-docs:
+		docker build --pull -t kube-agentic-net/mkdocs hack/mkdocs/image
+			docker run --rm -v ${PWD}:/docs kube-agentic-net/mkdocs build
+
+.PHONY: build-docs-netlify
+build-docs-netlify:
+		pip install -r hack/mkdocs/image/requirements.txt
+			mkdocs build
+
+.PHONY: live-docs
+live-docs:
+		docker build -t kube-agentic-net/mkdocs hack/mkdocs/image
+			docker run --rm -it -p 3000:3000 -v ${PWD}:/docs kube-agentic-net/mkdocs
diff --git a/hack/mkdocs/image/Dockerfile b/hack/mkdocs/image/Dockerfile
@@ -0,0 +1,26 @@
+# Copyright 2019 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+FROM python:3.13-alpine
+
+COPY requirements.txt /requirements.txt
+RUN pip install -r /requirements.txt
+
+WORKDIR /docs
+
+EXPOSE 3000
+
+COPY entrypoint.sh /
+
+ENTRYPOINT ["/entrypoint.sh"]
diff --git a/hack/mkdocs/image/entrypoint.sh b/hack/mkdocs/image/entrypoint.sh
@@ -0,0 +1,28 @@
+#!/bin/sh
+
+# Copyright 2019 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o pipefail
+
+CMD=$1
+
+if [ "$CMD" == "build" ];
+then
+  mkdocs build
+  exit 0;
+fi
+
+mkdocs serve --dev-addr=0.0.0.0:3000 --livereload
diff --git a/hack/mkdocs/image/requirements.txt b/hack/mkdocs/image/requirements.txt
@@ -0,0 +1,25 @@
+# required for mkdocs-core
+jinja2~=3.0
+# mkdocs 2.4.1 requires Markdown < 3.4.0
+# https://github.com/kubernetes-sigs/gateway-api/pull/1671#issuecomment-1400586465
+markdown~=3.7
+mkdocs~=1.6
+mkdocs-material-extensions~=1.3
+pygments~=2.16
+pymdown-extensions~=10.2
+
+# Requirements for plugins
+babel~=2.10
+colorama~=0.4
+paginate~=0.5
+regex>=2022.4
+requests~=2.26
+
+# mkdocs + mkdocs plugins
+mkdocs==1.6.1
+mkdocs-awesome-pages-plugin==2.9.3
+mkdocs-macros-plugin==1.2.0
+mkdocs-material==9.5.36
+mkdocs-material-extensions==1.3.1
+mkdocs-redirects==1.2.1
+mkdocs-mermaid2-plugin==1.1.1
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,43 @@
+site_name: Kubernetes Agentic Networking
+repo_url: https://github.com/kubernetes-sigs/kube-agentic-networking
+repo_name: kubernetes-sigs/kube-agentic-networking
+site_dir: site
+docs_dir: site-src
+extra_css:
+  - stylesheets/extra.css
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/git-alt
+  logo: images/logo/logo-text-large-horizontal-white.png
+  favicon: images/k8s-favicon.png
+  features:
+    - search.highlight
+    - navigation.tabs
+    - navigation.top
+    - navigation.expand
+  palette:
+    primary: custom
+edit_uri: edit/main/site-src/
+plugins:
+  - search
+  - awesome-pages
+  - mermaid2
+markdown_extensions:
+  - admonition
+  - meta
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.snippets
+  - toc:
+      permalink: true
+  - tables
diff --git a/netlify.toml b/netlify.toml
@@ -0,0 +1,6 @@
+# netlify configuration
+[build]
+publish = "site"
+command = "make build-docs-netlify"
+# available here https://github.com/netlify/build-image/blob/focal/included_software.md#languages
+environment = { PYTHON_VERSION = "3.8" }
diff --git a/site-src/.mkdocs-exclude b/site-src/.mkdocs-exclude
@@ -0,0 +1,6 @@
+.mkdocs-exclude
+.nojekyll
+.placeholder
+search/search_index.json
+sitemap.xml.gz
+sitemap.xml
diff --git a/site-src/contributing/index.md b/site-src/contributing/index.md
@@ -0,0 +1,33 @@
+# How to Get Involved
+
+This page contains links to all of the meeting notes, design docs and related
+discussions around the APIs.
+
+## Bug Reports
+
+Bug reports should be filed as [GitHub Issues](https://github.com/kubernetes-sigs/kube-agentic-networking/issues/new) on this repo.
+
+## Communications
+
+* [#sig-network-gateway-api](https://kubernetes.slack.com/archives/C09P6KS6EQZ)
+
+## Meetings
+
+Gateway API community meetings happen every Thursday at 10am Pacific Time
+([convert to your
+timezone](https://dateful.com/time-zone-converter?t=10:00&tz=PT%20%28Pacific%20Time%29)).
+To receive an invite to this and other WG-Serving community meetings, join the
+[WG-Serving mailing
+list](https://groups.google.com/a/kubernetes.io/g/wg-serving).
+
+* [Zoom link](https://zoom.us/j/9955436256?pwd=Z2FQWU1jeDZkVC9RRTN4TlZyZTBHZz09) (passcode in [meeting notes](https://docs.google.com/document/d/1frfPE5L1sI3737rdQV04IcDGeOcGJj2ItjMg6z2SRH0/edit?tab=t.0#heading=h.jvz2pwvdpit0) doc)
+
+### Meeting Notes and Recordings
+
+Meeting agendas and notes are maintained in the [meeting
+notes](https://docs.google.com/document/d/1frfPE5L1sI3737rdQV04IcDGeOcGJj2ItjMg6z2SRH0/edit?tab=t.0#heading=h.jvz2pwvdpit0)
+doc. Feel free to add topics for discussion at an upcoming meeting.
+
+All meetings are recorded and automatically uploaded to the [WG-Serving meetings
+YouTube
+playlist](https://www.youtube.com/playlist?list=PL69nYSiGNLP2io2Gg92njBfh-DX9sk7O3).
diff --git a/site-src/index.md b/site-src/index.md
@@ -0,0 +1,51 @@
+# Introduction
+
+The continuous evolution of the AI ecosystem has led to the emergence of agent-based development, a paradigm in which autonomous AI agents execute intricate tasks. This transformation is fostering the development of "AI-first" protocols, such as the Model Context Protocol (MCP) and A2A, which diverge significantly from conventional protocols.
+
+Agents in a sense are microservices for AI. They are self-contained, autonomous units of work that can be composed to build complex applications. These agents, and the tools they use to perform their functions, are becoming ubiquitous. They can run anywhere: on-premises, in traditional hyperscaler cloud environments (like Kubernetes or serverless functions), on new cloud platforms (neoclouds), or across the public internet.
+
+This distributed nature, combined with the new communication patterns of "AI-first" protocols, introduces novel security and governance challenges. Unlike traditional REST APIs, these protocols require integration with AI safety and security models in addition to conventional security measures. This is because agents can act autonomously, potentially with significant impact. It is therefore essential for Kubernetes to provide a consistent API for a well-governed, secure, and auditable flow of communication:
+
+- From agents in Kubernetes to agents in the cluster and remote agents anywhere.
+
+- From agents running anywhere to agents in Kubernetes.
+
+- For agents in Kubernetes to access tools anywhere.
+
+## Goals
+
+This subproject aims to deliver the following:
+
+**Core Capabilities**
+
+-   Provide standardized APIs for secure, governed communication between agents, tools, and potentially LLMs across Kubernetes cluster boundaries (ingress, egress, and east-west traffic)
+
+-   Attempt to design APIs around user-facing goals (e.g., "Agent A can communicate with Tool B") rather than protocol-specific constructs, ensuring adaptability as new AI-first protocols emerge alongside MCP and A2A
+
+-   Enable protocol-aware networking capabilities where necessary (e.g., MCP tool-level authorization) while keeping core APIs protocol-agnostic and future-proof
+
+-   Establish agent identity and authentication mechanisms that allow agents to be uniquely identified and verified across network boundaries
+
+
+**Security & Governance**
+
+-   Define authorization policies that control which agents can communicate with other agents, tools, and LLMs at a granular level (e.g., specific MCP tool functions)
+
+-   Integrate AI safety and security extension points to support external authentication, authorization, and policy enforcement decisions
+
+-   Provide auditable traffic management capabilities (rate limiting, access controls) suitable for autonomous agent workloads
+
+
+**Ecosystem Integration**
+
+-   Maintain alignment and collaboration with Gateway API, Gateway Inference Extension, WG AI Gateway, and WG AI Integration
+
+-   Design APIs extensible enough for diverse implementations (service meshes, gateways, future architectures)
+
+## API Resources
+
+Check back soon for the initial API proposal!
+
+## Who is working on this project?
+
+TODO
