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:

- name: strimzi-operator
  namespace: sqs
  createNamespace: true
  chart: strimzi/strimzi-kafka-operator
  version: 0.46.0
  values:
    - watchNamespaces: ["sqs"]

ArgoCD Application:

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)

# 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.

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

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:

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:

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