Automatic constraint discovery and developer notification for Kubernetes.

Potoo is a Kubernetes operator that automatically discovers all policies, constraints, quotas, and requirements across your cluster — regardless of which policy engine created them — and notifies developers when those constraints are blocking their workloads.

Modern Kubernetes clusters enforce constraints through many independent systems: Cilium network policies, Gatekeeper/OPA constraints, Kyverno policies, Istio authorization policies, native NetworkPolicies, ResourceQuotas, ValidatingWebhookConfigurations, and more. When a developer's deployment fails or their traffic is silently dropped, they have no unified way to discover what is blocking them or why. They spend hours debugging across scattered tools, kubectl commands, and Slack messages to platform teams.

Potoo sits in your cluster and:

1. Discovers all constraint-like resources automatically by scanning CRDs, webhooks, network policies, quotas, and mesh configurations
2. Indexes them into a normalized model regardless of source engine
3. Correlates failures (admission rejections, traffic drops, missing prerequisites) to the specific constraint causing them
4. Notifies developers via Kubernetes Events, a ConstraintReport CRD, and optional external channels (Slack, webhooks) — with privacy-aware detail levels that don't leak cross-namespace security information

• Cross-engine: Not tied to any single policy engine. Discovers constraints from Cilium, Gatekeeper, Kyverno, Istio, native K8s, and arbitrary CRDs.
• Automatic discovery: No manual registration of policy types. Scans the cluster's CRDs and heuristically identifies constraint-like resources, with pluggable adapters for deep parsing of known types.
• Runtime awareness: Integrates with Cilium Hubble for real-time traffic drop detection — developers are notified within seconds when a network policy blocks their traffic.
• Missing resource detection: Infers when a workload is missing a required companion resource (ServiceMonitor, VirtualService, PeerAuthentication, etc.) and alerts proactively.
• Privacy-first: Notifications are scoped by role. Developers see actionable summaries without cross-namespace policy details. Platform admins see full constraint specifics.
• Developer experience focused: The goal is not enforcement (policy engines already do that) but explanation — helping developers understand and resolve constraint issues quickly.

See ARCHITECTURE.md for detailed architecture documentation.

┌─────────────────────────────────────────────────┐
│                Potoo               │
│                                                  │
│  ┌─────────────┐  ┌──────────────┐              │
│  │  Discovery   │  │   Adapter    │              │
│  │   Engine     │──│   Registry   │              │
│  │             │  │              │              │
│  │ CRD Scanner │  │ Cilium       │              │
│  │ Heuristic   │  │ Gatekeeper   │              │
│  │ Detection   │  │ Kyverno      │              │
│  └──────┬──────┘  │ Istio        │              │
│         │         │ NetworkPolicy│              │
│         ▼         │ Webhooks     │              │
│  ┌─────────────┐  │ ResourceQuota│              │
│  │  Constraint  │  │ Generic      │              │
│  │   Indexer    │◄─┘              │              │
│  └──────┬──────┘                  │              │
│         │                         │              │
│         ▼                         │              │
│  ┌─────────────┐  ┌──────────────┐              │
│  │ Correlation  │  │  Requirement │              │
│  │   Engine     │  │  Evaluator   │              │
│  │             │  │              │              │
│  │ Events      │  │ Missing CRDs │              │
│  │ Hubble Flows│  │ Missing Mesh │              │
│  │ Dry-Run     │  │ Co-occurrence│              │
│  └──────┬──────┘  └──────┬───────┘              │
│         │                │                       │
│         ▼                ▼                       │
│  ┌─────────────────────────────┐                │
│  │   Notification Dispatcher   │                │
│  │                             │                │
│  │ K8s Events │ ConstraintReport │ Slack/Webhook│
│  └─────────────────────────────┘                │
└─────────────────────────────────────────────────┘

Separate Deployment:
┌─────────────────────────────────────────────────┐
│         Admission Webhook (Warning Mode)         │
│  Deploy-time warnings via K8s admission warnings │
│  failurePolicy: Ignore (always fail-open)        │
└─────────────────────────────────────────────────┘

helm repo add potoo https://potoo.io/charts
helm install potoo potoo/potoo \
  --namespace potoo-system \
  --create-namespace

Then in any namespace:

kubectl get constraintreports -n my-namespace

🚀 Alpha — Core discovery, 8 policy adapters (Cilium, Gatekeeper, Kyverno, NetworkPolicy, ResourceQuota, LimitRange, Webhooks, Generic), correlation engine, notification system, MCP server, CLI, admission webhook, and requirements evaluator are implemented and tested. See PROJECT_PLAN.md for the roadmap.

Potoo is designed for consumption by AI agents and automation tools, not just human developers. Every output has a structured, machine-parseable form.

See Agent Outputs for full design documentation.

Getting Started

• Installation — Helm, binary, and source install options
• Quickstart — 5-minute hands-on tutorial

Usage

• CLI Reference — potoo query, explain, check, remediate, and status commands
• MCP Server — AI agent integration with tools and resources
• CRD Reference — ConstraintReport, ConstraintProfile, NotificationPolicy

Reference

• Architecture — Deployment model, component design, data flow
• Constraint Types — Network, Admission, Resource, Mesh, and Missing constraint categories
• Severity Levels — Critical, Warning, and Info definitions
• Agent Outputs — MCP server, structured events, machine-readable CRDs, kubectl plugin
• Privacy Model — Information classification and notification scoping
• Adapters — Supported policy engines and adapter details
• Notifications — Event, report, and annotation notification system
• Configuration — Controller and webhook configuration options
• Adapter Guide — How to write a constraint adapter for a new policy engine
• Helm Chart — Helm chart documentation and values reference
• Examples — Standalone YAML manifests for trying out Potoo
• Changelog — Release history
• Contributing — How to contribute to the project

Apache License 2.0 — See LICENSE.