docs(phase1): create migration guide for 9 hookless releases
Detailed Phase 1 workflow: - Template Application spec (Helm source, values, sync policy) - Per-release migration pattern (create → test → remove → commit) - Helmfile ↔ ArgoCD mapping table - Local chart handling (source.path vs source.chart) - Verification checklist - Rollback instructions Reference: execute one release at a time, verify before next.
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user