Skip to content

Agent Mesh

docs, tests: one policy shape everywhere, and drop the flag that no longer exists

Antonio Ojea83db1d5dcda2
diff --git a/site/content/docs/development/policy.md b/site/content/docs/development/policy.md
index dfb3ad6e..1bc4ff82 100644
--- a/site/content/docs/development/policy.md
+++ b/site/content/docs/development/policy.md
@@ -3,7 +3,7 @@ title: "SAM Policy & Authorization Reference"
linkTitle: "SAM Policy & Authorization Reference"
---
SAM uses a decentralized authorization model powered by [Biscuit](https://www.biscuitsec.org/).
-The `sam-control-plane` authenticates users via OIDC and injects **Facts** into their token based on `policies.yaml`. The `sam-node` operates offline, evaluating the token against baseline rules and optional local attenuation policies.
+The `sam-control-plane` authenticates users via OIDC and injects **Facts** into their token based on the mesh policy held in its database. The `sam-node` operates offline, evaluating the token against baseline rules and optional local attenuation policies.
> [!IMPORTANT]
> **Default-Deny Security Posture**
diff --git a/site/content/docs/manifests/sam-control-plane.yaml b/site/content/docs/manifests/sam-control-plane.yaml
index 02a816e7..ca6bebf6 100644
--- a/site/content/docs/manifests/sam-control-plane.yaml
+++ b/site/content/docs/manifests/sam-control-plane.yaml
@@ -19,6 +19,8 @@ metadata:
type: Opaque
stringData:
SAM_OIDC_ISSUER: "http://mock-oidc:18080"
+ # Authenticates the policy admin API. Replace before using this outside a demo.
+ SAM_ADMIN_TOKEN: "replace-me-with-a-generated-token"
---
apiVersion: apps/v1
kind: Deployment
@@ -46,7 +48,6 @@ spec:
- "--db-dsn=/data/control-plane.db"
- "--issuer=$(SAM_OIDC_ISSUER)"
- "--allowed-audiences=sam-mesh-audience,sam-control-plane-audience"
- - "--policy-file=/etc/sam/policies/policies.yaml"
- "--insecure-skip-tls-verify"
ports:
- containerPort: 8080
@@ -57,16 +58,15 @@ spec:
secretKeyRef:
name: sam-control-plane-secret
key: SAM_OIDC_ISSUER
+ - name: SAM_ADMIN_TOKEN
+ valueFrom:
+ secretKeyRef:
+ name: sam-control-plane-secret
+ key: SAM_ADMIN_TOKEN
volumeMounts:
- - name: policies-volume
- mountPath: /etc/sam/policies
- readOnly: true
- name: db-data
mountPath: /data
volumes:
- - name: policies-volume
- configMap:
- name: sam-control-plane-policies
- name: db-data
emptyDir: {}
---
@@ -84,19 +84,40 @@ spec:
targetPort: 8080
name: http
---
-apiVersion: v1
-kind: ConfigMap
+# The control plane starts default closed: it has no policy until one is posted.
+# Seed it over the admin API, which is the only way policy is ever set.
+apiVersion: batch/v1
+kind: Job
metadata:
- name: sam-control-plane-policies
-data:
- policies.yaml: |
- version: "v1alpha1"
- bindings:
- - members: ["sam:system:authenticated"]
- role: "public-mesh"
- roles:
- public-mesh:
- allowed_services:
- - "*"
- allowed_targets:
- - "*"
+ name: sam-control-plane-seed-policy
+spec:
+ template:
+ spec:
+ restartPolicy: OnFailure
+ containers:
+ - name: seed
+ image: curlimages/curl:8.6.0
+ env:
+ - name: SAM_ADMIN_TOKEN
+ valueFrom:
+ secretKeyRef:
+ name: sam-control-plane-secret
+ key: SAM_ADMIN_TOKEN
+ command:
+ - sh
+ - -c
+ - |
+ set -eu
+ until curl -sf -o /dev/null http://sam-control-plane:8080/healthz; do sleep 2; done
+ curl -sf -X POST \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer ${SAM_ADMIN_TOKEN}" \
+ -d '{
+ "roles": [
+ {"name": "public-mesh", "allowed_services": ["*"], "allowed_targets": ["*"]}
+ ],
+ "bindings": [
+ {"role": "public-mesh", "members": ["sam:system:authenticated"]}
+ ]
+ }' \
+ http://sam-control-plane:8080/policies
diff --git a/site/content/docs/user/_index.md b/site/content/docs/user/_index.md
index 95c804c9..4b37c9eb 100644
--- a/site/content/docs/user/_index.md
+++ b/site/content/docs/user/_index.md
@@ -9,7 +9,7 @@ Welcome to the User & Operator Guides. This section provides detailed documentat
### In This Section
1. **[Control Plane Configuration](control-plane-configuration/)**
- Learn how to configure the OIDC identity bridge, set up cryptographic private keys, enforce TLS/mTLS, and write custom security role policy mappings in `policies.yaml`.
+ Learn how to configure the OIDC identity bridge, set up cryptographic private keys, enforce TLS/mTLS, and write custom security role policy mappings.
2. **[Agent Usage & Connectivity](agent-usage/)**
Understand how nodes connect to the mesh via OIDC login, secure credentials, run local Model Context Protocol (MCP) servers, and expose secure remote tool access to agents (like Google Gemini and Claude).
diff --git a/site/content/docs/user/kubernetes-deployment.md b/site/content/docs/user/kubernetes-deployment.md
index 206b3b30..e4284e87 100644
--- a/site/content/docs/user/kubernetes-deployment.md
+++ b/site/content/docs/user/kubernetes-deployment.md
@@ -93,32 +93,7 @@ kubectl rollout status deployment/dex -n dex
The Control Plane verifies OIDC tokens and manages access policies. The Routers handle peer discovery and routing within the GossipSub mesh.
-### 1. Configure Access Control Policies (`policies.yaml`)
-Create a ConfigMap defining your global mesh access rules:
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
- name: sam-control-plane-policies
- namespace: sam
-data:
- policies.yaml: |
- version: "v1alpha1"
- bindings:
- - members: ["user:system:serviceaccount:sam-nodes:sam-node-sa"]
- role: "node-role"
- roles:
- node-role:
- allowed_services:
- - "*"
- allowed_targets:
- - "*"
-```
-```bash
-kubectl apply -f policies-configmap.yaml
-```
-
-### 2. Deploy SAM Control Plane
+### 1. Deploy SAM Control Plane
The Control Plane is stateless and can scale horizontally. It connects to a shared PostgreSQL database to persist active leases and rotated capability signing keys.
```yaml
@@ -146,20 +121,35 @@ spec:
- "--db-dsn=postgres://sam:password@sam-db-service:5432/sam_mesh?sslmode=disable"
- "--issuer=https://AUTH.YOUR-DOMAIN.COM"
- "--allowed-audiences=YOUR-CLIENT-AUDIENCE"
- - "--policy-file=/etc/sam/policies/policies.yaml"
ports:
- containerPort: 8080
name: http
- volumeMounts:
- - name: policies-volume
- mountPath: /etc/sam/policies
- readOnly: true
- volumes:
- - name: policies-volume
- configMap:
- name: sam-control-plane-policies
```
+### 2. Configure Access Control Policies
+The Control Plane starts **default closed**: until a policy is posted it authorizes
+nothing. Policy lives in the database, not on disk, so seed it through the admin
+API. Roles and bindings use the same schema everywhere, including the Mesh Policy
+editor in the console.
+
+```bash
+curl -sf -X POST \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer ${SAM_ADMIN_TOKEN}" \
+ -d '{
+ "roles": [
+ {"name": "node-role", "allowed_services": ["*"], "allowed_targets": ["*"]}
+ ],
+ "bindings": [
+ {"role": "node-role", "members": ["user:system:serviceaccount:sam-nodes:sam-node-sa"]}
+ ]
+ }' \
+ https://CONTROL-PLANE.YOUR-DOMAIN.COM/policies
+```
+
+The `sam-mesh` Helm chart runs this as a bootstrap Job for you; see
+`charts/sam-mesh/templates/bootstrap-job.yaml`.
+
### 3. Deploy SAM Router StatefulSet
The Router must be deployed as a StatefulSet to allocate a persistent volume for storing its libp2p identity key, ensuring a stable Peer ID across pod restarts.
diff --git a/site/content/docs/user/node-configuration.md b/site/content/docs/user/node-configuration.md
index f3e53ece..086f7b3a 100644
--- a/site/content/docs/user/node-configuration.md
+++ b/site/content/docs/user/node-configuration.md
@@ -56,7 +56,7 @@ The `services` array allows you to register endpoints that remote peers in the S
| Property | Description |
| :--- | :--- |
| `type` | The protocol protocol type. Supported values are `mcp` (Model Context Protocol), `inference`, or `a2a`. |
-| `name` | The unique name of the service (e.g., `git-helper`). This must exactly match the name authorized by the control plane's `policies.yaml` (e.g., `mcp://git-helper`). |
+| `name` | The unique name of the service (e.g., `git-helper`). This must exactly match the name authorized by the control plane's mesh policy (e.g., `mcp://git-helper`). |
| `description` | A human-readable description published to the mesh discovery catalogue. |
| `command` | *(For MCP)* The executable command array to spawn as a local subprocess (e.g. `["node", "index.js"]`). |
| `env` | *(For MCP)* Key-value environment variables passed to the subprocess. |
diff --git a/tests/integration/failover_test.go b/tests/integration/failover_test.go
index b5aae59b..d536cdc0 100644
--- a/tests/integration/failover_test.go
+++ b/tests/integration/failover_test.go
@@ -48,7 +48,7 @@ func TestFailoverUpdatesRelay(t *testing.T) {
policyFile := filepath.Join(tmpDir, "policies.yaml")
policyContent := `version: "v1alpha1"
bindings: []
-roles: {}
+roles: []
`
writePolicyWithRouter(t, policyFile, policyContent)
diff --git a/tests/integration/federation_test.go b/tests/integration/federation_test.go
index 0c2ea867..faba4507 100644
--- a/tests/integration/federation_test.go
+++ b/tests/integration/federation_test.go
@@ -49,8 +49,8 @@ bindings:
- members: ["user:mock-user"]
role: admin
roles:
- admin:
- allowed_services:
+ - name: admin
+ allowed_services:
- "mcp://*"
- "system://sam.catalog"
allowed_targets: ["*"]
diff --git a/tests/integration/local_policy_test.go b/tests/integration/local_policy_test.go
index 49633830..44300ba6 100644
--- a/tests/integration/local_policy_test.go
+++ b/tests/integration/local_policy_test.go
@@ -21,7 +21,7 @@ func TestLocalPolicyCanGrantPermissions(t *testing.T) {
controlPlanePolicyFile := filepath.Join(tmpDir, "policies.yaml")
controlPlanePolicyYAML := `version: "v1alpha1"
roles:
- none:
+ - name: none
allowed_services: []
allowed_targets: ["*"]
bindings:
@@ -165,7 +165,7 @@ func TestLocalPolicyCannotBypassControlPlaneTargetConstraint(t *testing.T) {
controlPlanePolicyFile := filepath.Join(tmpDir, "policies.yaml")
controlPlanePolicyYAML := `version: "v1alpha1"
roles:
- restricted-role:
+ - name: restricted-role
allowed_services: ["*"]
allowed_targets: ["group:admin-only"]
bindings:
diff --git a/tests/integration/mcp_local_tools_test.go b/tests/integration/mcp_local_tools_test.go
index 5898a725..1f50992b 100644
--- a/tests/integration/mcp_local_tools_test.go
+++ b/tests/integration/mcp_local_tools_test.go
@@ -34,7 +34,7 @@ func TestMCPLocalTools(t *testing.T) {
policyFile := filepath.Join(tmpDir, "policies.yaml")
policyContent := `version: "v1alpha1"
bindings: []
-roles: {}
+roles: []
`
if err := os.WriteFile(policyFile, []byte(policyContent), 0644); err != nil {
t.Fatal(err)
diff --git a/tests/integration/minimal_helpers_test.go b/tests/integration/minimal_helpers_test.go
index c6b3c540..f359ea1c 100644
--- a/tests/integration/minimal_helpers_test.go
+++ b/tests/integration/minimal_helpers_test.go
@@ -17,6 +17,7 @@ package integration_test
import (
"bytes"
"context"
+ "encoding/json"
"errors"
"fmt"
"os"
@@ -628,9 +629,9 @@ func writePolicyWithRouter(t *testing.T, path string, yamlContent string) {
// Replace empty markers first
content = strings.ReplaceAll(content, "bindings: []", "bindings:")
- content = strings.ReplaceAll(content, "roles: {}", "roles:")
+ content = strings.ReplaceAll(content, "roles: []", "roles:")
- routerRole := fmt.Sprintf(` %s:
+ routerRole := fmt.Sprintf(` - name: %s
allowed_services: []
allowed_targets: ["*"]`, api.RoleRouter)
routerBinding := fmt.Sprintf(` - role: %s
@@ -671,21 +672,10 @@ func waitForNodeOnline(t *testing.T, logPath string) {
}
}
-type testBinding struct {
- Role string `yaml:"role"`
- Members []string `yaml:"members"`
-}
-
-type testRolePolicy struct {
- AllowedTargets []string `yaml:"allowed_targets"`
- AllowedServices []string `yaml:"allowed_services"`
-}
-
-type testPolicyConfig struct {
- Bindings []testBinding `yaml:"bindings"`
- Roles map[string]testRolePolicy `yaml:"roles"`
-}
-
+// injectPolicyYAML posts a policy fixture through the same conversion the console
+// performs: YAML for readability, protojson on the wire. Going through JSON keeps
+// this helper free of any field list, so a new PolicyRole field needs no change
+// here and cannot be silently dropped.
func injectPolicyYAML(t *testing.T, port int, adminToken string, policyFile string) {
t.Helper()
@@ -694,37 +684,18 @@ func injectPolicyYAML(t *testing.T, port int, adminToken string, policyFile stri
t.Fatalf("failed to read policy file %s: %v", policyFile, err)
}
- var config testPolicyConfig
- if err := yaml.Unmarshal(data, &config); err != nil {
+ var doc interface{}
+ if err := yaml.Unmarshal(data, &doc); err != nil {
t.Fatalf("failed to unmarshal policy file %s: %v", policyFile, err)
}
- reqData := &api.PolicyConfigUpdateRequest{
- Roles: make([]*api.PolicyRole, 0, len(config.Roles)),
- Bindings: make([]*api.PolicyBinding, 0, len(config.Bindings)),
- }
-
- for name, role := range config.Roles {
- reqData.Roles = append(reqData.Roles, &api.PolicyRole{
- Name: name,
- AllowedServices: role.AllowedServices,
- AllowedTargets: role.AllowedTargets,
- })
- }
- for _, b := range config.Bindings {
- reqData.Bindings = append(reqData.Bindings, &api.PolicyBinding{
- Role: b.Role,
- Members: b.Members,
- })
- }
-
- protoData, err := proto.Marshal(reqData)
+ jsonData, err := json.Marshal(yamlToJSON(doc))
if err != nil {
- t.Fatalf("failed to marshal policy request: %v", err)
+ t.Fatalf("failed to convert policy file %s to JSON: %v", policyFile, err)
}
- req, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("http://127.0.0.1:%d/policies", port), bytes.NewReader(protoData))
- req.Header.Set("Content-Type", "application/x-protobuf")
+ req, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("http://127.0.0.1:%d/policies", port), bytes.NewReader(jsonData))
+ req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+adminToken)
client := &http.Client{Timeout: 5 * time.Second}
@@ -739,3 +710,23 @@ func injectPolicyYAML(t *testing.T, port int, adminToken string, policyFile stri
t.Fatalf("unexpected POST /policies status: %s (body: %s)", resp.Status, string(body))
}
}
+
+// yamlToJSON rewrites the map[interface{}]interface{} that yaml.v2 produces into
+// the map[string]interface{} encoding/json requires.
+func yamlToJSON(v interface{}) interface{} {
+ switch typed := v.(type) {
+ case map[interface{}]interface{}:
+ converted := make(map[string]interface{}, len(typed))
+ for key, value := range typed {
+ converted[fmt.Sprintf("%v", key)] = yamlToJSON(value)
+ }
+ return converted
+ case []interface{}:
+ for i, value := range typed {
+ typed[i] = yamlToJSON(value)
+ }
+ return typed
+ default:
+ return v
+ }
+}
diff --git a/tests/integration/multimaster_test.go b/tests/integration/multimaster_test.go
index 32e543c5..8d300ed1 100644
--- a/tests/integration/multimaster_test.go
+++ b/tests/integration/multimaster_test.go
@@ -45,7 +45,7 @@ func TestMultiMasterControlPlane(t *testing.T) {
policyFile := filepath.Join(tmpDir, "policies.yaml")
policyContent := `version: "v1alpha1"
bindings: []
-roles: {}
+roles: []
`
writePolicyWithRouter(t, policyFile, policyContent)
diff --git a/tests/integration/policy_permutations_test.go b/tests/integration/policy_permutations_test.go
index 742e2d7a..bf9267b7 100644
--- a/tests/integration/policy_permutations_test.go
+++ b/tests/integration/policy_permutations_test.go
@@ -79,22 +79,22 @@ func TestPolicyPermutations(t *testing.T) {
controlPlanePolicyFile := filepath.Join(tmpDir, "policies.yaml")
controlPlanePolicyYAML := `version: "v1alpha1"
roles:
- role-user:
+ - name: role-user
allowed_services: ["mcp://test-user"]
allowed_targets: ["user:bob-subject"]
- role-email:
+ - name: role-email
allowed_services: ["mcp://test-email"]
allowed_targets: ["email:[email protected]"]
- role-group:
+ - name: role-group
allowed_services: ["mcp://test-group"]
allowed_targets: ["group:compute"]
- role-node:
+ - name: role-node
allowed_services: ["mcp://test-node"]
allowed_targets: ["group:backend"]
- role-direct:
+ - name: role-direct
allowed_services: ["mcp://test-role"]
allowed_targets: ["group:compute"]
- admin:
+ - name: admin
allowed_services: ["*"]
allowed_targets: ["*:*"]
diff --git a/tests/integration/revocation_test.go b/tests/integration/revocation_test.go
index 0741dbe0..64db971e 100644
--- a/tests/integration/revocation_test.go
+++ b/tests/integration/revocation_test.go
@@ -50,7 +50,7 @@ bindings:
- members: ["user:mock-user"]
role: admin
roles:
- admin:
+ - name: admin
allowed_services: ["*"]
allowed_targets: ["*"]
`
diff --git a/tests/integration/rotation_test.go b/tests/integration/rotation_test.go
index 4707bc56..9a5a5a7e 100644
--- a/tests/integration/rotation_test.go
+++ b/tests/integration/rotation_test.go
@@ -45,7 +45,7 @@ bindings:
- members: ["user:mock-user"]
role: admin
roles:
- admin:
+ - name: admin
allowed_services: ["*"]
allowed_targets: ["*"]
`