Skip to content

Agent Mesh

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.md
index 1421f478..8a5c35f0 100644
--- a/site/content/docs/development/_index.md
+++ b/site/content/docs/development/_index.md
@@ -88,10 +88,10 @@ make test-e2e-container
For 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 infrastructure
make kind-local-node # enroll a locally-built ./bin/sam-node into the mesh
make kind-e2e-mesh # run the end-to-end discover-and-call check
make 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.md
index 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/`, driven
make 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:
```bash
make 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 session
make 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-node
make 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.md
index 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 free
Google 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.md
index 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
```
## Configuration
diff --git a/site/content/docs/user/kubernetes-deployment.md b/site/content/docs/user/kubernetes-deployment.md
index 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/mai
To 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
```yaml
apiVersion: v1