potoo query

Query constraints affecting a namespace.

Table of contents

1. Synopsis
2. Description
3. Flags
   1. Constraint Types
   2. Severity Levels
4. Examples
   1. Query All Constraints
   2. Filter by Type
   3. Filter by Severity
   4. JSON Output
   5. JSON with Remediation
5. Response Schema
   1. QueryResult
   2. ConstraintInfo
6. Exit Codes
7. See Also

---

Synopsis

potoo query -n <namespace> [flags]

---

Description

The query command retrieves all constraints affecting workloads in a namespace. It reads from the ConstraintReport CRD created by the Potoo controller.

Results are sorted by severity (Critical first, then Warning, then Info).

---

Flags

Flag	Short	Required	Description
--namespace	-n	Yes	Namespace to query
--type		No	Filter by constraint type
--severity		No	Filter by severity level
--workload		No	Filter by workload name
--output	-o	No	Output format: table, json, yaml

Constraint Types

Valid values for --type:

• NetworkIngress - Inbound network restrictions
• NetworkEgress - Outbound network restrictions
• Admission - Admission webhook/policy rejections
• ResourceLimit - Quota and limit range restrictions
• MeshPolicy - Service mesh authorization policies
• MissingResource - Required companion resources not found

Severity Levels

Valid values for --severity:

• Critical - Active blocking (traffic drops, admission rejections)
• Warning - Approaching limits, audit violations
• Info - Informational, not actively blocking

---

Examples

Query All Constraints

potoo query -n my-namespace

Output:

NAMESPACE     NAME               TYPE            SEVERITY   EFFECT
my-namespace  restrict-egress    NetworkEgress   Critical   deny
my-namespace  require-limits     Admission       Critical   deny
my-namespace  compute-quota      ResourceLimit   Warning    limit
my-namespace  allow-internal     NetworkIngress  Info       restrict

Filter by Type

potoo query -n my-namespace --type NetworkEgress

Output:

NAMESPACE     NAME             TYPE           SEVERITY   EFFECT
my-namespace  restrict-egress  NetworkEgress  Critical   deny

Filter by Severity

potoo query -n my-namespace --severity Critical

Output:

NAMESPACE     NAME             TYPE           SEVERITY   EFFECT
my-namespace  restrict-egress  NetworkEgress  Critical   deny
my-namespace  require-limits   Admission      Critical   deny

JSON Output

potoo query -n my-namespace -o json

Output:

{
  "namespace": "my-namespace",
  "constraints": [
    {
      "name": "restrict-egress",
      "constraint_type": "NetworkEgress",
      "severity": "Critical",
      "effect": "deny",
      "source_kind": "NetworkPolicy",
      "source_api_version": "networking.k8s.io/v1",
      "affected_workloads": ["api-server", "worker"],
      "tags": ["network", "egress", "port-restriction"],
      "detail_level": "summary",
      "last_observed": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

JSON with Remediation

The JSON output includes remediation information when available:

{
  "constraints": [
    {
      "name": "restrict-egress",
      "remediation": {
        "summary": "Request network policy exception",
        "steps": [
          {
            "type": "manual",
            "description": "Contact platform team to request egress exception",
            "contact": "[email protected]",
            "requires_privilege": "developer"
          },
          {
            "type": "kubectl",
            "description": "Add exception annotation to workload",
            "command": "kubectl annotate deployment my-app potoo.io/egress-exception=true",
            "requires_privilege": "namespace-admin"
          }
        ]
      }
    }
  ]
}

---

Response Schema

QueryResult

Field	Type	Description
namespace	string	Queried namespace
constraints	ConstraintInfo[]	List of matching constraints
total	int	Total count

ConstraintInfo

Field	Type	Description
name	string	Constraint name (may be redacted per privacy)
constraint_type	string	Type classification
severity	string	Critical, Warning, or Info
effect	string	deny, restrict, warn, audit, limit
source_kind	string	Kubernetes kind (NetworkPolicy, etc.)
source_api_version	string	API version of source
affected_workloads	string[]	Workload names affected
message	string	Human-readable summary
tags	string[]	Filtering tags
remediation	RemediationInfo	Remediation steps (if available)
detail_level	string	Privacy level applied
last_observed	string	ISO 8601 timestamp

---

Exit Codes

Code	Meaning
0	Success
1	Error (invalid flags, API error, etc.)

---

See Also

• explain - Match errors to constraints
• check - Pre-check manifests
• remediate - Get remediation for a specific constraint