[Automated] Draft docs (kagent): fix(substrate): isolate worker pool placement by namespace

[github-actions]

kagent-dev/kagent#3089 — fix(substrate): isolate worker pool placement by namespace

Docs versions: 1.x (first shipped in v1.0.0-alpha10)

What changes for users: Generated ActorTemplates now select WorkerPools with both kagent.dev/worker-pool-name and kagent.dev/worker-pool-namespace, so same-named pools in different namespaces do not share Workers. Externally managed WorkerPools must carry both labels before upgrade, and old Sessions or Sandboxes need the old kagent.dev/worker-pool label until they are recreated.

What the docs now say: The Tune Agent Substrate page now explains namespace-scoped WorkerPool placement, shows the labels for externally managed WorkerPools, and documents the temporary compatibility label for pre-upgrade revisions.

Not verified: The workflow captured the cluster API surface, but no configuration was applied and the steps are unrun.

How kagent-3089 was drafted, and what was not verified

• Code PR: fix(substrate): isolate worker pool placement by namespace kagent#3089
• Code issue: none linked
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-alpha10.
• Category: new-feature / pr

Plan, and what changed it

• Planned: Add the WorkerPool placement labels and upgrade behavior to the page that owns WorkerPool tuning.
• Learned: tune-agent-substrate.md already owns WorkerPool sizing, Helm values, Worker images, and sandbox-class changes; cluster-facts.md confirms WorkerPool is ate.dev/v1alpha1.
• Did: Added a namespace-scoped placement section to operations/tune-agent-substrate.md, plus an external WorkerPool example and compatibility guidance.

Why a documentation change is necessary

The pull request changes Worker selection from the old name-only kagent.dev/worker-pool label to the kagent.dev/worker-pool-name and kagent.dev/worker-pool-namespace labels. The diff also says chart-managed pools get authoritative placement labels, while externally managed pools must carry both labels. The existing WorkerPool tuning page documented pool sizing, resources, sandbox class, and Worker images, but did not tell operators how placement labels work or what to do during upgrades.

Rejected targets:

• docs-site/content/kagent/1.x/about/architecture/agent-substrate.md: concept overview; useful background, but the user action is configuring WorkerPools.
• docs-site/content/kagent/1.x/about/substrate-runtime/_index.md: section index; no configuration belongs there.
• docs-site/content/kagent/1.x/about/substrate-runtime/identity.md: Agent Substrate authentication and identity, not Worker placement.
• docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md: egress policy behavior, not WorkerPool selection.
• docs-site/content/kagent/1.x/about/substrate-runtime/sandboxing.md: sandbox class concepts, not WorkerPool metadata labels.
• docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md: SandboxTemplate authoring, not chart-managed or external WorkerPool operations.
• docs-site/content/kagent/1.x/about/substrate-runtime/suspend-and-resume.md: lifecycle behavior, not placement configuration.
• docs-site/content/kagent/1.x/agents/agent-harness.md: Harness authoring; spec.substrate.workerPoolRef.name already belongs to Harnesses, but the changed labels belong to WorkerPools.
• docs-site/content/kagent/1.x/operations/operational-considerations.md: production overview that already points readers to Tune Agent Substrate for pool sizing.
• docs-site/content/kagent/1.x/setup/installation.md: fresh install path; the chart sets the new labels automatically there.

What changed on disk

• docs-site/content/kagent/1.x/operations/tune-agent-substrate.md: Added kagent.dev/worker-pool-name, kagent.dev/worker-pool-namespace, externally managed WorkerPool labels, and the temporary kagent.dev/worker-pool compatibility label.

How to verify this change

1. Upgrade kagent with a chart-managed WorkerPool and optional extra labels.

   helm upgrade kagent \
     oci://ghcr.io/kagent-dev/kagent/helm/kagent \
     --namespace kagent \
     --reuse-values \
     -f kagent.yaml

2. Check the chart-managed WorkerPool labels.

   kubectl get workerpool kagent-default -n kagent \
     -o jsonpath='{.metadata.labels.kagent\.dev/worker-pool-name}{" "}{.metadata.labels.kagent\.dev/worker-pool-namespace}{"\n"}'

   The command prints kagent-default kagent.
3. Apply an externally managed WorkerPool with the two placement labels, then check the labels.

   kubectl get workerpool external-pool -n team-a \
     -o jsonpath='{.metadata.labels.kagent\.dev/worker-pool-name}{" "}{.metadata.labels.kagent\.dev/worker-pool-namespace}{"\n"}'

   The command prints external-pool team-a. A new revision that references a pool without both labels stays Ready=False with reason ActorTemplatePending.

What was not verified

The configuration was not applied to a cluster, so every command in this diff is unrun.
The upgrade transition for old Sessions and Sandboxes was not exercised in this sandbox.

How the pages were chosen (triage report)

Feature clusters

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• feat: add runtime revision GC backlog and failure metrics kagent#2808 and fix(substrate): isolate worker pool placement by namespace kagent#3089 both have docs-site/content/kagent/1.x/agents/agent-harness.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• fix: allow disabling kagent model streaming kagent#3028 and fix(substrate): isolate worker pool placement by namespace kagent#3089 both have docs-site/content/kagent/1.x/agents/agent-harness.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• feat(telemetry): move Python runtimes onto upstream GenAI instrumentation kagent#3103 and fix(substrate): isolate worker pool placement by namespace kagent#3089 both have docs-site/content/kagent/1.x/agents/agent-harness.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there

New configuration: no page mentions it yet

kagent-dev/kagent#3089 — fix(substrate): isolate worker pool placement by namespace

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): WorkerPools with the same name in different namespaces share a placement label. Generated ActorTemplates can therefore select another namespace's workers.
• Not tested: a cluster was used only to dry-run the YAML manifests the draft added; prose, inline field paths and commands are unrun
• No rule covers 1 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • docs/architecture/configuration-and-compilation.md

Draft branch: pr-tracker-draft-kagent-3089

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. This repository's checks are held as action_required until somebody presses Approve and run on the Checks tab. Checks that come from GitHub Apps rather than Actions, such as DCO, run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[Rachael-Graham]

Absorbed into #591 (commit 0ef30c0), rewritten against the current page rather than merged — this branch was cut before main's rewrite of tune-agent-substrate.md, so it conflicts with main on its own.

Content verified against the v1.0.0-alpha12 chart: substrate-workerpool.yaml applies both placement labels through mergeOverwrite after substrateWorkerPool.labels, and substrate-workerpool_test.yaml asserts kagent.dev/worker-pool is no longer set. The two field tables were dropped because they restated their own YAML.