ArgoCD: Replace complex stack sync with individual application syncs

Migrated from single recursive directory sync to individual Application manifests for better control and visibility. Changes: - Created app-*.yaml for each application (10 apps) - Disabled auto-sync on all apps for safe migration - Disabled old app-stack-basicstack-de.yaml complex sync - Updated app-argocd.yaml to disable auto-sync during migration - Added ARGOCD-MIGRATION.md with migration plan and next steps - Updated apps/README.md to document new structure Each app now needs: 1. Manual sync verification 2. Health check 3. Auto-sync enablement (tracked in separate tasks) Related: DEV-287 Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-07-12 10:44:41 +00:00 · 2026-07-12 10:44:41 +00:00 · f0dd8d8d04
commit f0dd8d8d04
parent 08292bd449
14 changed files with 301 additions and 25 deletions
--- a/apps/ARGOCD-MIGRATION.md
+++ b/apps/ARGOCD-MIGRATION.md
@ -0,0 +1,95 @@
+# 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
--- a/apps/README.md
+++ b/apps/README.md
@ -2,6 +2,16 @@

 This directory contains deployment configurations for all applications running on the basicstack.de cluster.

+## ArgoCD Application Management
+
+Each application has two types of files:
+
+1. **`app-<name>.yaml`**: ArgoCD Application manifest that tells ArgoCD to sync the app subdirectory
+2. **`<name>/`**: Application-specific Kubernetes manifests and configuration
+
+The `app-*.yaml` files are synced by ArgoCD and create/manage the corresponding Application resources.
+Each application's manifests in its subdirectory are then synced by its Application resource.
+
 ## Structure

 Each application should have its own subdirectory containing:
--- a/apps/app-argocd.yaml
+++ b/apps/app-argocd.yaml
@ -13,9 +13,6 @@ spec:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
-    automated:
-      prune: false  # Manual approval for deletions
-      selfHeal: true
    syncOptions:
    - CreateNamespace=true
    - ServerSideApply=true
--- a/apps/app-backup.yaml
+++ b/apps/app-backup.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: backup
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/backup
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: backup
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-bookstack.yaml
+++ b/apps/app-bookstack.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: bookstack
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/bookstack
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: bookstack
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-directus.yaml
+++ b/apps/app-directus.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: directus
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/directus
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: directus
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-forgejo.yaml
+++ b/apps/app-forgejo.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: forgejo
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/forgejo
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: forgejo
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-opencloud.yaml
+++ b/apps/app-opencloud.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: opencloud
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/opencloud
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: opencloud
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-paperclip.yaml
+++ b/apps/app-paperclip.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: paperclip
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/paperclip
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: paperclip
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-passbolt.yaml
+++ b/apps/app-passbolt.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: passbolt
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/passbolt
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: passbolt
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-platform-prod.yaml
+++ b/apps/app-platform-prod.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: platform-prod
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/platform-prod
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: platform-prod
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-pocket-id.yaml
+++ b/apps/app-pocket-id.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: pocket-id
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/pocket-id
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: pocket-id
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
--- a/apps/app-stack-basicstack-de.yaml
+++ b/apps/app-stack-basicstack-de.yaml
@ -1,22 +1,26 @@
-apiVersion: argoproj.io/v1alpha1
-kind: Application
-metadata:
-  name: stack-basicstack-de
-  namespace: argocd
-spec:
-  project: default
-  source:
-    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
-    targetRevision: main
-    path: apps
-    directory:
-      recurse: true
-      exclude: 'argocd/**'
-  destination:
-    server: https://kubernetes.default.svc
-  syncPolicy:
-    automated:
-      prune: false  # Manual approval for deletions
-      selfHeal: true
-    syncOptions:
-    - CreateNamespace=true
+# DISABLED: Replaced with individual app syncs (see app-*.yaml files)
+# This complex recursive sync has been decomposed into individual application syncs
+# for better control and visibility. Each app now has its own app-<name>.yaml file.
+#
+# apiVersion: argoproj.io/v1alpha1
+# kind: Application
+# metadata:
+#   name: stack-basicstack-de
+#   namespace: argocd
+# spec:
+#   project: default
+#   source:
+#     repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+#     targetRevision: main
+#     path: apps
+#     directory:
+#       recurse: true
+#       exclude: 'argocd/**'
+#   destination:
+#     server: https://kubernetes.default.svc
+#   syncPolicy:
+#     automated:
+#       prune: false  # Manual approval for deletions
+#       selfHeal: true
+#     syncOptions:
+#     - CreateNamespace=true
--- a/apps/app-stalwart.yaml
+++ b/apps/app-stalwart.yaml
@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: stalwart
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/stalwart
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: stalwart
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true