diff --git a/apps/pocket-id/MIGRATION.md b/apps/pocket-id/MIGRATION.md new file mode 100644 index 0000000..fd9eace --- /dev/null +++ b/apps/pocket-id/MIGRATION.md @@ -0,0 +1,154 @@ +# Pocket ID Migration to Argo CD - Verification & Rollout + +**Status**: ✅ Manifests committed to Git (commit 794cf51) +**Date**: 2026-07-12 +**Task**: DEV-291 + +## Pre-Migration State (Backed Up) + +All existing manifests have been exported and saved to: +- Location: `/tmp/paperclip-run-dev-291-b33dbd3d-76c-1s9MK2/pocket-id-backup/` +- Includes: deployment, service, PVC, ingress, secrets (with TLS certificate) + +### Current Running State +- Pod: `pocket-id-644b9969b8-4b5fq` - Running (2 restarts, 16h age) +- Service: ClusterIP on 10.97.209.99:1411 +- PVC: `pocket-id-data` - Bound to `pvc-d784e4fc-48e8-464a-8807-cee01ee70e66` (5Gi) +- Ingress: https://auth.basicstack.de (TLS via cert-manager) +- Secrets: `pocket-id-secrets` (managed by SealedSecret), `pocket-id-tls` (managed by cert-manager) + +## Migration Changes + +### Files Added to Git (apps/pocket-id/) +1. **deployment.yaml** - Cleaned manifest for pocket-id deployment +2. **service.yaml** - ClusterIP service definition +3. **pvc.yaml** - PVC with `Delete=false` annotation for safety +4. **ingress.yaml** - Traefik ingress with cert-manager TLS +5. **README.md** - Documentation and safety notes +6. **MIGRATION.md** - This document + +### Files Already in Git +- **pocket-id-secrets-sealed.yaml** - SealedSecret (existed before migration) +- **../app-pocket-id.yaml** - Argo CD Application manifest (existed before) + +### Safety Measures Applied + +1. ✅ **PVC Protection**: Added `argocd.argoproj.io/sync-options: Delete=false` annotation + - Prevents Argo CD from ever deleting the PVC + - Existing volume `pvc-d784e4fc-48e8-464a-8807-cee01ee70e66` will be preserved + +2. ✅ **Secret Management**: + - Existing SealedSecret will continue to manage `pocket-id-secrets` + - TLS secret excluded from Git (managed by cert-manager) + +3. ✅ **Non-Destructive Sync**: + - All manifests match current cluster state + - Argo CD will adopt existing resources without recreation + - No service interruption expected + +4. ✅ **Backup Created**: + - Full export of all resources saved + - Can be restored if needed + +## Rollout Steps + +### Step 1: Refresh Argo CD Application +```bash +# Option A: Wait for automatic refresh (every 3 minutes by default) +# Option B: Manual refresh via UI or CLI +kubectl patch application pocket-id -n argocd -p '{"metadata":{"annotations":{"argocd.argoproj.io/refresh":"hard"}}}' --type merge +``` + +### Step 2: Review Diff in Argo CD UI +1. Open Argo CD UI: https://argocd.basicstack.de (or your Argo CD URL) +2. Navigate to `pocket-id` application +3. Click "APP DIFF" to review changes +4. Expected diff: + - New resources: deployment, service, ingress (should show as "in sync" if they match existing) + - PVC: should show as "synced" with existing resource + - No deletions should be shown + +### Step 3: Sync Application +```bash +# Via kubectl (if you want to trigger sync programmatically) +kubectl patch application pocket-id -n argocd -p '{"operation":{"sync":{"syncStrategy":{"hook":{}}}}}' --type merge + +# OR via Argo CD UI: +# Click "SYNC" button, review the resources to be synced, then "SYNCHRONIZE" +``` + +### Step 4: Verification Checklist + +After sync completes, verify: + +- [ ] Application status is "Healthy" and "Synced" in Argo CD UI +- [ ] Pod is running: `kubectl get pods -n pocket-id` (should still be the same pod) +- [ ] Service endpoints are correct: `kubectl get endpoints -n pocket-id` +- [ ] Ingress is working: `curl -I https://auth.basicstack.de` +- [ ] Web UI is accessible: Open https://auth.basicstack.de in browser +- [ ] Login flow works: Test OIDC login with existing client +- [ ] Admin access works: Verify you can access admin UI with existing credentials +- [ ] OIDC clients preserved: Check that all existing clients are still present +- [ ] No data loss: Verify user accounts and configurations are intact + +### Step 5: Verify GitOps Workflow + +Test that Argo CD is properly managing the deployment: + +```bash +# Make a test change in Git (e.g., add a label to deployment) +# Wait for Argo CD to detect the change (or refresh manually) +# Verify change is applied automatically or shown as "OutOfSync" +``` + +## Rollback Plan + +If issues occur during or after sync: + +### Option 1: Revert Git Commit +```bash +cd stack.basicstack.de +git revert 794cf51 +git push +# Wait for Argo CD to sync the revert +``` + +### Option 2: Manual Restore from Backup +```bash +# Restore from exported manifests in backup directory +kubectl apply -f /tmp/paperclip-run-dev-291-b33dbd3d-76c-1s9MK2/pocket-id-backup/ +``` + +### Option 3: Disable Argo CD Management Temporarily +```bash +# Remove Application from Argo CD (does not delete resources) +kubectl delete application pocket-id -n argocd +# Manually manage resources with kubectl until issue is resolved +``` + +## Success Criteria + +Migration is considered successful when: + +1. ✅ All resources are "Healthy" and "Synced" in Argo CD +2. ✅ https://auth.basicstack.de is accessible and functioning +3. ✅ All existing OIDC clients work without reconfiguration +4. ✅ User login and admin access work as before +5. ✅ No data loss in PVC +6. ✅ Subsequent Git commits to apps/pocket-id/ are automatically detected by Argo CD +7. ✅ No service interruptions occurred during migration + +## Important Notes + +- **DO NOT** manually modify resources in the cluster after Argo CD takes over +- All changes should go through Git commits to apps/pocket-id/ +- The PVC is protected by `Delete=false` but still be careful with any PVC-related changes +- TLS certificate is managed by cert-manager - do not add it to Git +- The ENCRYPTION_KEY must never change - it's needed to decrypt existing data + +## Contact + +If issues arise during rollout: +- Check Argo CD UI for detailed sync status and error messages +- Review pod logs: `kubectl logs -n pocket-id -l app=pocket-id` +- Escalate to CTO agent if automated rollback is needed