ai-superpower/.ai/QUICK-REFERENCE.md

AI Quick Reference - kube-log Project

🚫 Cluster Access Restrictions

AI Assistant does NOT have direct access to Kubernetes clusters:

• ❌ CANNOT run: kubectl commands against live clusters
• ❌ CANNOT run: helm install/upgrade to live clusters
• ✅ CAN run: helm template (renders manifests locally)
• ✅ CAN run: helm show values (inspects charts)
• ✅ CAN run: helm dependency commands (manages chart dependencies)

Why:

• User manages cluster access and credentials
• Prevents accidental changes to production clusters
• User controls when and how deployments happen

What AI can do:

1. Generate manifests with helm template
2. Show what would be deployed
3. Analyze chart configurations
4. Suggest kubectl/helm commands for user to run

What user does:

1. Run kubectl/helm commands themselves
2. Verify changes before applying
3. Control deployment timing
4. Manage cluster credentials

---

🏢 OpenShift Deployments

OpenShift installations are done via ArgoCD from the IaC repository:

• Local dev repo: ~/koodi/niko-dev/kube-log/
• IaC repo: ~/koodi/niko-dev/IaC/kube-log/
• Deployment method: ArgoCD points to IaC repo

Customer-specific file:

• values.storage.openshift.dev.yaml exists in IaC repo (customer side)
• Contains: volume sizes and storageClass settings
• Example: storageClass: "ocs-storagecluster-cephfs"
• This file is NOT synced from local dev repo (customer maintains it)

When debugging OpenShift issues:

1. Check ArgoCD sync status
2. Verify customer's values.storage.openshift.dev.yaml exists
3. Ensure values.openshift.yaml is in IaC repo
4. Remember: OpenShift uses SCC (Security Context Constraints), not PSP

---

🔄 Syncing to IaC Repository

When requested to sync changes to the IaC repository:

# Siirry projektin juureen
cd /Users/moilanik/koodi/niko-dev

# Kopioi kaikki paitsi .ai kansio, CLAUDE.md ja IaC-spesifiset tiedostot
rsync -av --delete \
  --exclude='.ai/' \
  --exclude='.github/' \
  --exclude='CLAUDE.md' \
  --exclude='.git/' \
  --exclude='tmp/' \
  --exclude='values.storage.openshift.dev.yaml' \
  kube-log/ IaC/kube-log/

# Tarkista muutokset
cd IaC/kube-log && git status

What this does:

• Syncs all kube-log changes to separate IaC git repository
• Excludes .ai/ (AI guidelines - not needed in production repo)
• Excludes CLAUDE.md (AI guidelines - kept local only)
• Excludes .git/ (each repo has its own git history)
• Excludes tmp/ (temporary files)
• Excludes values.storage.openshift.dev.yaml (IaC-only file, customer specific)
• --delete removes files from IaC that were deleted from kube-log

When to sync:

• After significant changes to templates, values files, or documentation
• Before committing to IaC repository
• When owner requests: "synkkaa IaC" or similar

IMPORTANT: User will commit and push in IaC repo themselves!

---

🚨 Git Commands - DO NOT RUN

These commands are FORBIDDEN without explicit permission:

# ❌ DO NOT RUN THESE:
git add .
git commit -m "..."
git push
git push --force
git reset --hard

Instead, SHOW the command and wait:

# ✅ Show this to user:
echo "Run this command:"
echo "git add ."
echo "git commit -m 'your message'"
echo "git push"

---

🎯 Common Tasks

Check What Changed

git status
git diff
git diff values.yaml

Restore File from Git

# Show command, don't run:
git checkout <commit-hash> -- <file-path>

View Git History

git log --oneline -20
git log --oneline --graph --all

Test Helm Template

# K8s
helm template . --name-template monitoring --namespace kube-log \
  -f values.yaml -f values.storage.dev.yaml

# OpenShift
helm template . --name-template monitoring --namespace kube-log \
  -f values.yaml -f values.storage.dev.yaml -f values.openshift.yaml

