From e5c018ce8fd0089e11bf4c9b85e2b4ce28db1691 Mon Sep 17 00:00:00 2001
From: ahmza <hamza@ahmza.com>
Date: Thu, 3 Sep 2026 05:29:05 +0100
Subject: [PATCH] Make Ingress the default path for reaching new apps

---
 docs/08-adding-new-apps.md | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/docs/08-adding-new-apps.md b/docs/08-adding-new-apps.md
index 08b9811..7e9140c 100644
--- a/docs/08-adding-new-apps.md
+++ b/docs/08-adding-new-apps.md
@@ -82,11 +82,26 @@ syntax required in the Application resource itself.
 > ready to try one of your own — `apps/metallb/` is a real template to
 > copy from.
 
-If the new app has its own `LoadBalancer` Service (see
-[`docs/05-metallb.md`](05-metallb.md)), pick its address from the free
-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.
+## Reaching a new app: Ingress first, dedicated address only if you must
+
+Now that [`docs/11-ingress.md`](11-ingress.md) is set up, that's the
+default way a new app should become reachable — not its own
+`LoadBalancer` Service. Give it a plain `ClusterIP` Service (the default
+if you omit `type` entirely, as in [`apps/demo/service.yaml`](../apps/demo/service.yaml)),
+add an `Ingress` for a real hostname (see [`apps/demo/ingress.yaml`](../apps/demo/ingress.yaml)),
+and add the `cert-manager.io/cluster-issuer: letsencrypt-staging` annotation
+to get it a real HTTPS certificate — proven against staging first, then
+switched to `letsencrypt-prod` once confirmed (see
+[`docs/12-cert-manager.md`](12-cert-manager.md)). Record the new hostname
+in the hostnames table in [`docs/network.md`](network.md).
+
+A dedicated `type: LoadBalancer` Service (see
+[`docs/05-metallb.md`](05-metallb.md)) is still the right choice for an app
+that genuinely can't speak HTTP — a raw TCP or UDP service, for example,
+since Ingress only routes HTTP(S). If you do need one, pick its address
+from the free 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
 
@@ -123,7 +138,11 @@ cascading a stateless app's.
       a placeholder
 - [ ] Pushed to Git
 - [ ] `argocd app list` shows the new app, `Synced`/`Healthy`
-- [ ] If it has a `LoadBalancer` Service, its address is recorded in `docs/network.md`
+- [ ] Reachable through Ingress at a real hostname (recorded in
+      `docs/network.md`'s hostnames table), unless it genuinely can't
+      speak HTTP
+- [ ] If it does need its own dedicated `LoadBalancer` Service instead, its
+      address is recorded in `docs/network.md`
 
 Continue to [`docs/09-growing-up.md`](09-growing-up.md) for what to add
 next as this cluster grows beyond a learning setup.