From c34b58e0b26ff1c2c7aa17956069f133b72c8e7f Mon Sep 17 00:00:00 2001
From: ahmza <hamza@ahmza.com>
Date: Thu, 3 Sep 2026 03:58:47 +0100
Subject: [PATCH] Add cascade-delete finalizer to stateless apps; document the
 distinction

---
 apps/demo.yaml             |  7 +++++++
 apps/longhorn.yaml         |  7 +++++++
 apps/metallb.yaml          |  7 +++++++
 docs/08-adding-new-apps.md | 27 +++++++++++++++++++++++++++
 4 files changed, 48 insertions(+)

diff --git a/apps/demo.yaml b/apps/demo.yaml
index d3ba055..a54dcc1 100644
--- a/apps/demo.yaml
+++ b/apps/demo.yaml
@@ -24,6 +24,13 @@ kind: Application
 metadata:
   name: demo
   namespace: argocd
+  # Without this finalizer, deleting this Application object only makes
+  # Argo CD forget about its resources — the namespace, Deployment, and
+  # Service would keep running, orphaned and unmanaged. This finalizer
+  # makes deletion cascade: remove apps/demo.yaml from Git, and everything
+  # this Application deployed is actually torn down too.
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
 spec:
   project: default
 
diff --git a/apps/longhorn.yaml b/apps/longhorn.yaml
index 4d16a4c..30d0024 100644
--- a/apps/longhorn.yaml
+++ b/apps/longhorn.yaml
@@ -16,6 +16,13 @@ kind: Application
 metadata:
   name: longhorn
   namespace: argocd
+  # Deliberately NO resources-finalizer.argocd.argoproj.io here, unlike
+  # apps/demo.yaml and apps/metallb.yaml. Longhorn's CRDs (Volumes, Replicas,
+  # Engines) represent real data, not just running Pods — cascade-deleting
+  # this Application would tell Longhorn to tear down every volume and
+  # replica in the cluster along with it. Removing apps/longhorn.yaml from
+  # Git should be a rare, deliberate act, confirmed by hand
+  # (see docs/09-growing-up.md), never an accidental one-line prune.
 spec:
   project: default
 
diff --git a/apps/metallb.yaml b/apps/metallb.yaml
index 6b1ee53..f12160a 100644
--- a/apps/metallb.yaml
+++ b/apps/metallb.yaml
@@ -18,6 +18,13 @@ kind: Application
 metadata:
   name: metallb
   namespace: argocd
+  # Without this finalizer, deleting this Application object only makes
+  # Argo CD forget about its resources — MetalLB's Pods, CRDs, and our
+  # BGPPeer/BGPAdvertisement would keep running, orphaned. This finalizer
+  # makes deletion cascade properly. Safe here because MetalLB holds no
+  # data of its own — contrast with apps/longhorn.yaml below.
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
 spec:
   project: default
 
diff --git a/docs/08-adding-new-apps.md b/docs/08-adding-new-apps.md
index 0da14c9..08b9811 100644
--- a/docs/08-adding-new-apps.md
+++ b/docs/08-adding-new-apps.md
@@ -88,6 +88,33 @@ addresses listed in [`docs/network.md`](network.md), and add a row for it
 there once it's up — that file only stays useful if every app that gets an
 address shows up in it.
 
+## Removing an app
+
+The reverse of adding one: delete `apps/<name>.yaml` and `apps/<name>/`,
+commit, and push. The app-of-apps notices the missing Application manifest
+and prunes the `Application` object itself — but that alone does **not**
+delete what that Application deployed. Argo CD only cascades an
+Application's deletion into deleting its managed resources (namespace,
+Deployment, Service, everything) if that Application carries this
+finalizer:
+
+```yaml
+metadata:
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+```
+
+Without it, the resources are simply orphaned — still running, but no
+longer tracked by Argo CD or described anywhere in Git. `apps/demo.yaml`
+and `apps/metallb.yaml` both carry this finalizer. `apps/longhorn.yaml`
+deliberately does **not** — see the comment in that file for why cascading
+a storage layer's deletion is a different, much higher-stakes decision than
+cascading a stateless app's.
+
+> **Ask Claude:** "what would happen right now if I deleted
+> `apps/longhorn.yaml` and it had this finalizer?" before you ever add one
+> to an app that holds real data.
+
 ## Checklist
 
 - [ ] New app's manifests live in `apps/<name>/`