Potoo — Kubernetes Policy Debugger

Kubernetes deployments fail for a lot of reasons that look identical from the outside — a pod sits in Pending, a request times out, an admission webhook silently rejects a manifest. The cause is scattered across NetworkPolicies, Cilium policies, Gatekeeper constraints, Kyverno policies, Istio configurations, ResourceQuotas, custom webhooks, and a long tail of CRDs. Finding the specific policy responsible usually means kubectl spelunking across multiple namespaces, with cluster-admin access most app teams don’t have. Potoo is a Kubernetes operator that does that work continuously and tells the affected developer what blocked them — without enforcing any policy of its own.

What it does

#

Potoo solves a routing problem — getting the right failure information to the right developer — not a policy problem. It watches the policy surface continuously, correlates failures (denied admissions, blocked traffic, missing required resources) to the policy that caused them, and tells the affected developer what they need to know — via Kubernetes Events, a ConstraintReport CRD, Slack, or workload annotations. Visibility is scoped per tenant so platform-owned policy detail doesn’t leak across namespace boundaries.

How it works

#

• Discovery engine scans the cluster for policy-bearing resources via known CRDs plus heuristic detection. Adding a new policy engine follows a documented contribution path (docs/ADAPTER_GUIDE.md).
• Adapter registry covers Cilium, Gatekeeper, Kyverno, NetworkPolicy, ResourceQuota, LimitRange, ValidatingWebhookConfigurations, and a generic heuristic adapter for unknown CRDs. Istio is supported when present (authorization policies, VirtualServices, PeerAuthentication).
• Correlation engine integrates with Cilium Hubble to attribute real-time network failures to the policy that produced them, and with the admission webhook chain for deploy-time blocks.
• Missing resource detection infers when a workload lacks an expected sibling — ServiceMonitor for Prometheus scrape, VirtualService for Istio routing, PeerAuthentication for mTLS — and surfaces that the same way it surfaces explicit policy blocks.
• Pre-flight admission webhook runs against manifests before they’re applied, predicting which policies a workload will trip without actually deploying it.
• MCP server exposes the discovered constraint model as tools an AI agent can call. Claude Code, Copilot, or any MCP client can ask “what’s blocking this Pod?” and get a structured answer.
• ConstraintReport CRD is the machine-readable output for kubectl queries, dashboards, and automation. Designed with explicit agent-friendly fields so it composes cleanly with the MCP interface.

Deploys via Helm; no sidecars, no per-node agents.

Architecture notes

#

• Read-only, not in the control path. Potoo doesn’t gate admissions, doesn’t drop packets, doesn’t inject sidecars. A bug in Potoo can’t block a deployment — the worst outcome is a missed notification, not a missed workload.
• Adapter pattern over a unified schema. Policy engines disagree about what a “constraint” is. Rather than force a lossy common model, adapters translate each source into a per-engine view that the correlation engine joins on workload identity.
• Privacy scoped at the notification layer. Tenant boundaries are enforced before notification dispatch, not at query time.
• MCP as a peer interface. The agent surface is structured against the same constraint model as the CRD and kubectl outputs, not wrapped around an internal API.

Status

#

Alpha. Released v0.1.0 on 2026-02-18. Licensed under BSL 1.1; converts to Apache 2.0 on 2029-02-20 per the license’s Change Date.

potooio/potoo

K8s operator designed to explain any infra or cluster based constraints that could prohibit or inhibit deployments to developers.

Go

0

0