Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: kind mesh deploys infra only; services ship via charts/sam-node
Tomas Tormo087eef99a52c
diff --git a/site/content/docs/development/_index.md b/site/content/docs/development/_index.mdindex 1421f478..8a5c35f0 100644--- a/site/content/docs/development/_index.md+++ b/site/content/docs/development/_index.md@@ -88,10 +88,10 @@ make test-e2e-containerFor end-to-end integration testing in a local Kubernetes environment, the repository provides `make` targets that stand up a complete mesh in `kind` with a single command:```bash-make kind-up # create the sam-kind cluster, build+load images, deploy control-plane + router + nodes+make kind-up # create the sam-kind cluster, build+load images, deploy the sam infrastructuremake kind-local-node # enroll a locally-built ./bin/sam-node into the meshmake kind-e2e-mesh # run the end-to-end discover-and-call checkmake kind-down # tear the cluster down```-`make kind-up` builds the `sam-control-plane:local`, `sam-router:local`, and `sam-node:local` images, creates a `sam-kind` cluster, and deploys the control-plane and router plus the nodes declared in `development/kind/mesh-config.yaml`. See the [Kubernetes Deployment and Local Testing Guide](kubernetes-deployment/#1-local-testing-with-kind) for details.+`make kind-up` builds the `sam-control-plane:local`, `sam-router:local`, `sam-node:local` and `sam-console:local` images, creates a `sam-kind` cluster, and deploys the control plane, router, console and Dex — no sam-nodes. Deploy services with `charts/sam-node`; see the [Kubernetes Deployment and Local Testing Guide](kubernetes-deployment/#1-local-testing-with-kind) for details.diff --git a/site/content/docs/development/kubernetes-deployment.md b/site/content/docs/development/kubernetes-deployment.mdindex 9f36f6ac..e6077e3b 100644--- a/site/content/docs/development/kubernetes-deployment.md+++ b/site/content/docs/development/kubernetes-deployment.md@@ -11,7 +11,7 @@ This guide explains how to deploy the SAM control plane and router in a Kubernet## 1. Local Testing with Kind-The repository ships a one-command local mesh under `development/kind/`, driven by `make` targets. This is the fastest way to get a running control plane, router and a few nodes on your machine.+The repository ships a one-command local mesh under `development/kind/`, driven by `make` targets. This is the fastest way to get a running control plane, router and console on your machine — ready for you to deploy services onto.### Automated Mesh (Recommended)@@ -19,10 +19,17 @@ The repository ships a one-command local mesh under `development/kind/`, drivenmake kind-up```-This creates a `sam-kind` cluster (one control-plane plus three workers — one labeled `sam-role: control-plane`, and one each for `node-a` and `node-b`), builds the `sam-control-plane:local`, `sam-router:local`, and `sam-node:local` images, loads them into the cluster, and deploys:+This creates a `sam-kind` cluster (one control-plane plus two workers — one+labeled `sam-role: control-plane` for the router), builds the+`sam-control-plane:local`, `sam-router:local`, `sam-node:local` and+`sam-console:local` images, loads them into the cluster, and deploys:- The **control plane**, configured to trust the cluster's own OIDC issuer.-- Two **nodes** declared in `development/kind/mesh-config.yaml` (`node-a` and `node-b`), both **bare** by default — assign services to suit what you're testing.+- The **console**.+- **Dex**.+- The **router**.+- **No sam-nodes.** The mesh comes up empty; put services on it with the+ `charts/sam-node` chart (next section) or enroll a local node.In-cluster nodes authenticate to the control plane via **Workload Identity Federation** (projected ServiceAccount tokens), so no static secrets or mock OIDC provider are needed.@@ -33,7 +40,7 @@ The mesh is exposed through Gateway API LoadBalancer addresses, so there are no- **Dex** on its own address, deployed from `development/kind/dex.yaml` rather than the chart — Dex is an independent component the chart no longer bundles.- The **router** at its own node's IP on port 4501, TCP **and** QUIC, announced from `status.hostIP`.-Once everything is up, `make kind-up` opens a tmux session with live per-pod logs (control plane, router and each node in its own pane). Manage the mesh with:+Once everything is up, `make kind-up` opens a tmux session with live per-pod logs (control plane and router, each in its own pane). Manage the mesh with:```bashmake kind-up ARGS=-s # bring the mesh up without attaching the log view@@ -41,65 +48,62 @@ make kind-logs # (re)attach the live-logs tmux sessionmake kind-down # delete the sam-kind cluster and stop cloud-provider-kind```-### Mesh Layout (`mesh-config.yaml`)+### Deploying a Service-The nodes that make up the dev mesh are declared in `development/kind/mesh-config.yaml`. Each entry maps a node to an optional service:+A service is any backend a node advertises to the mesh (`type: mcp` or+`type: inference`). In Kubernetes a service ships as a **`charts/sam-node`+release**: one pod holding your service container and a `sam-node` sidecar+that advertises it. The repository ships ready-made examples under+`development/examples/`; each is a `Dockerfile` plus a `values.yaml`+describing only the service — kind-wide wiring (control plane URL, fast+discovery) lives once in `development/kind/sam-node.values.yaml` and is+stacked underneath with a second `-f`.++Deploy one (calc-mcp) into the running kind mesh:++```bash+docker build -t calc-mcp:local development/examples/calc-mcp+kind load docker-image --name sam-kind calc-mcp:local+helm --kube-context kind-sam-kind -n sam-kind install calc-mcp charts/sam-node \+ -f development/kind/sam-node.values.yaml \+ -f development/examples/calc-mcp/values.yaml+```++To write your own service, copy an example folder: a backend listening on a+local port, a `Dockerfile`, and a `values.yaml` declaring the service —```yaml-# node -> service. A blank value means a bare node (no service, e.g. a caller).-# Set a value to host a service on that node; the value is a folder path under-# development/examples/, e.g:-# node-a: calc-mcp-# node-b: code-reviewer-pool/reviewer-# All nodes ship bare by default — assign services to suit what you're testing.-node-a:-node-b:+config:+ version: v1alpha1+ attenuation:+ policies: []+ services:+ - type: mcp+ name: my-service+ description: What it does+ target_url: http://127.0.0.1:7779/mcp+service:+ name: my-mcp+ image: my-mcp:local```-- The key is the node's name. The cluster currently ships with a control plane and router plus these **two** agent nodes, both bare by default; each is pinned to a matching worker via the `sam-role` labels in `kind-config.yaml`.-- A **blank** value is a bare node — a `sam-node` with no local service, useful as a caller/consumer.-- A **non-blank** value is a folder name under `development/examples/`. That service is built and deployed as a **sidecar** next to the node, and the node is configured to advertise it to the mesh.--When a node has a service, `make kind-up` builds the service image from its `Dockerfile`, loads it into the cluster, and mounts the service's `sam-node-config.yaml` into the node. Because `make kind-up` only runs against a fresh cluster (it refuses if `sam-kind` already exists), **services are (re)deployed on cluster recreation** — after editing `mesh-config.yaml` or a service, run `make kind-down && make kind-up` to pick up the change.--### Adding and Testing a New Service--A service is any backend a node advertises to the mesh. Its kind is set by the `type` field in `sam-node-config.yaml`. SAM currently supports `mcp` (an MCP server) and `inference` (an LLM inference endpoint). The repository ships example MCP services under `development/examples/` (`calc-mcp`, `greeter-mcp`, `code-reviewer-pool/reviewer`, and `everything-mcp`) which are the easiest starting point. Using `calc-mcp` as a template:--1. **Create the service folder** `development/examples/my-mcp/` with:- - The service backend (e.g. `my_server.py`) listening on a local port, plus a `Dockerfile` and any `requirements.txt`.- - A `sam-node-config.yaml` declaring the service. Set `type` to the service kind and point `target_url` at the backend's local port:- ```yaml- version: "v1alpha1"- attenuation:- policies:- services:- - type: "mcp"- name: "my-service"- description: "What it does"- target_url: "http://127.0.0.1:7779/mcp"- ```- The sidecar and `sam-node` share the pod's network, so `target_url` is always `127.0.0.1:<port>`, where `<port>` matches the port your service listens on.--2. **Assign it to a node** in `mesh-config.yaml` — set the value on a free node slot (`node-a` or `node-b`):- ```yaml- node-a: my-mcp- ```- > [!NOTE]- > There are two node slots because `kind-config.yaml` defines two workers labeled `sam-role: node-a|node-b`. To host more than two services at once, add a matching labeled worker there too.+The service container and `sam-node` share the pod's network, so `target_url`+is always `127.0.0.1:<port>`. Iterate with `docker build … && kind load … &&+helm upgrade calc-mcp charts/sam-node -f … -f …` — the chart rolls the pods+on config changes. Remove a service with `helm uninstall`.-3. **Recreate the cluster** so the new service is built and deployed:- ```bash- make kind-down && make kind-up- ```+Discover and call it from another node — enroll a local node and use the MCP+client:-4. **Discover and call it** from another node — enroll a local node and use the MCP client:- ```bash- make kind-local-node- # in another shell:- ./bin/mcp-client -url http://127.0.0.1:9099/mcp -token devtoken -tool find_remote_tools -args '{}'- ```- `find_remote_tools` lists the discovered tools (e.g. `mcp://my-service/...`) and the peer hosting them; pass that `peer_id` and `tool_name` to `call_remote_tool` to invoke it.+```bash+make kind-local-node+# in another shell:+./bin/mcp-client -url http://127.0.0.1:9099/mcp -token devtoken -tool find_remote_tools -args '{}'+```++`find_remote_tools` lists the discovered tools (e.g. `mcp://my-service/...`)+and the peer hosting them; pass that `peer_id` and `tool_name` to+`call_remote_tool` to invoke it.### Enrolling a Local Node@@ -110,11 +114,9 @@ make build # produce ./bin/sam-nodemake kind-local-node```-This mints a bootstrap token through the control plane's `/admin` API and runs `./bin/sam-node` against the control plane's gateway address — the same credential and path a real external node uses — exposing its MCP API on `127.0.0.1:9099` with the API token `devtoken`. Extra flags pass through via `ARGS`, e.g. to host an example service:--```bash-make kind-local-node ARGS="--config development/examples/calc-mcp/sam-node-config.yaml"-```+This mints a bootstrap token through the control plane's `/admin` API and runs `./bin/sam-node` against the control plane's gateway address — the same credential and path a real external node uses — exposing its MCP API on `127.0.0.1:9099` with the API token `devtoken`. Extra flags pass through via `ARGS`, e.g. `make kind-local-node+ARGS="--config my-node.yaml"` to host a service from a local config file+(same schema as the `config:` block in a `charts/sam-node` values file).You can then drive it with the bundled MCP client:@@ -127,17 +129,11 @@ You can then drive it with the bundled MCP client:To verify the full discovery-and-call path against a freshly built mesh:```bash+make kind-up ARGS="-s"make kind-e2e-mesh```-This enrolls a local node, waits for it to discover `mcp://calculator/add`, calls `add(2, 3)`, and asserts the result is `5`. Because nodes ship bare by default, the check needs a `calc-mcp` service on the mesh — bring the mesh up with the bundled e2e layout, which pins it:--```bash-MESH_CONFIG=development/kind/mesh-config.e2e.yaml make kind-up ARGS="-s"-make kind-e2e-mesh-```--`MESH_CONFIG` overrides which layout `make kind-up` deploys (default: `mesh-config.yaml`); `mesh-config.e2e.yaml` assigns `calc-mcp` to `node-b`.+`kind-e2e-mesh` deploys `calc-mcp` as a `charts/sam-node` release, enrolls a local node, waits for it to discover `mcp://calculator/add`, calls `add(2, 3)`, and asserts the result is `5`.---diff --git a/site/content/docs/use-cases/gemini-buddy.md b/site/content/docs/use-cases/gemini-buddy.mdindex b309328b..b9a592dc 100644--- a/site/content/docs/use-cases/gemini-buddy.md+++ b/site/content/docs/use-cases/gemini-buddy.md@@ -79,20 +79,21 @@ The buddy shells out to the Gemini CLI, so set your API key on the API-key `ENV`line in `development/examples/gemini-buddy-mcp/Dockerfile` before building (a freeGoogle AI Studio key is fine for the demo).-### 2. Mesh layout+### 2. Bring the mesh up and deploy the buddy-Host the buddy on one node in `development/kind/mesh-config.yaml`:--```yaml-node-a: # bare node (orchestrator entry)-node-b: gemini-buddy-mcp # the buddy+```bash+make build # builds ./bin/sam-node (once)+make kind-up # control plane + router (no sam-nodes yet)+docker build -t gemini-buddy-mcp:local development/examples/gemini-buddy-mcp+kind load docker-image --name sam-kind gemini-buddy-mcp:local+helm --kube-context kind-sam-kind -n sam-kind install gemini-buddy charts/sam-node \+ -f development/kind/sam-node.values.yaml \+ -f development/examples/gemini-buddy-mcp/values.yaml```-### 3. Bring the mesh up and start a local orchestrator node+### 3. Start a local orchestrator node```bash-make build # builds ./bin/sam-node (once)-make kind-up # control plane + router + buddy (node-b)make kind-local-node # local sam-node enrolled in the mesh — LEAVE RUNNING```diff --git a/site/content/docs/use-cases/warm-agent-pool.md b/site/content/docs/use-cases/warm-agent-pool.mdindex f191bd7e..38102ec9 100644--- a/site/content/docs/use-cases/warm-agent-pool.md+++ b/site/content/docs/use-cases/warm-agent-pool.md@@ -106,39 +106,33 @@ The reviewer workers shell out to an LLM, so set your API key on the API-key`ENV` line in `development/examples/code-reviewer-pool/reviewer/Dockerfile`before building (a free key is fine for the demo).-### 2. Mesh layout--This use case needs five node slots, and the cluster ships with two (`node-a`-and `node-b`). Add the three missing workers to-`development/kind/kind-config.yaml` first:--```yaml- - role: worker- labels:- sam-role: node-c- - role: worker- labels:- sam-role: node-d- - role: worker- labels:- sam-role: node-e+### 2. Bring the mesh up and deploy the pool++```bash+make build # builds ./bin/sam-node (once)+make kind-up # control plane + router (no sam-nodes yet)```-Then write this layout into `development/kind/mesh-config.yaml`:+Then build the two images and deploy the pool as `charts/sam-node` releases —+three reviewer replicas (each replica enrolls as its own mesh node, so the+pool is three same-named `code-reviewer` services) and one manager:-```yaml-node-a: # bare node (orchestrator entry)-node-b: code-reviewer-pool/reviewer # worker-node-c: code-reviewer-pool/reviewer # worker-node-d: code-reviewer-pool/reviewer # worker-node-e: code-reviewer-pool/manager # manager+```bash+docker build -t reviewer:local development/examples/code-reviewer-pool/reviewer+docker build -t pool-manager:local development/examples/code-reviewer-pool/manager+kind load docker-image --name sam-kind reviewer:local pool-manager:local++helm --kube-context kind-sam-kind -n sam-kind install reviewers charts/sam-node \+ -f development/kind/sam-node.values.yaml \+ -f development/examples/code-reviewer-pool/reviewer/values.yaml --set replicaCount=3+helm --kube-context kind-sam-kind -n sam-kind install manager charts/sam-node \+ -f development/kind/sam-node.values.yaml \+ -f development/examples/code-reviewer-pool/manager/values.yaml```-### 3. Bring the mesh up and start a local orchestrator node+### 3. Start a local orchestrator node```bash-make build # builds ./bin/sam-node (once)-make kind-up # control plane + router + reviewer pool (node-b/c/d) + manager (node-e)make kind-local-node # local sam-node enrolled in the mesh — LEAVE RUNNING```@@ -199,13 +193,13 @@ in the pool.### 6. Elasticity beat (add a worker mid-job)-Scale a reviewer down, start a larger job, then scale it back up — the manager-picks the new worker up on its next discovery pass and starts leasing it:+Scale the reviewer pool down, start a larger job, then scale it back up — the+manager picks the new worker up on its next discovery pass and starts leasing it:```bash-kubectl --context kind-sam-kind -n sam-kind scale deploy/node-d --replicas=0+kubectl --context kind-sam-kind -n sam-kind scale deploy/reviewers-sam-node --replicas=2# start a big job, then:-kubectl --context kind-sam-kind -n sam-kind scale deploy/node-d --replicas=1+kubectl --context kind-sam-kind -n sam-kind scale deploy/reviewers-sam-node --replicas=3```## Configurationdiff --git a/site/content/docs/user/kubernetes-deployment.md b/site/content/docs/user/kubernetes-deployment.mdindex 55c54f60..68c8fba1 100644--- a/site/content/docs/user/kubernetes-deployment.md+++ b/site/content/docs/user/kubernetes-deployment.md@@ -245,6 +245,12 @@ Refer to [dns-sync-cronjob-template.yaml](https://github.com/google/sam/blob/maiTo secure nodes without distributing static passwords, configure nodes to authenticate via **ServiceAccount projected tokens** (Workload Identity Federation).+> [!TIP]+> The repository ships this pattern as a Helm chart: `charts/sam-node`+> renders the ServiceAccount, config ConfigMap and Deployment below from a+> small values file (see the chart's README). The manifests that follow show+> what it produces.+### 1. Create a ServiceAccount```yamlapiVersion: v1