diff --git a/apps/ARGOCD-MIGRATION.md b/apps/ARGOCD-MIGRATION.md new file mode 100644 index 0000000..0756cee --- /dev/null +++ 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 diff --git a/apps/README.md b/apps/README.md index 0b0bdfa..759efcb 100644 --- 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-.yaml`**: ArgoCD Application manifest that tells ArgoCD to sync the app subdirectory +2. **`/`**: 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: diff --git a/apps/app-argocd.yaml b/apps/app-argocd.yaml index e2724a4..0b68c31 100644 --- 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 diff --git a/apps/app-backup.yaml b/apps/app-backup.yaml new file mode 100644 index 0000000..f7e004b --- /dev/null +++ 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 diff --git a/apps/app-bookstack.yaml b/apps/app-bookstack.yaml new file mode 100644 index 0000000..57b44d4 --- /dev/null +++ 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 diff --git a/apps/app-directus.yaml b/apps/app-directus.yaml new file mode 100644 index 0000000..4fa0353 --- /dev/null +++ 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 diff --git a/apps/app-forgejo.yaml b/apps/app-forgejo.yaml new file mode 100644 index 0000000..1ef0c81 --- /dev/null +++ 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 diff --git a/apps/app-opencloud.yaml b/apps/app-opencloud.yaml new file mode 100644 index 0000000..c3111e0 --- /dev/null +++ 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 diff --git a/apps/app-paperclip.yaml b/apps/app-paperclip.yaml new file mode 100644 index 0000000..3a87ee8 --- /dev/null +++ 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 diff --git a/apps/app-passbolt.yaml b/apps/app-passbolt.yaml new file mode 100644 index 0000000..fb2df57 --- /dev/null +++ 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 diff --git a/apps/app-platform-prod.yaml b/apps/app-platform-prod.yaml new file mode 100644 index 0000000..feaef59 --- /dev/null +++ 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 diff --git a/apps/app-pocket-id.yaml b/apps/app-pocket-id.yaml new file mode 100644 index 0000000..aaa3262 --- /dev/null +++ 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 diff --git a/apps/app-stack-basicstack-de.yaml b/apps/app-stack-basicstack-de.yaml index f86ca50..9ac1c6a 100644 --- 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-.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 diff --git a/apps/app-stalwart.yaml b/apps/app-stalwart.yaml new file mode 100644 index 0000000..2a473fb --- /dev/null +++ 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