96 lines
3 KiB
Markdown
96 lines
3 KiB
Markdown
|
# ArgoCD Application Sync Migration
|
||
|
|
|
||
|
|
**Date**: 2026-07-12
|
||
|
|
**Issue**: DEV-287
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
Migrated from a single complex recursive directory sync (`app-stack-basicstack-de.yaml`) to individual Application manifests for each app. This provides:
|
||
|
|
|
||
|
|
- Better visibility into each application's sync status
|
||
|
|
- Individual control over sync policies per application
|
||
|
|
- Easier troubleshooting and management
|
||
|
|
- Clearer application boundaries
|
||
|
|
|
||
|
|
## Changes Made
|
||
|
|
|
||
|
|
### 1. Created Individual Application Manifests
|
||
|
|
|
||
|
|
Created `app-*.yaml` files for each application with auto-sync DISABLED:
|
||
|
|
|
||
|
|
- `app-backup.yaml`
|
||
|
|
- `app-bookstack.yaml`
|
||
|
|
- `app-directus.yaml`
|
||
|
|
- `app-forgejo.yaml`
|
||
|
|
- `app-opencloud.yaml`
|
||
|
|
- `app-paperclip.yaml`
|
||
|
|
- `app-passbolt.yaml`
|
||
|
|
- `app-platform-prod.yaml`
|
||
|
|
- `app-pocket-id.yaml`
|
||
|
|
- `app-stalwart.yaml`
|
||
|
|
|
||
|
|
### 2. Disabled Auto-Sync on ArgoCD App
|
||
|
|
|
||
|
|
Updated `app-argocd.yaml` to remove auto-sync (manual control during migration).
|
||
|
|
|
||
|
|
### 3. Disabled Complex Stack Sync
|
||
|
|
|
||
|
|
Commented out `app-stack-basicstack-de.yaml` to prevent the old recursive sync.
|
||
|
|
|
||
|
|
## Migration Steps
|
||
|
|
|
||
|
|
### Phase 1: Repository Update (DONE)
|
||
|
|
|
||
|
|
✅ Create individual app manifests
|
||
|
|
✅ Disable auto-sync on all apps
|
||
|
|
✅ Disable old stack-basicstack-de sync
|
||
|
|
|
||
|
|
### Phase 2: Apply New Applications (NEXT)
|
||
|
|
|
||
|
|
For each application, we need to:
|
||
|
|
|
||
|
|
1. **Apply the new Application manifest** to ArgoCD
|
||
|
|
2. **Wait for ArgoCD to detect it** (should show as OutOfSync initially)
|
||
|
|
3. **Sync the application** to match current k8s state
|
||
|
|
4. **Verify health** and that no resources were pruned/changed unexpectedly
|
||
|
|
5. **Enable auto-sync** once verified
|
||
|
|
|
||
|
|
### Phase 3: Delete Old Stack Sync
|
||
|
|
|
||
|
|
Once all individual apps are healthy:
|
||
|
|
|
||
|
|
1. Delete the `stack-basicstack-de` Application from ArgoCD: `kubectl delete application stack-basicstack-de -n argocd`
|
||
|
|
2. Verify that individual apps remain healthy
|
||
|
|
3. Remove the commented `app-stack-basicstack-de.yaml` file
|
||
|
|
|
||
|
|
### Phase 4: Enable Auto-Sync
|
||
|
|
|
||
|
|
For each application that's complete and stable:
|
||
|
|
|
||
|
|
1. Update its `app-*.yaml` to add automated sync policy
|
||
|
|
2. Commit and let ArgoCD apply the change
|
||
|
|
|
||
|
|
## Safety Considerations
|
||
|
|
|
||
|
|
- ✅ Old sync is disabled before new apps are applied (prevents conflicts)
|
||
|
|
- ✅ Auto-sync disabled on all new apps (manual control during migration)
|
||
|
|
- ✅ Each app can be verified individually before proceeding
|
||
|
|
- ⚠️ Do NOT delete the old `stack-basicstack-de` Application until all new apps are healthy
|
||
|
|
|
||
|
|
## Per-Application Tasks
|
||
|
|
|
||
|
|
Each application needs completion work tracked in separate issues:
|
||
|
|
|
||
|
|
1. **Verify manifests are complete** - Check that all necessary K8s resources are in the app directory
|
||
|
|
2. **Test manual sync** - Ensure the app syncs correctly and matches current state
|
||
|
|
3. **Verify health** - Check that application is Healthy in ArgoCD
|
||
|
|
4. **Enable auto-sync** - Update app manifest to add automated sync policy
|
||
|
|
5. **Monitor** - Watch for any issues after enabling auto-sync
|
||
|
|
|
||
|
|
## Current Status
|
||
|
|
|
||
|
|
- [x] Phase 1: Repository updated with individual app manifests
|
||
|
|
- [ ] Phase 2: Apply new applications and verify
|
||
|
|
- [ ] Phase 3: Delete old stack sync
|
||
|
|
- [ ] Phase 4: Enable auto-sync on verified apps
|