Skip to content

feat(kagent): mount kagent tools and substrate MCP in the template - #472

Merged
dimetron merged 2 commits into
mainfrom
feat/kagent-template-tools
Nov 14, 2026
Merged

dimetron merged 2 commits into
mainfrom
feat/kagent-template-tools

Conversation

@dimetron

Copy link
Copy Markdown
Owner

What

The kagent manifest now gives pi-go Kubernetes and Agent Substrate tools, and the network access they and common downloads need.

  • AgentTemplate mounts kagent's two built-in MCP servers, both installed by the kagent Helm chart:
    • kagent-tool-server: Kubernetes, Helm, Istio, Cilium, Argo Rollouts, Prometheus and a shell tool.
    • kagent-api: the controller's MCP, for Agent Substrate sandboxes, sessions and checkpoints.
  • New EgressPolicy pi-go-tools-egress: grants the two in-cluster MCP origins (http://kagent-tools.<ns>.svc.cluster.local:8084, http://<controller>.<ns>.svc.cluster.local:8083) and https://dl.k8s.io for kubectl.
  • github-egress adds https://release-assets.githubusercontent.com. github.com/<owner>/<repo>/releases/download/... now redirects there, so release downloads failed.
  • render-manifests.sh gets --tool-server, --api-server, --tools-service and --tools-egress-name. The defaults are the kagent chart's names, so the release workflow needs no change.
  • DEPLOY.md explains the tools, and that each Agent should reference both policies.

Why

On kagent, a BYO actor can only resolve and reach the hostnames its EgressPolicies name; Substrate's DNS relay answers NXDOMAIN for everything else. So the template's MCP servers need their own grant, as GitHub MCP already has one.

Verified

This is on kagent v1.0.0-alpha17-76 / Substrate 1.0.0-rc1 (kind, arm64), with the same objects applied by hand to the pi-go template and Agent.

  • Tools: pi-go called k8s_get_resources (11 pods in ate-system) and list_sandboxes (0). The Agent reported EgressPoliciesApplied=True, ResolvedRefs=True and Ready=True, with a new revision prepared.
  • Downloads: an actor downloaded kubectl v1.35.0 from dl.k8s.io and fetched v0.4.1/kagent-manifests.yaml through the release-assets redirect (3411 bytes).
  • Render: render-manifests.sh --image …@sha256:… --no-env leaves no placeholders. kubectl apply --dry-run=server accepts the Harness, AgentTemplate and new policy. bash -n and shellcheck are clean.

Notes

  • kagent-tool-server runs as cluster-admin in the default chart, including shell, k8s_delete_resource and helm_uninstall. Every agent on this template gets that power. Narrow it with tools: on the binding where a harness enforces selection, or with RBAC on kagent-tools.
  • github-egress doesn't apply on an existing cluster, and that's not new. A client-side kubectl apply of the rendered manifest still fails with metadata.resourceVersion: Invalid value: 0: must be specified for an update. The other objects apply. kubectl apply --server-side --dry-run=server accepted all four objects, but scripts/install-kagent.sh documents a problem mixing apply modes on these CRDs, so this PR doesn't change how the manifest is applied.

The AgentTemplate gave pi-go no tools beyond its own, so on kagent it could
not inspect the cluster or the Substrate it runs on, and the github-egress
policy blocked GitHub release downloads and kubectl.

- AgentTemplate: mount kagent's two built-in MCP servers, kagent-tool-server
  (Kubernetes, Helm, Istio, Cilium, Argo Rollouts, Prometheus, shell) and
  kagent-api (Agent Substrate sandboxes, sessions, checkpoints).
- New EgressPolicy pi-go-tools-egress: the two in-cluster MCP origins and
  https://dl.k8s.io. A BYO actor resolves and reaches only the hostnames its
  policies name, so without it the tools cannot connect.
- github-egress: add https://release-assets.githubusercontent.com, where
  github.com/.../releases/download now redirects.
- render-manifests.sh: --tool-server, --api-server, --tools-service and
  --tools-egress-name, defaulting to the kagent Helm chart's names.

Verified on kagent v1.0.0-alpha17-76 with the same objects applied by hand:
pi-go listed ate-system pods with k8s_get_resources and sandboxes with
list_sandboxes; an actor downloaded kubectl v1.35.0 from dl.k8s.io and a
release asset through release-assets.githubusercontent.com.

Signed-off-by: pi <dimetron@me.com>
@codecov

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.59%. Comparing base (aa9f94e) to head (a713435).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #472      +/-   ##
==========================================
- Coverage   91.60%   91.59%   -0.01%     
==========================================
  Files         390      390              
  Lines       50146    50146              
==========================================
- Hits        45937    45933       -4     
- Misses       4203     4207       +4     
  Partials        6        6              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Add pi-go-devtools-egress, which lists download hosts project by project
instead of wildcards:

- Kubernetes: dl.k8s.io and the kubernetes / kubernetes-sigs chart repos
- kagent and Agent Substrate: kagent.dev, ghcr.io
- agentgateway: agentgateway.dev, cr.agentgateway.dev
- registry layers: pkg-containers.githubusercontent.com (ghcr.io and
  cr.agentgateway.dev both answer blob requests with a 307 there)
- Helm: get.helm.sh
- arkade: get.arkade.dev, the non-GitHub hosts `arkade get` downloads
  from (pkg/get/tools.go) and the chart repositories `arkade install`
  uses (pkg/apps), 43 origins in all

dl.k8s.io moves here from pi-go-tools-egress, which now holds only the
in-cluster MCP servers. --devtools-egress-name names the policy.

An origin grants its whole host, so github.com and ghcr.io cannot be
narrowed to one organisation's paths with an EgressPolicy; DEPLOY.md says
so. Verified from a kagent actor: every host group answered (registries
with the expected 401 on /v2/), get.arkade.dev served its installer, and
an ungranted host (example.org) did not resolve.

Signed-off-by: pi <dimetron@me.com>
@dimetron

Copy link
Copy Markdown
Owner Author

Updated per review: egress is now allowed per project, with arkade added.

  • pi-go-devtools-egress (new): 43 explicit origins, no wildcards (no *.github.io, no *.googleapis.com):
    • Kubernetes: dl.k8s.io, kubernetes.github.io, kubernetes-sigs.github.io

    • kagent / Agent Substrate: kagent.dev, ghcr.io

    • agentgateway: agentgateway.dev, cr.agentgateway.dev

    • Registry layers: pkg-containers.githubusercontent.com. Both registries above answer blob requests with a 307 to it (checked).

    • Helm: get.helm.sh

    • arkade:

      • get.arkade.dev;
      • the 10 non-GitHub hosts arkade get downloads from (pkg/get/tools.go);
      • the 23 chart repositories arkade install uses (pkg/apps).

      These come from a clone of alexellis/arkade at 18ccdbc.

  • pi-go-tools-egress now holds only the in-cluster MCP servers; dl.k8s.io moved to devtools.

Limit: an EgressPolicy origin grants a whole host, all paths. So github.com and ghcr.io can't be narrowed to one organisation (kubernetes/*, kagent-dev/*, agentgateway/*). That would need a filtering proxy in front of them. DEPLOY.md says so.

Verified on kagent alpha17-76 / Substrate rc1, from a Claude Code actor using the same list:

  • Hosts in every project group answered: kagent.dev, agentgateway.dev, prometheus-community charts, get.helm.sh, releases.hashicorp.com, dl.k8s.io. The registries returned the expected 401 on /v2/.
  • get.arkade.dev served its installer (6095 bytes).
  • An ungranted host (example.org) got bad address: the actor's DNS refuses names that aren't in its policies.

@dimetron
dimetron merged commit 6d63386 into main Nov 14, 2026
14 of 15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant