Calling kubectl Safely from an Agent

kubectl is a sharp tool. The wrapper that whitelists verbs, classifies blast radius, and refuses anything outside scope. With the test suite that proves it.

Verb allowlist

The verb allowlist is the first safety primitive. Read-only verbs allow in any context; mutating verbs allow conditionally with controlled scope; dangerous verbs deny outright because they are too risky for unattended agent use.

• Allow. get, describe, logs; read-only and safe in any context.
• Conditional allow. scale, rollout; with a controlled namespace and replica delta.
• Deny. delete, exec, port-forward, edit; too dangerous for unattended agent use.
• Per-verb policy committed. The allowlist documented in the agent’s policy file; supports investigation when a verb is invoked.

Scope by namespace and resource

Scope narrows what each verb can touch. The wrapper restricts namespace (production requires extra approval), restricts resource type (the agent lists pods but cannot modify CRDs), restricts label selectors (anything in dev is fair game; production requires app=approved-set).

• Namespace restriction. Production namespace requires extra approval; dev is open.
• Resource-type restriction. Agent lists pods but cannot modify CRDs; the resource axis is enforced.
• Label selector restriction. Production requires app=approved-set; the selector narrows the blast surface.
• Per-namespace approval policy. Documented per environment; supports the principle of least access.

Blast-radius classification

Each operation has a blast-radius classification. get/describe is blast 0 (no state change); logs is blast 0 in normal operation but can be high on huge log lines (cost); scale 1 to 3 on a Deployment is blast contained to the deployment; rollout undo is contained but irreversible without effort.

• Get/describe: blast 0. No state change; safe in any context.
• Logs: blast 0 with cost cap. Normal operation safe; huge log lines incur cost; cap output size.
• Scale: contained. Scale 1 to 3 on a Deployment; blast contained to the deployment.
• Rollout undo: contained but irreversible. Blast contained but not easily undone; requires conscious approval.

Test suite for the wrapper

The wrapper needs a test suite that covers happy path, deny path, and edge cases. Each allowed verb on each resource type passes; each denied verb fails with a clear error; each conditional passes with the right scope and fails without; edge cases (empty namespace, malformed selectors, very long outputs) are covered explicitly.

• Allowed verbs pass. Each allowed verb on each resource type; the happy path is tested.
• Denied verbs fail clearly. Each denied verb fails with a clear error; the deny path is tested.
• Conditionals pass and fail. Pass with the right scope, fail without; the conditional logic is tested.
• Edge cases covered. Empty namespace, malformed selectors, very long outputs; explicit tests for each.

Observability of kubectl calls

Every kubectl call from the agent is observed. Logged with agent run id, verb, resource, namespace, exit code, output size; aggregate dashboards show calls per agent role, per verb, and error rates; outlier alerts fire on a sudden spike in a normally-quiet verb because that is the kind of anomaly worth investigating.

• Per-call log line. Agent run id, verb, resource, namespace, exit code, output size; the audit trail.
• Aggregate dashboards. Calls per agent role, calls per verb, error rates per verb; the macro view.
• Outlier alerts. Sudden spike in a normally-quiet verb; a flag worth investigating.
• Per-incident replay. The log line supports incident reconstruction; the agent’s actions are reviewable.