diff --git a/docs/PHASE1-MIGRATION-GUIDE.md b/docs/PHASE1-MIGRATION-GUIDE.md new file mode 100644 index 0000000..7d567ef --- /dev/null +++ b/docs/PHASE1-MIGRATION-GUIDE.md @@ -0,0 +1,130 @@ +# 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