ai-superpower/.ai/instructions/constraints/kubernetes-access.instructions.md

Kubernetes and Helm Access Instructions

🚨 CRITICAL: AI Has NO Cluster Access

AI Assistant does NOT have direct access to Kubernetes clusters

What This Means:

AI cannot interact with live Kubernetes clusters. Only the user can.

kubectl Commands

• ❌ AI CANNOT run: kubectl commands against live clusters
• ✅ AI CAN do: Ask user to run kubectl commands
• ✅ AI CAN do: Explain what kubectl command will do
• ✅ AI CAN do: Show the exact command user should run

Example workflow:

AI: "Please run this command to check pod status:"
kubectl get pods -n monitoring

User: [runs command and shows output]

AI: [analyzes output and provides guidance]

Port-Forwarding Workflow

AI creates curl commands, user handles port-forwards:

1. User runs: kubectl port-forward -n monitoring svc/prometheus 9090:80
2. AI runs: curl http://localhost:9090/api/v1/query?query=...
3. AI analyzes: Results and provides recommendations

Why this pattern:

• AI can make HTTP requests to localhost
• User controls cluster access
• Secure: AI never has cluster credentials

---

🎯 Helm Command Restrictions

What AI CAN Do:

• ✅ helm template - Render manifests locally (no cluster needed)
• ✅ helm show values - Inspect chart values
• ✅ helm show chart - Show chart metadata
• ✅ helm dependency list/update/build - Manage dependencies
• ✅ helm lint - Validate chart structure

Example:

# AI can run these locally:
helm template monitoring . -f values.yaml
helm show values charts/prometheus-*.tgz
helm dependency update

What AI CANNOT Do:

• ❌ helm install - Requires cluster access
• ❌ helm upgrade - Requires cluster access
• ❌ helm uninstall - Requires cluster access
• ❌ helm list - Requires cluster access
• ❌ helm get - Requires cluster access

Instead:

• AI generates the command
• AI explains what it will do
• User runs the command themselves

Example:

AI: "Run this to upgrade the release:"
helm upgrade observability-stack . -n monitoring -f values.yaml -f values.storage.dev.yaml

AI: "This will update the following resources: ..."

---

📊 Debugging Workflow

Check Pod Status:

AI: "Please check pod status:"
User runs: kubectl get pods -n monitoring
User: [shows output]
AI: [analyzes and guides]

Check Pod Logs:

AI: "Please get logs from prometheus pod:"
User runs: kubectl logs -n monitoring deployment/prometheus-server --tail=50
User: [shows output]
AI: [analyzes errors]

Check Events:

AI: "Please check recent events:"
User runs: kubectl get events -n monitoring --sort-by='.lastTimestamp' | tail -20
User: [shows output]
AI: [identifies issues]

Access Service via Port-Forward:

AI: "Please port-forward Prometheus:"
User runs: kubectl port-forward -n monitoring svc/prometheus 9090:80

AI runs: curl http://localhost:9090/api/v1/query?query=up
AI: [analyzes metrics]

---

🔑 Key Principles

1. User has cluster access - AI does not
2. AI asks user to run kubectl/helm - Never assumes access
3. Port-forward pattern - User forwards, AI curls localhost
4. Local operations only - AI uses helm template, not install
5. Analysis role - AI analyzes output user provides

---

✅ Best Practices

• Always explain what command will do before asking user to run it
• Show exact command with all flags
• Ask for relevant output only (use grep/tail to filter)
• Use port-forward + curl instead of kubectl exec
• Generate manifests with helm template for validation

---

❌ Common Mistakes to Avoid

1. Don't try to run kubectl directly
2. Don't assume AI can install Helm releases
3. Don't ask user for cluster credentials
4. Don't suggest kubectl exec with tools that aren't available (see container-limitations.instructions.md)