Skip to content

Agent Mesh

charts: add sam-node chart for deploying a node with an optional service sidecar

Tomas Tormo2565d52e9425
diff --git a/Makefile b/Makefile
index 3a7d45cd..f35eb713 100644
--- a/Makefile
+++ b/Makefile
@@ -196,7 +196,7 @@ helm-lint:
exit 1; \
fi; \
fi; \
- $$HELM_BIN lint ./charts/sam-mesh
+ $$HELM_BIN lint ./charts/sam-mesh && $$HELM_BIN lint ./charts/sam-node --set controlPlaneUrl=http://required-for-lint:8080
# render the chart to bin/chart/ for inspection; pass extra flags via ARGS, e.g. ARGS="--set gateway.enabled=true"
.PHONY: helm-template
@@ -211,7 +211,7 @@ lint: fmt helm-lint
.PHONY: helm-test
helm-test:
@helm plugin list 2>/dev/null | grep -q '^unittest' || helm plugin install https://github.com/helm-unittest/helm-unittest
- helm unittest charts/sam-mesh
+ helm unittest charts/sam-mesh charts/sam-node
.PHONY: verify
verify:
diff --git a/charts/sam-node/Chart.yaml b/charts/sam-node/Chart.yaml
new file mode 100644
index 00000000..0180780a
--- /dev/null
+++ b/charts/sam-node/Chart.yaml
@@ -0,0 +1,6 @@
+apiVersion: v2
+name: sam-node
+description: A Helm chart for deploying a SAM node, optionally hosting a service as a sidecar
+type: application
+version: 0.1.0
+appVersion: "1.0.0"
diff --git a/charts/sam-node/README.md b/charts/sam-node/README.md
new file mode 100644
index 00000000..13324ac3
--- /dev/null
+++ b/charts/sam-node/README.md
@@ -0,0 +1,67 @@
+# sam-node
+
+Deploys one SAM node into a Kubernetes cluster, optionally hosting a service
+as a sidecar container. The node authenticates to the control plane with a
+projected ServiceAccount token (Workload Identity Federation); the token's
+`audience` must be listed in the control plane's `allowedAudiences`.
+
+## Usage
+
+A bare node (a caller / mesh participant with no local service):
+
+```bash
+helm install my-node charts/sam-node \
+ --set controlPlaneUrl=http://sam-mesh-control-plane:8080
+```
+
+A node hosting an MCP service (see `development/examples/*/values.yaml` for
+complete, working examples):
+
+```yaml
+controlPlaneUrl: http://sam-mesh-control-plane:8080
+config:
+ version: v1alpha1
+ services:
+ - type: mcp
+ name: calculator
+ description: Simple math operations
+ target_url: http://127.0.0.1:7777/mcp
+service:
+ name: calc-mcp
+ image: calc-mcp:local
+```
+
+Values files stack: keep environment wiring (`controlPlaneUrl`, extra args)
+in a base file and the service description in its own, then pass both:
+`helm install calc charts/sam-node -f base.yaml -f calc/values.yaml`
+(later files win). The kind dev mesh ships such a base at
+`development/kind/sam-node.values.yaml`.
+
+The service container and the node share the pod's network, so `target_url`
+points at `127.0.0.1:<port>`. Services declared in `config.services` are
+advertised to the mesh via DHT and gossip; `config.attenuation` narrows what
+the node's credential permits. The config file is read once at node startup —
+the chart rolls the pods on config changes (checksum annotation).
+
+## Values
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `controlPlaneUrl` | — (required) | Control plane URL the node enrolls with |
+| `audience` | `sam-mesh-audience` | Projected token audience |
+| `apiToken` | `devtoken` | Bearer token for the node's local REST API |
+| `bindAddr` | `127.0.0.1:8080` | Node API bind address (loopback = pod-private) |
+| `extraArgs` | `[]` | Extra sam-node args |
+| `config` | empty services | Rendered verbatim as `sam-node.yaml` |
+| `service.image` | `""` | Service container image; empty = bare node |
+| `service.name/command/env/ports/resources` | — | Service container spec |
+| `image.repository/tag/pullPolicy` | `sam-node:local` | Node image |
+| `replicaCount` | `1` | Each replica enrolls as its own mesh node |
+
+## Dynamic registration (alternative to `config.services`)
+
+A running node also accepts `POST /sam/service/register` on its API
+(`bindAddr`, bearer `apiToken`) with a JSON body
+`{"service":{"type":"mcp","name":"x","description":"…"},"targetUrl":"http://…"}`.
+Registrations are in-memory: after a node restart the registrar must
+re-register. Static `config.services` entries need no such care.
diff --git a/charts/sam-node/templates/_helpers.tpl b/charts/sam-node/templates/_helpers.tpl
new file mode 100644
index 00000000..791aa7fe
--- /dev/null
+++ b/charts/sam-node/templates/_helpers.tpl
@@ -0,0 +1,49 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "sam-node.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name, truncated to the 63-char DNS limit.
+*/}}
+{{- define "sam-node.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "sam-node.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "sam-node.labels" -}}
+helm.sh/chart: {{ include "sam-node.chart" . }}
+{{ include "sam-node.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "sam-node.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "sam-node.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
diff --git a/charts/sam-node/templates/configmap.yaml b/charts/sam-node/templates/configmap.yaml
new file mode 100644
index 00000000..6c7fde64
--- /dev/null
+++ b/charts/sam-node/templates/configmap.yaml
@@ -0,0 +1,9 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: {{ include "sam-node.fullname" . }}-config
+ labels:
+ {{- include "sam-node.labels" . | nindent 4 }}
+data:
+ sam-node.yaml: |
+ {{- .Values.config | toYaml | nindent 4 }}
diff --git a/charts/sam-node/templates/deployment.yaml b/charts/sam-node/templates/deployment.yaml
new file mode 100644
index 00000000..488d7778
--- /dev/null
+++ b/charts/sam-node/templates/deployment.yaml
@@ -0,0 +1,91 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: {{ include "sam-node.fullname" . }}
+ labels:
+ {{- include "sam-node.labels" . | nindent 4 }}
+spec:
+ replicas: {{ .Values.replicaCount }}
+ selector:
+ matchLabels:
+ {{- include "sam-node.selectorLabels" . | nindent 6 }}
+ template:
+ metadata:
+ labels:
+ {{- include "sam-node.selectorLabels" . | nindent 8 }}
+ annotations:
+ # A config-only change must roll the pods: the node reads its config
+ # file once at startup and never reloads it.
+ checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+ spec:
+ serviceAccountName: {{ include "sam-node.fullname" . }}
+ containers:
+ - name: sam-node
+ image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+ imagePullPolicy: {{ .Values.image.pullPolicy }}
+ env:
+ - name: SAM_API_TOKEN
+ value: {{ .Values.apiToken | quote }}
+ args:
+ - "run"
+ - "--config=/etc/sam/sam-node.yaml"
+ - "--control-plane={{ required "controlPlaneUrl is required" .Values.controlPlaneUrl }}"
+ - "--jwt-path=/var/run/secrets/tokens/sam-token"
+ - "--bind-addr={{ .Values.bindAddr }}"
+ {{- range .Values.extraArgs }}
+ - {{ . | quote }}
+ {{- end }}
+ {{- with .Values.resources }}
+ resources:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ volumeMounts:
+ - name: config
+ mountPath: /etc/sam
+ - name: sam-token
+ mountPath: /var/run/secrets/tokens
+ readOnly: true
+ {{- if .Values.service.image }}
+ - name: {{ .Values.service.name }}
+ image: {{ .Values.service.image | quote }}
+ imagePullPolicy: {{ .Values.image.pullPolicy }}
+ {{- with .Values.service.command }}
+ command:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.service.env }}
+ env:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.service.ports }}
+ ports:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.service.resources }}
+ resources:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- end }}
+ {{- with .Values.nodeSelector }}
+ nodeSelector:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.tolerations }}
+ tolerations:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.affinity }}
+ affinity:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ volumes:
+ - name: config
+ configMap:
+ name: {{ include "sam-node.fullname" . }}-config
+ - name: sam-token
+ projected:
+ sources:
+ - serviceAccountToken:
+ path: sam-token
+ expirationSeconds: 3600
+ audience: {{ .Values.audience | quote }}
diff --git a/charts/sam-node/templates/serviceaccount.yaml b/charts/sam-node/templates/serviceaccount.yaml
new file mode 100644
index 00000000..25a24ff8
--- /dev/null
+++ b/charts/sam-node/templates/serviceaccount.yaml
@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+ name: {{ include "sam-node.fullname" . }}
+ labels:
+ {{- include "sam-node.labels" . | nindent 4 }}
diff --git a/charts/sam-node/tests/deployment_test.yaml b/charts/sam-node/tests/deployment_test.yaml
new file mode 100644
index 00000000..e087db27
--- /dev/null
+++ b/charts/sam-node/tests/deployment_test.yaml
@@ -0,0 +1,59 @@
+suite: sam-node deployment
+templates:
+ # configmap.yaml must be loaded for the checksum/config include to resolve
+ - templates/deployment.yaml
+ - templates/configmap.yaml
+tests:
+ - it: fails without controlPlaneUrl
+ template: templates/deployment.yaml
+ asserts:
+ - failedTemplate: {}
+
+ - it: renders a bare node with one container
+ template: templates/deployment.yaml
+ set:
+ controlPlaneUrl: http://sam-mesh-control-plane:8080
+ asserts:
+ - equal:
+ path: spec.template.spec.containers[0].name
+ value: sam-node
+ - lengthEqual:
+ path: spec.template.spec.containers
+ count: 1
+ - contains:
+ path: spec.template.spec.containers[0].args
+ content: "--control-plane=http://sam-mesh-control-plane:8080"
+ - contains:
+ path: spec.template.spec.containers[0].args
+ content: "--bind-addr=127.0.0.1:8080"
+ - equal:
+ path: spec.template.spec.volumes[1].projected.sources[0].serviceAccountToken.audience
+ value: sam-mesh-audience
+
+ - it: renders the service container when service.image is set
+ template: templates/deployment.yaml
+ set:
+ controlPlaneUrl: http://sam-mesh-control-plane:8080
+ service:
+ name: calc-mcp
+ image: calc-mcp:local
+ asserts:
+ - lengthEqual:
+ path: spec.template.spec.containers
+ count: 2
+ - equal:
+ path: spec.template.spec.containers[1].name
+ value: calc-mcp
+ - equal:
+ path: spec.template.spec.containers[1].image
+ value: calc-mcp:local
+
+ - it: appends extraArgs
+ template: templates/deployment.yaml
+ set:
+ controlPlaneUrl: http://sam-mesh-control-plane:8080
+ extraArgs: ["--discovery-interval=200ms"]
+ asserts:
+ - contains:
+ path: spec.template.spec.containers[0].args
+ content: "--discovery-interval=200ms"
diff --git a/charts/sam-node/values.yaml b/charts/sam-node/values.yaml
new file mode 100644
index 00000000..9c66715a
--- /dev/null
+++ b/charts/sam-node/values.yaml
@@ -0,0 +1,50 @@
+image:
+ repository: sam-node
+ tag: local
+ pullPolicy: IfNotPresent
+
+replicaCount: 1
+
+# Required: control plane URL the node enrolls with,
+# e.g. http://sam-mesh-control-plane:8080
+controlPlaneUrl: ""
+
+# Audience of the projected ServiceAccount token; must be one of the control
+# plane's allowedAudiences.
+audience: sam-mesh-audience
+
+# Bearer token protecting the node's local REST API.
+apiToken: devtoken
+
+# Address the node API binds inside the pod. Loopback keeps the API
+# pod-private; set 0.0.0.0:8080 to expose it on the pod IP.
+bindAddr: "127.0.0.1:8080"
+
+# Extra sam-node args, e.g. ["--discovery-interval=200ms"].
+extraArgs: []
+
+# Rendered verbatim as the node's sam-node.yaml: static services the node
+# advertises, and local attenuation.
+config:
+ version: v1alpha1
+ attenuation:
+ policies: []
+ checks: []
+ rules: []
+ services: []
+
+# Optional service container next to the node; they share localhost, so
+# config.services target_url entries point at 127.0.0.1:<port>.
+# Rendered only when image is non-empty.
+service:
+ name: service
+ image: ""
+ command: []
+ env: []
+ ports: []
+ resources: {}
+
+resources: {}
+nodeSelector: {}
+tolerations: []
+affinity: {}