Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
charts: add sam-node chart for deploying a node with an optional service sidecar
Tomas Tormo2565d52e9425
diff --git a/Makefile b/Makefileindex 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-testhelm-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: verifyverify:diff --git a/charts/sam-node/Chart.yaml b/charts/sam-node/Chart.yamlnew file mode 100644index 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.mdnew file mode 100644index 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.tplnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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: {}