EEM kubernetes tools

Overview

Tool inventory: 31 core Kubernetes tools + 5 ecosystem tools = 36 tools total.

Dispatch Model

All k8s_*, helm_*, argocd_*, and kustomize_* tools are EEM exec-adapter tools. They are not advertised directly as chat-completion x_* tools. Chat callers invoke them through the x_exec_invoke envelope, passing tool_name set to the canonical name (for example k8s_get_pods). See the EEM Overview for the full execution lifecycle and approval flow.

Core Tools

Pods

k8s_get_pods, List pods in a namespace (JSON, read)
k8s_describe_pod, Describe a single pod (read)
k8s_delete_pod, Delete a pod (write)
k8s_logs, Fetch pod logs (read)
k8s_label_pod, Add or update a pod label (write)
k8s_annotate_pod, Add or update a pod annotation (write)

Nodes

k8s_get_nodes, List cluster nodes (read)
k8s_drain_node, Drain a node of pods (write, destructive)
k8s_cordon_node, Mark a node unschedulable (write)
k8s_uncordon_node, Mark a node schedulable (write)

Workloads

k8s_get_deployments, List deployments (read)
k8s_restart_deployment, Roll-restart a deployment (write)
k8s_scale_deployment, Scale replica count (write), up to the workspace's scale_replica_cap when it declares one.
k8s_rollout_status, Inspect rollout status (read)
k8s_rollout_history, Inspect rollout history (read)
k8s_rollout_undo, Revert to a previous revision (write)

Networking

k8s_get_services, List services (read)
k8s_get_ingress, List ingresses (read)

Configuration

k8s_get_configmaps, List configmaps (JSON, read)
k8s_get_secrets, List secrets (read). Blast radius: emits kubectl get secrets -o json, which returns the full Secret resource including the base64-encoded data map. Treat the output as sensitive material and gate approvals accordingly.
k8s_get_namespaces, List namespaces (read)

Events

k8s_get_events, List recent events in a namespace (read)

Exec

k8s_exec, Run a command in a pod container (write, destructive). Requires exec_allowed_pods and exec_allowed_commands on the workspace; see Workspace Scope.

Metrics

k8s_top_nodes, Per-node CPU/memory usage (read)
k8s_top_pods, Per-pod CPU/memory usage (read)
k8s_top_cluster, Aggregate cluster usage (read)

Manifests

k8s_apply_manifest, Apply an inline YAML/JSON manifest (write)
k8s_apply_from_file, Apply a manifest from a file path (write). Requires kube_manifest_paths on the workspace; see Workspace Scope.
k8s_delete_resource, Delete a resource by kind/name (write, destructive)

Generic

k8s_wait, Wait for a resource condition (read)

Ecosystem Integrations

Helm

helm_list, List Helm releases (read)
helm_history, Show release history (read)

Kustomize

kustomize_build, Render overlays to YAML (read). Requires kustomize_paths on the workspace; see Workspace Scope.

ArgoCD

argocd_app_list, List ArgoCD applications (read)
argocd_app_sync, Trigger an application sync (write)

Workspace Scope

Four tools read the workspace's scope before they build a command line, and three of them refuse when the key they read is absent. This is a change: a kubernetes workspace that declares no scope used to run all four.

k8s_exec needs both exec_allowed_pods, glob patterns matched against the pod argument, and exec_allowed_commands, binaries matched against the FIRST element of the command argv. Without both keys it refuses every call.
k8s_apply_from_file needs kube_manifest_paths, and refuses any path outside those directories.
kustomize_build needs kustomize_paths, and refuses any directory outside those directories. An omitted directory means the first one declared; it used to mean the agent's own working directory.
k8s_scale_deployment reads scale_replica_cap when it is declared and is unchanged when it is not: a cap narrows a tool that is meant to scale, rather than granting it anything.

The first three keys behave that way because each of those tools takes a pod, a command or a filesystem path straight from the caller. An undeclared key there is a grant rather than a narrowing, and a grant nobody wrote grants nothing: unbounded, path and directory reach the whole filesystem of the host the agent runs on, which on a laptop is a home directory.

Only the argv's first element is matched, and nothing is smuggled past it: kubectl exec runs the argv directly with no shell in between, so ["ls", "; curl ..."] runs ls with one odd argument rather than two commands. The element is compared exactly as written, so /bin/sh and sh are separate entries; list the spelling your callers use. Allowing a shell, or anything that runs other programs, allows whatever it can run -- that is a decision the operator makes by listing it.

Path keys must be absolute. A path that leaves a declared directory through a symbolic link is refused rather than followed, and the directory handed to kubectl or kustomize is the one that was checked. What those binaries do with it afterwards is theirs.

namespaces bounds every tool on this page that targets one, and enabled_resource_kinds bounds every tool's kind. Both narrow rather than grant, so a workspace that declares neither behaves as it always did.

A tool that substitutes default for an omitted namespace is checked against that literal, so a workspace whose list leaves out default has to be passed a namespace.
k8s_apply_manifest, k8s_apply_from_file and helm_history pass no namespace when the call omits one, which would hand the choice to the kubeconfig's current context; while namespaces is set that is refused.
helm_list with no namespace, and k8s_top_cluster always, read every namespace. "All of them" is inside no list, so both are refused while namespaces is set; use k8s_top_pods for one namespace.
k8s_apply_manifest parses its own manifest body while either key is set, because a document carries its own metadata.namespace. Multi-document YAML, JSON and a List wrapper are all read; a body that is not valid YAML or JSON is refused rather than passed through; a document that names a namespaced kind with no namespace in it and none on the call is refused. Cluster-scoped kinds have no namespace and are not bounded by one.
k8s_delete_resource checks its kind, and k8s_wait and the k8s_rollout_* tools check the part of resource before the slash. A resource with no slash names no kind and is refused while enabled_resource_kinds is set. Kind spellings are compared after lowercasing and dropping the API group, so Pod, pods and po are one kind; a kind outside the built-in table is matched literally.

Nothing here bounds which CLUSTER a call reaches. No tool on this page takes a context or a cluster argument and none passes --context, so the cluster is the one the kubeconfig the tool runs on currently points at: the workspace's own, when it sets credentials_ref. No scope key bounds it, and the one that claimed to has been removed. See Config Files for the full scope reference.

Credential Setup

The kubectl and helm tools on this page take a Kubernetes credential: the kubeconfig named by the workspace's credentials_ref, a file on the agent host at credentials_dir/<workspace>/<credentials_ref>. They get it through KUBECONFIG and read no other kubeconfig. No inline secret is accepted on the tool-call envelope.

A kubeconfig that is missing, empty, a symlink, or readable by group or other refuses the call before kubectl runs.
There is no in-cluster fallback. An agent running in a pod uses the service account only through a kubeconfig that names it.
The ArgoCD tools take a bearer token, which a workspace cannot bind yet, so they are refused in a workspace that sets credentials_ref. kustomize_build takes no credential and runs.
A workspace without credentials_ref runs these tools on whatever kubeconfig the agent's own account reaches. Run one agent per credential boundary, or bind each workspace.

See Workspace credentials for the file layout.

Examples

See the EEM Overview for the execution lifecycle and approval flow when using Kubernetes tools.