homelab/docs/PHASE1-MIGRATION-GUIDE.md

# Phase 1: Migrate 9 Hookless Releases to ArgoCD

## Releases to migrate (no presync/postsync hooks)
1. strimzi-operator
2. kafka-cluster
3. kmsvc-redis
4. queue-crd
5. management-service
6. promtail
7. blackbox-exporter
8. portainer
9. claude-terminal

## Pattern per release

### 1. Create Application in k8s/argocd/apps/

**Helmfile source:**
```yaml
- name: strimzi-operator
  namespace: sqs
  createNamespace: true
  chart: strimzi/strimzi-kafka-operator
  version: 0.46.0
  values:
    - watchNamespaces: ["sqs"]
```

**ArgoCD Application:**
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: strimzi-operator
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "0"
spec:
  project: homelab
  source:
    repoURL: https://strimzi.io/charts/
    chart: strimzi-kafka-operator
    targetRevision: 0.46.0
    helm:
      values: |
        watchNamespaces: ["sqs"]
  destination:
    server: https://kubernetes.default.svc
    namespace: sqs
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
```

### 2. Test ArgoCD application (dry-run)

```bash
# If app created, check diff
kubectl apply -f k8s/argocd/apps/{WAVE}-{RELEASE}.yaml --dry-run=client -o yaml

# Or: use argocd CLI
argocd app diff {RELEASE}  # should be clean (no diffs) if spec matches helmfile
```

### 3. Remove from helmfile

Delete the release block from `helmfile.yaml.gotmpl`, commit.

```bash
# Verify no unintended drift
helmfile diff
```

### 4. Commit

Per-release commit (one app at a time).

## Helmfile → Application mapping

| Helmfile | Chart | Namespace | Version | Wave | Status |
|----------|-------|-----------|---------|------|--------|
| strimzi-operator | strimzi/strimzi-kafka-operator | sqs | 0.46.0 | 0 | TODO |
| kmsvc-redis | bitnami/redis | sqs | 20.6.0 | 0 | TODO |
| prometheus | prometheus-community/kube-prometheus-stack | monitoring | latest | 0 | TODO |
| kafka-cluster | ./k8s/sqs/charts/kafka-cluster | sqs | local | 1 | TODO |
| queue-crd | ./k8s/sqs/charts/queue-crd | sqs | local | 1 | TODO |
| management-service | ./k8s/sqs/charts/management-service | sqs | local | 1 | TODO |
| promtail | grafana/promtail | logging | latest | 1 | TODO |
| blackbox-exporter | prometheus-community/prometheus-blackbox-exporter | monitoring | ~11 | 1 | TODO |
| portainer | portainer/portainer | dashboard | latest | 3 | TODO |
| claude-terminal | ./k8s/dev-tools | dev-tools | local | 3 | TODO |

## Local charts mapping

For local charts (e.g., `./k8s/sqs/charts/kafka-cluster`), use `source.path` instead of `source.chart`:

```yaml
source:
  repoURL: https://forgejo.riotpiao.homelab.com/riotpiao.com/homelab.git
  targetRevision: main
  path: k8s/sqs/charts/kafka-cluster
  helm:
    valueFiles:
      - values.yaml  # or path to values override
```

## Verification

After all 9 releases migrated:

```bash
argocd app list | grep -E "strimzi-operator|kmsvc-redis|prometheus|kafka-cluster|queue-crd|management-service|promtail|blackbox-exporter|portainer|claude-terminal"

# All should show: Synced | Healthy
```

Then:
```bash
helmfile diff  # should show no diffs (these releases removed from helmfile)
```

## Rollback

If an Application breaks the cluster during migration:
1. Keep helmfile release block in git (don't delete until verified)
2. If needed: `helmfile apply -l name={RELEASE}` restores from helmfile
3. Debug the Application spec and retry