From 2cea0575320f8040f1b7d53f2ac595523473939c Mon Sep 17 00:00:00 2001 From: Varsha Prasad Narsing Date: Mon, 11 May 2026 22:10:29 -0700 Subject: [PATCH] docs: update README and docs for dev preview readiness - Rewrite README to cover AgentRuntime, AuthBridge webhook, MLflow integration, and all operator controllers - Update architecture diagram to show full component set - Fix broken doc links (signature verification, identity binding) - Add all docs to the documentation table (AuthBridge, controller-webhook interaction, MLflow, client registration) - Add AgentRuntime Quick Start alongside manual label path - Fix protocol label requirement: clarify that Deployments need protocol.kagenti.io/a2a for AgentCard auto-creation - Remove hardcoded Helm chart version Assisted-By: Claude (Anthropic AI) Signed-off-by: Varsha Prasad Narsing --- README.md | 200 +++++++++++++----- kagenti-operator/GETTING_STARTED.md | 7 +- .../agent_v1alpha1_agentruntime_basic.yaml | 2 + kagenti-operator/docs/architecture.md | 2 +- 4 files changed, 150 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index c3a682b5..6e4ba92e 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![License](https://img.shields.io/github/license/kagenti/kagenti-operator)](LICENSE) ![Contributors](https://img.shields.io/github/contributors/kagenti/kagenti-operator) -**Kagenti Operator** is a Kubernetes operator that automates the deployment, discovery, and security of AI agents in Kubernetes clusters. +**Kagenti Operator** is a Kubernetes operator that automates the deployment, discovery, and security of AI agents in Kubernetes clusters. It provides workload identity (SPIFFE), mutual authentication (OAuth2/Keycloak), agent-to-agent trust (A2A signature verification), and observability (MLflow tracing) — all declaratively managed through Custom Resources. ## Overview @@ -11,72 +11,89 @@ The Kagenti Operator manages the following Custom Resource Definitions (CRDs): | Resource | Purpose | |----------|---------| +| **[AgentRuntime](./kagenti-operator/docs/api-reference.md#agentruntime)** | Enrolls a workload into the Kagenti platform — applies labels, triggers sidecar injection, and configures identity and observability | | **[AgentCard](./kagenti-operator/docs/api-reference.md#agentcard)** | Discovers, indexes, and verifies agent metadata for Kubernetes-native agent discovery | -Agents are deployed as standard Kubernetes **Deployments** or **StatefulSets** with the `kagenti.io/type: agent` label. The operator automatically discovers labeled workloads and creates AgentCard resources for them. - ### Key Features -- **Agent Deployment** — Deploy agents using standard Kubernetes Deployments or StatefulSets with the `kagenti.io/type: agent` label -- **Dynamic Agent Discovery** — Automatic indexing of agent metadata via the A2A protocol -- **Signature Verification** — JWS-based cryptographic verification of agent cards (RSA, ECDSA) -- **Identity Binding** — SPIFFE-based workload identity binding with allowlist enforcement +- **Declarative Agent Enrollment** — Create an `AgentRuntime` CR pointing to a clean Deployment; the operator applies labels, injects sidecars, and manages rolling updates automatically +- **AuthBridge Sidecar Injection** — Mutating webhook injects envoy-proxy (mTLS + token exchange), SPIFFE helper (workload identity), and client registration (Keycloak OAuth2) sidecars +- **Dynamic Agent Discovery** — Automatic indexing of agent metadata via the [A2A protocol](https://a2a-protocol.org/) +- **Signature Verification** — JWS-based cryptographic verification of agent cards (RSA, ECDSA) using SPIRE X.509 trust bundles +- **Identity Binding** — SPIFFE-based workload identity binding with trust domain validation - **Network Policy Enforcement** — Automatic NetworkPolicy creation based on signature verification status -- **Flexible Configuration** — Complete control over pod specifications, service ports, and environment variables +- **MLflow Integration** — Auto-discovers MLflow instances, creates per-agent experiments, and configures tracing - **Multi-Framework Support** — Works with LangGraph, CrewAI, AG2, and any A2A-compatible framework ## Architecture ```mermaid -graph TD; - subgraph Kubernetes - direction TB - style Kubernetes fill:#f0f4ff,stroke:#8faad7,stroke-width:2px - - User[User/App] - style User fill:#ffecb3,stroke:#ffa000 - - Workload["Deployment / StatefulSet\n(with kagenti labels)"] - style Workload fill:#e1f5fe,stroke:#039be5 - - User -->|Creates| Workload - - AgentCardSync[AgentCard Sync Controller] - style AgentCardSync fill:#ffe0b2,stroke:#fb8c00 - - AgentCardController[AgentCard Controller] - style AgentCardController fill:#ffe0b2,stroke:#fb8c00 - - NetworkPolicyController[NetworkPolicy Controller] - style NetworkPolicyController fill:#ffe0b2,stroke:#fb8c00 +graph TB + subgraph "User Interaction" + User[User/Developer] + User -->|Creates| Deployment[Deployment/StatefulSet] + User -->|Creates| RuntimeCR[AgentRuntime CR] + end - AgentPod[Agent Pod] - style AgentPod fill:#c8e6c9,stroke:#66bb6a + subgraph "Kagenti Operator" + ValidationWebhook[Validating Webhooks] + InjectionWebhook[AuthBridge Mutating Webhook] + RuntimeController[AgentRuntime Controller] + SyncController[AgentCard Sync Controller] + CardController[AgentCard Controller] + NPController[NetworkPolicy Controller] + MLflowController[MLflow Controller] - AgentCardCRD["AgentCard CR"] - style AgentCardCRD fill:#e1f5fe,stroke:#039be5 + RuntimeCR -->|Validates| ValidationWebhook + end - NetworkPolicy["NetworkPolicy"] - style NetworkPolicy fill:#ffcdd2,stroke:#e57373 + subgraph "Config Sources" + ClusterCM[Cluster Defaults ConfigMaps] + NsCM[Namespace Defaults ConfigMap] + end - Workload -->|Deploys| AgentPod - Workload -->|Watches| AgentCardSync - AgentCardSync -->|Auto-creates| AgentCardCRD - AgentCardCRD -->|Reconciles| AgentCardController - AgentCardController -->|Fetches /.well-known/agent-card.json| AgentPod - AgentCardController -->|Verifies signatures & identity| AgentCardCRD - AgentCardCRD -->|Reconciles| NetworkPolicyController - NetworkPolicyController -->|Creates| NetworkPolicy + subgraph "Runtime" + Pod[Agent Pods] + Deployment -->|Creates| Pod + InjectionWebhook -->|Injects sidecars at CREATE| Pod + CardController -->|Fetches agent card from| Pod end + + RuntimeController -->|Applies labels + config-hash| Deployment + RuntimeController -->|Reads defaults| ClusterCM + RuntimeController -->|Reads defaults| NsCM + RuntimeController -->|Watches| RuntimeCR + + SyncController -->|Watches| Deployment + SyncController -->|Auto-creates| AgentCardCR[AgentCard CR] + CardController -->|Reconciles| AgentCardCR + NPController -->|Creates| NetworkPolicy[NetworkPolicy] + MLflowController -->|Discovers MLflow, injects env vars| Deployment + + style User fill:#ffecb3 + style RuntimeCR fill:#e1f5fe + style AgentCardCR fill:#e1f5fe + style ValidationWebhook fill:#fff3e0 + style InjectionWebhook fill:#fff3e0 + style RuntimeController fill:#ffe0b2 + style SyncController fill:#ffe0b2 + style CardController fill:#ffe0b2 + style NPController fill:#ffe0b2 + style MLflowController fill:#ffe0b2 + style Deployment fill:#d1c4e9 + style Pod fill:#c8e6c9 ``` -The operator runs three controllers: +The operator runs the following controllers and webhooks: -| Controller | Purpose | -|------------|---------| -| **AgentCard Sync Controller** | Watches Deployments/StatefulSets with agent labels and auto-creates AgentCard resources | -| **AgentCard Controller** | Fetches agent card data from running agents, verifies signatures, evaluates identity binding | +| Component | Purpose | +|-----------|---------| +| **AgentRuntime Controller** | Reconciles AgentRuntime CRs — applies labels, computes config hash, triggers rolling updates on config change | +| **AuthBridge Webhook** | Mutating webhook that injects sidecar containers (envoy-proxy, SPIFFE helper, client registration) into agent/tool Pods | +| **AgentCard Sync Controller** | Watches labeled Deployments/StatefulSets and auto-creates AgentCard resources | +| **AgentCard Controller** | Fetches agent card data from running agents, verifies JWS signatures, evaluates identity binding | | **NetworkPolicy Controller** | Creates permissive or restrictive NetworkPolicies based on signature verification status | +| **MLflow Controller** | Auto-discovers MLflow instances, creates experiments per agent, injects tracking env vars and RBAC | ## Quick Start @@ -108,16 +125,20 @@ By default the script installs the released operator version pinned as a chart d # Install the operator using OCI chart helm install kagenti-operator \ oci://ghcr.io/kagenti/kagenti-operator/kagenti-operator-chart \ - --version 0.2.0-alpha.19 \ --namespace kagenti-system \ --create-namespace ``` ### Deploy Your First Agent -Deploy an agent as a standard Kubernetes Deployment with the required `kagenti.io/type: agent` label: +There are two ways to deploy agents. The **AgentRuntime** approach is recommended — it keeps your workload manifests clean and provides identity, auth, and observability configuration. + +#### Option 1: AgentRuntime (Recommended) + +Deploy a clean Deployment and create an AgentRuntime CR: ```bash +# Deploy the agent workload kubectl apply -f - < **Note:** The `Agent` Custom Resource is deprecated and will be removed in a future release. @@ -51,9 +51,9 @@ The Kagenti Operator discovers, indexes, and secures AI agents deployed in Kuber ## Deploy an Agent with AgentRuntime (Recommended) -The AgentRuntime approach keeps your workload manifests clean — no kagenti labels required. The controller applies labels, computes a config hash, and triggers the AuthBridge webhook to inject sidecars. +The AgentRuntime approach requires only a `protocol.kagenti.io/a2a` label on your Deployment — the controller applies `kagenti.io/type`, computes a config hash, and triggers the AuthBridge webhook to inject sidecars. The protocol label tells the AgentCard sync controller which protocol the agent speaks, enabling automatic discovery. -### Step 1: Deploy a Clean Deployment +### Step 1: Deploy a Deployment with Protocol Label ```yaml kubectl apply -f - <