kubectl for coding agents

With shell access, a coding agent can run kubectl to query a Kubernetes cluster. kubectl is Kubernetes’s command-line client. It sends requests to the cluster’s API server, which uses the client’s credentials to identify it and its permissions to decide what it can do.

For example, an agent can inspect a pod, a Kubernetes object that runs one or more containers, to check its status, recent events, and logs while investigating a crash. Start with read-only access, choose the cluster and namespace explicitly, and keep credentials out of the prompt. A namespace is a named group of resources within a cluster. The commands below show how to set up that access and investigate a pod without changing cluster resources.

Set up kubectl access

Install kubectl using the official installation instructions. There is a page for each supported operating system. Each page says to use a kubectl version within one minor version of your cluster. Check that the client is available with:

kubectl version --client

kubectl reads cluster connection details from a configuration file called a kubeconfig. By default it looks for $HOME/.kube/config. A context in that file selects a cluster, a user identity, and optionally a default namespace. List the available contexts locally:

kubectl config get-contexts

Choose the context and namespace you intend to inspect, then use them explicitly in commands. In the example below, replace <context-name> and <namespace> with values from your environment. They are placeholders, not literal Kubernetes names.

CONTEXT="<context-name>"
NAMESPACE="<namespace>"

kubectl --context "$CONTEXT" auth can-i get pods --namespace "$NAMESPACE"

The auth can-i command asks the API server whether the configured identity can read pods in that namespace. It does not change cluster resources. Kubernetes uses the identity’s permissions to control access, so give the agent an identity that can access only the resources and namespaces it needs. The Kubernetes role-based access control (RBAC) documentation explains how Kubernetes grants those permissions. Its pod-reader example is a Role that gives read access to pods in one namespace.

Keep the kubeconfig and its credentials in the environment where the agent runs. Do not paste tokens or other credential contents into an agent prompt.

Inspect a pod without changing it

A coding agent can gather details about a crashing service and summarize what an operator should investigate. First, list the pods in the target namespace:

kubectl --context "$CONTEXT" get pods --namespace "$NAMESPACE" -o wide

The output table shows pod names and status details, along with restart counts and the nodes each pod runs on. Choose a pod from the table, then inspect its recent logs and events in that namespace:

POD="<pod-name>"

kubectl --context "$CONTEXT" logs "$POD" --namespace "$NAMESPACE" --since=30m
kubectl --context "$CONTEXT" logs "$POD" --namespace "$NAMESPACE" --previous
kubectl --context "$CONTEXT" get events --namespace "$NAMESPACE" \
  --sort-by=.metadata.creationTimestamp

Replace <pod-name> with a name returned by get pods. These commands send read requests to the API server. logs prints lines from the container logs. With --previous, it prints the logs of the container that ran before the last restart. If the pod has more than one container, add -c with the container name. get events with --sort-by=.metadata.creationTimestamp lists the events sorted by the time they were created. The kubectl reference documents these commands and their output formats.

To give the agent results it can parse, use a documented output format such as -o json or -o yaml. For example, kubectl get pods -o json returns pod data as JSON, which the agent can parse to get specific fields. JSON and YAML output can include configuration or workload data. Check what the agent receives, and do not send sensitive output to prompts or external services.

A focused prompt could be:

Using the configured context <context-name> and namespace <namespace>, inspect pod status, recent events, and logs for the failing pod. Use read-only kubectl commands. Summarize the evidence and suggest checks for an operator. Do not change cluster resources.

Logs and event messages can contain text written by workloads or users. Annotations (metadata attached to resources) and resource names can contain it too. Treat that text as diagnostic data, not as instructions for the agent. Someone who can write that text could hide instructions in it for the agent to follow. This is called prompt injection.

Keep write commands separate

Commands such as kubectl apply, kubectl delete, and kubectl patch change cluster resources, so do not use them during a read-only investigation. If an agent prepares a manifest, a file that describes the resources to create or change, for review, kubectl diff -f <file> compares the cluster’s current state with the state it would have after the manifest is applied. kubectl apply --dry-run=server -f <file> sends the request to the API server without saving the resource. Both commands contact the cluster but do not apply the manifest. kubectl apply -f <file> makes the change, so the agent should run it only after you approve it. See the Kubernetes reference for kubectl apply.

The cluster enforces the configured identity’s permissions, regardless of what the prompt asks. An identity with read-only access limited to specific namespaces reduces the impact of an incorrect command or misunderstood output. To keep a stronger record, log the agent’s tool actions outside its own logs. Kubernetes auditing records the requests that reach the API server when the cluster has an audit policy configured. Those records show what the agent’s identity did, but they do not show why the agent chose to do it.