Skip to content

Agent Mesh

docs: describe the gateway-fronted kind mesh

Tomas Tormo7672f211cdf4
diff --git a/site/content/docs/development/kubernetes-deployment.md b/site/content/docs/development/kubernetes-deployment.md
index 19f682ee..9f36f6ac 100644
--- a/site/content/docs/development/kubernetes-deployment.md
+++ b/site/content/docs/development/kubernetes-deployment.md
@@ -2,7 +2,7 @@
title: "Kubernetes Deployment and Local Testing Guide"
linkTitle: "Kubernetes Deployment and Local Testing Guide"
---
-This guide explains how to deploy the SAM control plane and router in a Kubernetes cluster and how to test it locally with `kind` — using the bundled `make kind-*` targets for a one-command mesh, or a manual setup with `cloud-provider-kind`.
+This guide explains how to deploy the SAM control plane and router in a Kubernetes cluster and how to test it locally with `kind` — using the bundled `make kind-*` targets for a one-command mesh, or a manual setup. Both paths need `cloud-provider-kind`.
> [!TIP]
> This guide focuses on local development sandboxing. For production-grade Kubernetes deployments (GKE, EKS, AKS), see the [Production Kubernetes Deployment](../../user/kubernetes-deployment/) guide.
@@ -19,19 +19,26 @@ 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 workers for the control plane, router, and `node-a` through `node-e`), 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 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:
- The **control plane**, configured to trust the cluster's own OIDC issuer.
-- Five **nodes** declared in `development/kind/mesh-config.yaml` (`node-a` through `node-e`), all **bare** by default — assign services to suit what you're testing.
+- 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.
-Nodes authenticate to the control plane via **Workload Identity Federation** (projected ServiceAccount tokens), so no static secrets or mock OIDC provider are needed. The control plane is exposed to the host on `127.0.0.1:9090` (HTTP enroll) and `127.0.0.1:4001` (libp2p) via a NodePort and the cluster's `extraPortMappings` — `cloud-provider-kind` is not required.
+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.
+
+The mesh is exposed through Gateway API LoadBalancer addresses, so there are no port-forwards and no `extraPortMappings`. `run.sh` runs **`cloud-provider-kind`** as a container (a hard prerequisite — it needs the docker socket) to serve those addresses, and prints them when the mesh is up:
+
+- The **control plane** on its own address, routing the 8 exact enrollment paths, plus a dev-only `/admin` route.
+- The **console** at `/console/` on that same address, shaped like the production deployment: `/console` 302s to `/console/`, and a `URLRewrite` filter strips the prefix before the console sees the request.
+- **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:
```bash
make kind-up ARGS=-s # bring the mesh up without attaching the log view
make kind-logs # (re)attach the live-logs tmux session
-make kind-down # delete the sam-kind cluster
+make kind-down # delete the sam-kind cluster and stop cloud-provider-kind
```
### Mesh Layout (`mesh-config.yaml`)
@@ -40,17 +47,16 @@ The nodes that make up the dev mesh are declared in `development/kind/mesh-confi
```yaml
# node -> service. A blank value means a bare node (no service, e.g. a caller).
-# The service value is a folder path under development/examples/, e.g:
-# node-b: calc-mcp
-# node-c: code-reviewer-pool/reviewer
+# 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:
-node-c:
-node-d:
-node-e:
```
-- The key is the node's name. The cluster currently ships with a control plane and router plus these **five** agent nodes, all bare by default; each is pinned to a matching worker via the `sam-role` labels in `kind-config.yaml`.
+- 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.
@@ -75,12 +81,12 @@ A service is any backend a node advertises to the mesh. Its kind is set by the `
```
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 any free node slot (`node-a` through `node-e`):
+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 five node slots because `kind-config.yaml` defines five workers labeled `sam-role: node-a|node-b|node-c|node-d|node-e`. To host more than five services at once, add a matching labeled worker there too.
+ > 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.
3. **Recreate the cluster** so the new service is built and deployed:
```bash
@@ -104,7 +110,7 @@ make build # produce ./bin/sam-node
make kind-local-node
```
-This mints a ServiceAccount token and runs `./bin/sam-node` against the control plane at `127.0.0.1:9090`, 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:
+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"
diff --git a/site/content/docs/use-cases/gemini-buddy.md b/site/content/docs/use-cases/gemini-buddy.md
index dbb8abed..b309328b 100644
--- a/site/content/docs/use-cases/gemini-buddy.md
+++ b/site/content/docs/use-cases/gemini-buddy.md
@@ -86,9 +86,6 @@ 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
-node-c:
-node-d:
-node-e:
```
### 3. Bring the mesh up and start a local orchestrator node
diff --git a/site/content/docs/use-cases/warm-agent-pool.md b/site/content/docs/use-cases/warm-agent-pool.md
index 0f9461e0..f191bd7e 100644
--- a/site/content/docs/use-cases/warm-agent-pool.md
+++ b/site/content/docs/use-cases/warm-agent-pool.md
@@ -108,7 +108,23 @@ before building (a free key is fine for the demo).
### 2. Mesh layout
-The layout ships in `development/kind/mesh-config.yaml`:
+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
+```
+
+Then write this layout into `development/kind/mesh-config.yaml`:
```yaml
node-a: # bare node (orchestrator entry)