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:**

```bash
# 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:**

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

**Instead, SHOW the command and wait:**

```bash
# ✅ 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

```bash
git status
git diff
git diff values.yaml
```

### Restore File from Git

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

### View Git History

```bash
git log --oneline -20
git log --oneline --graph --all
```

### Test Helm Template

```bash
# 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.)

```bash
# 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):**
```bash
# 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**:

```bash
# 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

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

### View Logs

```bash
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

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

### Port Forwarding

```bash
# 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)

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

### OpenShift (values.openshift.yaml)

```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