---

📋 Installation Commands

Standard Kubernetes (K3s, etc.)

# Dev environment
helm upgrade --install kube-log . --namespace kube-log --create-namespace \
  -f values.yaml -f values.storage.dev.yaml

# Production
helm upgrade --install kube-log . --namespace kube-log --create-namespace \
  -f values.yaml -f values.storage.prod.yaml

OpenShift

OpenShift deployments are managed via ArgoCD from IaC repo:

• ArgoCD points to: ~/koodi/niko-dev/IaC/kube-log/
• Uses: values.yaml, values.storage.openshift.dev.yaml, values.openshift.yaml

Manual installation (for testing only):

# Dev environment
helm upgrade --install kube-log . --namespace kube-log --create-namespace \
  -f values.yaml -f values.storage.openshift.dev.yaml -f values.openshift.yaml

# Production
helm upgrade --install kube-log . --namespace kube-log --create-namespace \
  -f values.yaml -f values.storage.openshift.prod.yaml -f values.openshift.yaml

Known Issue: First Installation

First installation may fail with ConfigMap/ServiceAccount error. Just run the same command twice:

# First run (may fail)
helm upgrade --install kube-log . --namespace kube-log -f values.yaml -f values.storage.dev.yaml

# Second run (works)
helm upgrade --install kube-log . --namespace kube-log -f values.yaml -f values.storage.dev.yaml

---

🔍 Debugging

Check Pod Status

kubectl get pods -n kube-log
kubectl get pods -n kube-log -w  # Watch mode

View Logs

kubectl logs -n kube-log deployment/kube-log-minio
kubectl logs -n kube-log deployment/kube-log-minio --tail=50
kubectl logs -n kube-log kube-log-loki-0

Check PVCs

kubectl get pvc -n kube-log
kubectl describe pvc -n kube-log kube-log-minio

Port Forwarding

# MinIO
kubectl port-forward -n kube-log svc/kube-log-minio 9000:9000

# Grafana
kubectl port-forward -n kube-log svc/kube-log-grafana 3000:80

# Prometheus
kubectl port-forward -n kube-log svc/kube-log-prometheus-server 9090:80

# Loki
kubectl port-forward -n kube-log svc/kube-log-loki 3100:3100

---

🗂️ File Structure

kube-log/
├── .ai/                          # AI guidelines (not in git)
│   ├── README.md                 # Main collaboration rules
│   └── QUICK-REFERENCE.md        # This file
├── charts/                       # Helm dependencies (tgz)
├── templates/                    # Kubernetes manifests
├── files/                        # Config files, dashboards
│   ├── dashboards/              # Grafana dashboards
│   └── grafana-alloy-config.river
├── values.yaml                   # K8s baseline config
├── values.openshift.yaml         # OpenShift overrides (if exists)
├── values.storage.dev.yaml       # Dev storage config
├── values.storage.prod.yaml      # Prod storage config
└── README.md                     # Main documentation

---

💡 MinIO Buckets

Default buckets (created automatically):

• loki-storage - Loki chunks and indexes
• prometheus-metrics - Prometheus long-term storage (Thanos)
• tempo-traces - Tempo distributed tracing

Credentials (POC):

• Username: admin
• Password: password123

---

🔐 Security Context Patterns

Kubernetes (values.yaml)

securityContext:
  enabled: true
  runAsUser: 1000
  runAsGroup: 1000
  fsGroup: 1000
  runAsNonRoot: true

OpenShift (values.openshift.yaml)

securityContext:
  enabled: false  # Let SCC inject

---

📝 Remember

• NEVER run git commands without permission
• ALWAYS show git diff before suggesting commits
• ASK if uncertain
• MINIMAL changes only
• TEST with helm template before installing

---

Last Updated: 2025-11-05 Project Owner: Controls all git operations AI Role: Analyze, suggest, show commands - never execute git operations