feat(helm): CLUSTER, PUBLISH_UNTAGGED and CONSUMER_GROUP env

CHANGELOG.md

@@ -8,6 +8,10 @@ Please choose versions by [Semantic Versioning](http://semver.org/).
 * MINOR version when you add functionality in a backwards-compatible manner, and
 * PATCH version when you make backwards-compatible bug fixes.
 
+## Unreleased
+
+- feat(helm): render optional cluster-routing env — `cluster` → `CLUSTER` on the singular executor, every `executors[]` entry and every controller; `publishUntagged` → `PUBLISH_UNTAGGED` on every controller (rendered whenever the key is set, so `false` renders); `executor.consumerGroup` / `executors[].consumerGroup` → `CONSUMER_GROUP` on that executor; chart 0.7.0→0.8.0. All three are absent by default, so an install that sets none of them renders the same manifests as before (only the `helm.sh/chart` label changes). Consumed by agent-task-controller >= v0.14.0 and agent-task-executor >= v0.19.0; older binaries ignore the env.
+
 ## v0.107.0
 - the `a2aWorkerController` Deployment now emits `INGRESS_DOMAIN` (from `ingressHost`) and `TLS_SECRET_NAME` (from `tlsSecretName`, empty allowed); the binary refuses to start on the k8s backend without both, so an enabled controller crashlooped with `backend "k8s" requires NAMESPACE, INGRESS_DOMAIN and TLS_SECRET_NAME`
 

helm/Chart.yaml

@@ -3,7 +3,7 @@ name: agent
 description: bborbe agent framework — event-driven, Kafka-based, K8s-native task platform (controller, executor, and example agents)
 type: application
 # Chart version — bumped on chart changes, independent of appVersion.
-version: 0.7.0
+version: 0.8.0
 # Default image tag for the framework components when values don't override.
 appVersion: "0.3.1"
 home: https://github.com/bborbe/agent

helm/README.md

@@ -96,6 +96,8 @@ agents: []
 | `keel.pollSchedule` | `@every 1m` | keel poll interval when enabled. |
 | `affinity` | `{}` | Node affinity object applied to controller/executor/recurring pods. Empty = none. |
 | `rolloutNonce` | `""` | Value of a `random` pod annotation to force a rollout. Empty = omit. |
+| `cluster` | `""` | Cluster name rendered as `CLUSTER` on every executor and every controller. Controllers publish only tasks whose `cluster:` frontmatter matches. Requires agent-task-controller ≥ v0.14.0 and agent-task-executor ≥ v0.19.0. Empty = nothing rendered. |
+| `publishUntagged` | unset | Rendered as `PUBLISH_UNTAGGED` (quoted `"true"`/`"false"`) on every controller **only when the key is set** — `false` is honoured, absent renders nothing. Set `false` on clusters that must run only explicitly tagged tasks (e.g. sun). Requires agent-task-controller ≥ v0.14.0. |
 
 ### executor
 
@@ -108,6 +110,7 @@ agents: []
 | `executor.topicPrefix` | `""` | Kafka topic prefix. Empty = unprefixed (per-stage-cluster / Octopus). Quant: `develop`/`master`. |
 | `executor.branch` | `""` | Stage label forwarded as `BRANCH`. |
 | `executor.taskGlob` | `""` | git-rest single-level glob selecting the vault task files the reconcile loop evaluates. Consumer-supplied — the chart asserts no vault folder layout; empty = no glob configured. |
+| `executor.consumerGroup` | `""` | Rendered as `CONSUMER_GROUP` on the executor. Gives each Kafka consumer its own consumer group (e.g. `agent-task-executor-sun`) so executors on different clusters do not share offsets. Empty = nothing rendered. |
 | `executor.sentry.proxy` | `""` | Sentry proxy URL (optional). |
 | `executor.sentry.dsn` | `""` | Sentry DSN; when set the chart creates the Secret. |
 | `executor.existingSecret` | `""` | Name of a pre-existing Secret with key `sentry-dsn`; when set the chart creates no Secret. |
@@ -138,6 +141,7 @@ default) the single legacy `agent-task-executor` Deployment renders unchanged.
 | `executors[].kafkaBrokers` | `executor.kafkaBrokers` | Kafka bootstrap brokers. Required when not inherited. |
 | `executors[].image.repository` / `image.tag` | `executor.image` | Image repo/tag; empty tag → chart `appVersion`. |
 | `executors[].logLevel` | `executor.logLevel` | Log verbosity. |
+| `executors[].consumerGroup` | `executor.consumerGroup` | Rendered as `CONSUMER_GROUP` on that executor; per-entry value wins, empty = nothing rendered. |
 | `executors[].sentry.proxy` | `executor.sentry.proxy` | Sentry proxy URL. |
 | `executors[].existingSecret` | `executor.existingSecret`, then shared `agent-task-executor` | Pre-existing Secret with key `sentry-dsn`. |
 | `executors[].podSecurityContext` / `securityContext` / `resources` | `executor.*` | Pod/container security contexts + resources. |

