propt

Pre-action operational intelligence for Kubernetes. propt wraps kubectl transparently — mutating commands (delete, scale, apply, patch, edit, replace, rollout) get a real, live-cluster impact check and a Execute? [y/N] prompt first. Read-only commands pass straight through with zero overhead.

Built on real open-source signals, not a hardcoded risk table:

• kubernetes Python client — live resource discovery
• networkx — dependency graph from real ownerReferences and label-selector matching (no invented relationships)
• Popeye (derailed/popeye) — real, actively-maintained cluster sanitizer, used as the operational risk knowledge source
• metrics-server (optional) — real CPU usage, if installed

Every decision is also logged as an auditable record to Amazon S3 via boto3 — see AWS integration below.

---

1. Install (Windows 11 / PowerShell)

Python dependencies

cd propt
pip install -e .
pip install pytest

Popeye (Windows binary, no Go toolchain needed)

1. Go to https://github.com/derailed/popeye/releases
2. Download the latest popeye_Windows_x86_64.tar.gz (or .zip if offered)
3. Extract popeye.exe somewhere on your PATH, e.g. C:\tools\popeye.exe
4. Verify: popeye version

If Popeye isn't found on PATH, propt still works — it just reports "popeye not available" in the Unknown/missing context section instead of fabricating findings.

Cluster

Make sure kubectl points at your minikube cluster:

minikube status
kubectl get nodes

metrics-server (optional, for real load data)

minikube addons enable metrics-server

AWS (for audit logging)

propt writes every decision it makes to an S3 bucket as a timestamped JSON record, using your existing AWS CLI credentials (via boto3 — no keys are stored or handled by propt itself).

aws configure          # if not already set up
aws s3 mb s3://<your-bucket-name> --region ap-south-1

Set the bucket name propt should use (defaults to propt-audit-logs-sid-2026 if unset):

$env:PROPT_AUDIT_BUCKET = "<your-bucket-name>"

If AWS isn't configured, propt still works — audit logging fails silently rather than blocking the actual kubectl operation.

---

2. Verify it's wired up

pytest

These tests mock the cluster so they run without one — they document expected behavior (see tests/test_engine.py). The real proof is the live demo below.

---

3. Set up the demo scenario

Deploy two contrasting workloads into your cluster:

kubectl create deployment payment-api --image=nginx --replicas=3
kubectl create deployment worker --image=nginx --replicas=10
kubectl expose deployment payment-api --port=80 --name=payment-api

# Simulate the understaffed condition
kubectl scale deployment payment-api --replicas=3
kubectl delete pod <one-of-the-payment-api-pods>   # bring it to 2/3 without propt, to set the stage

(Or just let propt itself do the second delete below — the first manual delete above is only to establish the "already short one replica" starting condition for the demo.)

4. Run it

propt kubectl delete pod <another-payment-api-pod-name>

Expect: HIGH POTENTIAL IMPACT — evidence should show available replicas below desired, plus any live Popeye findings for that deployment.

propt kubectl delete pod <a-worker-pod-name>

Expect: NONE / low impact — same engine, different live state, different conclusion.

propt kubectl get pods

Expect: passes straight through immediately, no analysis, no prompt.

---

Architecture

kubectl command
      |
      v
Common Change Model (propt/parser.py)
      |
      v
Live Resource Graph (propt/k8s_graph.py) --- built from real ownerReferences + selectors
      |
      v
Impact Inference Engine (propt/engine.py) --- combines graph + Popeye findings + metrics
      |
      v
Explanation (propt/explain.py) --- printed to terminal, evidence-based, no opaque score
      |
      v
Execute? [y/N] --- human decides
      |
      +---> Audit record written to Amazon S3 (propt/audit.py, via boto3)
      |
      v
propt runs the ORIGINAL kubectl command as-is

AWS integration: audit logging

Every impact decision — the command, the target, the evidence, the consequence text, and whether the engineer chose to proceed — is written to Amazon S3 as a timestamped JSON object under decisions/<timestamp>.json. This gives a team a real, queryable history of infrastructure decisions and their reasoning, matching the "auditable, trust-first" principle from the original project spec (never silently change policy; keep evidence and outcomes reviewable).

Example record:

{
  "timestamp": "2026-09-20T06:48:43.005997+00:00",
  "command": "delete pod payment-api-85648675fb-6bj46",
  "target": "pod/payment-api-85648675fb-6bj46",
  "impact_level": "HIGH",
  "evidence": ["deployment/payment-api: available replicas (5) below desired (6)"],
  "consequence": "Potential reduction in capacity or degraded state propagating to: deployment/payment-api, replicaset/payment-api-85648675fb, service/payment-api.",
  "executed": false
}

Audit logging is intentionally fire-and-forget: if AWS credentials aren't configured or S3 is unreachable, propt degrades silently and the actual kubectl workflow is never blocked.

What this is not (by design, for the hackathon scope)

• Not tied to a hardcoded command→risk table — risk comes from live cluster state + Popeye's real findings.
• Not a live "traffic" simulator — if metrics-server isn't installed, it says so rather than inventing a number.
• No LLM reasoning layer, no multi-provider adapters (Terraform etc.), no auth/security hardening — explicitly out of scope for this build, same as the original project spec.