Repository navigation
docs: cover namespace-restricted installs on the 1.x installation page (#629) - #641
Conversation
kagent-dev#629) Signed-off-by: Moritz Schmitz von Hülst <mschmitzvonhuelst@gmail.com>
Rachael-Graham
left a comment
Rachael-Graham
left a comment
There was a problem hiding this comment.
Thanks! I tested this locally and had a fw suggestions based on that
| - `config.kubernetes.watchNamespaces` narrows the watch below the RBAC scope. A watch entry that names a namespace outside the RBAC scope fails the render, because the controller would loop on `Forbidden` errors at runtime. | ||
| - The `kagent-tool-server` RemoteMCPServer that the chart creates admits references from its own namespace only. An Agent in another watched namespace that binds it does not become ready until you set `allowedNamespaces` on that server. See [Reach kagent-tool-server from another namespace]({{< link path="reference/tools-ecosystem#reach-kagent-tool-server-from-another-namespace" >}}). | ||
|
|
||
| Verify a namespaced install the same way as the default one, plus the negative case: create an Agent in each watched namespace and in one unwatched namespace, and confirm that the controller reconciles only the watched two while the Agent in the unwatched namespace stays unmanaged. |
There was a problem hiding this comment.
can you change this to numbered steps w/ commands and expected output to match the rest of the guide? or link to a diff verification steps section
| watchNamespaces: [prod-agents, staging-agents] | ||
| ``` | ||
|
|
||
| Prefer `global.watchNamespaces` over the per-surface keys. The chart derives both surfaces from this one value, so they cannot disagree: it replaces the cluster-scoped getter and writer ClusterRoles with a Role and RoleBinding in each listed namespace, and it limits the controller's watch to the same list. The chart appends the install namespace to the list automatically, so the release's own objects remain managed. |
There was a problem hiding this comment.
getter and writer ClusterRoles
this names only two of the three ClusterRoles the chart namespaces, bc kagent-tools-cluster-admin-role also becomes a role - maybe "replaces every kagent ClusterRole with a Role and RoleBinding in each listed namespace"
| The per-surface keys still exist for installs that scope the surfaces independently, and the validation rules bind them: | ||
|
|
||
| - `rbac.namespaces` takes precedence over `global.watchNamespaces` whenever the key is present. An explicit `rbac.namespaces: []` restores cluster-scoped RBAC. When `rbac.namespaces` is set, it must include the install namespace or the render fails. | ||
| - `config.kubernetes.watchNamespaces` narrows the watch below the RBAC scope. A watch entry that names a namespace outside the RBAC scope fails the render, because the controller would loop on `Forbidden` errors at runtime. |
There was a problem hiding this comment.
Under global.watchNamespaces, the chart adds config.kubernetes.watchNamespaces entries to the RBAC scope instead of failing (_helpers.tpl:93-96,109). The render fails only when rbac.namespaces is set explicitly, so please make the bullet conditional on that.
There was a problem hiding this comment.
also on this line - I tested this in a cluster, abd setting config.kubernetes.watchNamespaces alongside global.watchNamespaces replaces the watch list & the install namespace isnt added back. On alpha16, global.watchNamespaces: [prod-agents, staging-agents] with config.kubernetes.watchNamespaces: [prod-agents] left new Agents in kagent with no status. So I think state that the install namespace must be listed explicitly.
|
The The content-gating checks all pass: Static + content checks, linkChecker, DCO. So the deploy red is an environment limitation of fork PRs, not a content problem — no preview URL will be available for this PR until it is merged (or the branch is mirrored into an org account that can see the secrets). |
…-dev#629) Signed-off-by: Moritz Schmitz von Hülst <mschmitzvonhuelst@gmail.com>
|
All four points addressed in 0b4bb74:
|
Rachael-Graham
left a comment
Rachael-Graham
left a comment
There was a problem hiding this comment.
nice, thank you very much for covering this. Merging
Closes #629
The 1.x installation page had no guidance on restricting kagent to specific namespaces; the only documentation of the alternative was the
global.watchNamespacesrow in1.x/reference/helm.md.Adds the optional section "Restrict kagent to specific namespaces" after "Verify the installation" and before "Next steps", per the issue's scope:
global.watchNamespacesvalues example.global.watchNamespacesover the per-surface keys, and explains that the chart derives both surfaces (RBAC and the controller watch) from it, and appends the install namespace automatically.rbac.namespaceswins when the key is present, an explicitrbac.namespaces: []restores cluster-scoped RBAC and must include the install namespace when set, andconfig.kubernetes.watchNamespacesoutside the RBAC scope fails the render (Forbidden loop).allowedNamespacescoverage for the chart-created RemoteMCPServer to the existing tools-ecosystem section rather than repeating it.Verified against the chart at v1.0.0-alpha16 (the latest release as of 2026-10-19): the precedence, install-namespace append, and render-failure behavior described are what
helm/kagent/templates/_helpers.tpland the RBAC templates implement.How to Test
Build the docs and check the new section and its link:
The section renders on /kagent/1.x/setup/installation/ and the anchor link resolves to the existing "Reach kagent-tool-server from another namespace" section of the tools-ecosystem reference.