helm/templates/controller-statefulset.yaml

@@ -99,6 +99,14 @@ spec:
               value: "false"
             - name: AUTO_INJECT_TASK_IDENTIFIER
               value: {{ $c.autoInjectTaskIdentifier | quote }}
+            {{- with $.Values.cluster }}
+            - name: CLUSTER
+              value: {{ . | quote }}
+            {{- end }}
+            {{- if and (hasKey $.Values "publishUntagged") (kindIs "bool" $.Values.publishUntagged) }}
+            - name: PUBLISH_UNTAGGED
+              value: {{ $.Values.publishUntagged | quote }}
+            {{- end }}
             - name: NAMESPACE
               valueFrom:
                 fieldRef:

helm/templates/executor-deployment.yaml

@@ -104,6 +104,14 @@ spec:
               value: {{ .Values.executor.gitRestGatewaySecret | quote }}
             - name: TASK_GLOB
               value: {{ .Values.executor.taskGlob | quote }}
+            {{- with .Values.cluster }}
+            - name: CLUSTER
+              value: {{ . | quote }}
+            {{- end }}
+            {{- with .Values.executor.consumerGroup }}
+            - name: CONSUMER_GROUP
+              value: {{ . | quote }}
+            {{- end }}
           ports:
             - containerPort: 9090
               name: http
@@ -249,6 +257,14 @@ spec:
               value: {{ $e.gitRestGatewaySecret | default $.Values.executor.gitRestGatewaySecret | quote }}
             - name: TASK_GLOB
               value: {{ $e.taskGlob | default $.Values.executor.taskGlob | quote }}
+            {{- with $.Values.cluster }}
+            - name: CLUSTER
+              value: {{ . | quote }}
+            {{- end }}
+            {{- with ($e.consumerGroup | default $.Values.executor.consumerGroup) }}
+            - name: CONSUMER_GROUP
+              value: {{ . | quote }}
+            {{- end }}
           ports:
             - containerPort: 9090
               name: http

helm/values.yaml

@@ -43,6 +43,22 @@ rolloutNonce: ""
 sentry:
   proxy: ""
 
+# Cluster this release is installed on (e.g. nukedev, nukeprod, sun). When
+# non-empty it is rendered as the `CLUSTER` env on every executor and every
+# controller; controllers publish only tasks whose `cluster:` frontmatter
+# matches this value. Requires agent-task-controller >= v0.14.0 and
+# agent-task-executor >= v0.19.0. Empty (default) renders nothing.
+cluster: ""
+
+# publishUntagged: rendered as the `PUBLISH_UNTAGGED` env (quoted "true"/"false")
+# on every controller only when this key is SET — unset renders nothing and the
+# controller's own default applies. Set it to false on clusters that must run
+# only explicitly tagged tasks (e.g. sun), so tasks without a `cluster:`
+# frontmatter are not published there. Deliberately commented out: a default
+# here would make "unset" and false indistinguishable. Requires
+# agent-task-controller >= v0.14.0.
+# publishUntagged: false
+
 executor:
   enabled: true
   image:
@@ -88,6 +104,11 @@ executor:
   # reconcile loop evaluates. Consumer-supplied — the chart asserts no vault
   # folder layout. Empty = no glob configured.
   taskGlob: ""
+  # consumerGroup: rendered as the `CONSUMER_GROUP` env on the executor when
+  # non-empty. Gives each Kafka consumer its own consumer group (e.g.
+  # agent-task-executor-sun) so executors on different clusters do not share
+  # offsets. Empty = nothing rendered.
+  consumerGroup: ""
   # Pod-level securityContext. Empty by default — runAsNonRoot/runAsUser/fsGroup
   # depend on what the image supports, so clusters opt in (e.g. runAsNonRoot: true,
   # runAsUser: 65534, fsGroup: 65534).
@@ -161,6 +182,7 @@ executors: []
   #     repository: bborbe/agent-task-executor
   #     tag: ""                     # empty => Chart.appVersion (default executor.image)
   #   logLevel: "2"                 # default executor.logLevel
+  #   consumerGroup: ""             # default executor.consumerGroup
   #   sentry:
   #     # Sentry proxy cluster URL. Default executor.sentry.proxy. NOTE: sentry.dsn
   #     # is NOT a per-entry field — the chart never creates per-vault Secrets;
@@ -192,6 +214,7 @@ executors: []
   #     repository: bborbe/agent-task-executor
   #     tag: ""
   #   logLevel: "2"
+  #   consumerGroup: ""             # default executor.consumerGroup
   #   sentry:
   #     proxy: ""
   #   existingSecret: ""