a6eb4da214
- .ai/ instruction set (root, behavior, skills, constraints) - apply.sh workflow documentation (apply.md) - architecture documentation (docs/architecture.md) - .github/copilot-instructions.md for VS Code auto-load - .gitignore (tmp/, .ai-instructions.conf)"
147 lines
3.8 KiB
Markdown
147 lines
3.8 KiB
Markdown
# 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:**
|
|
```bash
|
|
# 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)
|