From f3319c753c8cbd622d96db669d74238fd52971a7 Mon Sep 17 00:00:00 2001
From: Erich Blume <blume.erich@gmail.com>
Date: Wed, 11 Feb 2026 21:10:42 -0800
Subject: [PATCH] Update deploy-k8s-service doc with ProxyGroup ingress pattern
 (#166)

## Summary
- Updated the "Configure Ingress" section to use the current ProxyGroup pattern (`proxy-group: "ingress"`, `defaultBackend`, `tls.hosts`)
- Replaced the old per-ingress proxy example that used `rules:` with `host:` (which breaks ProxyGroup routing)
- Added key points explaining why `defaultBackend` is required and what each annotation does
- Updated checklist to mention ProxyGroup

## Test plan
- [ ] Review rendered doc for accuracy against existing ingress manifests

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/166
---
 .../docs-update-deploy-k8s-ingress.doc.md     |  1 +
 docs/how-to/deploy-k8s-service.md             | 34 +++++++++++--------
 2 files changed, 20 insertions(+), 15 deletions(-)
 create mode 100644 docs/changelog.d/docs-update-deploy-k8s-ingress.doc.md

diff --git a/docs/changelog.d/docs-update-deploy-k8s-ingress.doc.md b/docs/changelog.d/docs-update-deploy-k8s-ingress.doc.md
new file mode 100644
index 0000000..b6f35f8
--- /dev/null
+++ b/docs/changelog.d/docs-update-deploy-k8s-ingress.doc.md
@@ -0,0 +1 @@
+Update "Deploy K8s Service" how-to with current ProxyGroup ingress pattern.
diff --git a/docs/how-to/deploy-k8s-service.md b/docs/how-to/deploy-k8s-service.md
index 1d6a692..ed42912 100644
--- a/docs/how-to/deploy-k8s-service.md
+++ b/docs/how-to/deploy-k8s-service.md
@@ -1,6 +1,6 @@
 ---
 title: Deploy K8s Service
-modified: 2026-02-07
+modified: 2026-02-11
 tags:
   - how-to
   - kubernetes
@@ -47,15 +47,17 @@ spec:
 
 ## Configure Ingress
 
-Add [[tailscale-operator|Tailscale Ingress]] with Homepage annotations:
+Add a [[tailscale-operator|Tailscale Ingress]] routed through the ProxyGroup with Homepage annotations:
 
 ```yaml
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
-  name: <service>
+  name: <service>-tailscale
   namespace: <service>
   annotations:
+    tailscale.com/proxy-class: "default"
+    tailscale.com/proxy-group: "ingress"
     gethomepage.dev/enabled: "true"
     gethomepage.dev/name: "Service Name"
     gethomepage.dev/group: "Apps"
@@ -64,19 +66,21 @@ metadata:
     gethomepage.dev/pod-selector: "app=<service>"
 spec:
   ingressClassName: tailscale
-  rules:
-  - host: <service>
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: <service>
-            port:
-              number: 80
+  defaultBackend:
+    service:
+      name: <service>
+      port:
+        number: 80
+  tls:
+    - hosts:
+        - <service>
 ```
 
+Key points:
+- **`proxy-group: "ingress"`** routes through the shared ProxyGroup instead of spawning a per-ingress proxy
+- **Do not use `rules:` with `host:`** — the ProxyGroup proxy receives the FQDN as Host header (e.g. `<service>.tail8d86e.ts.net`), so a short `host: <service>` won't match. Use `defaultBackend` instead.
+- **`tls.hosts`** sets the MagicDNS hostname (becomes `<service>.tail8d86e.ts.net`)
+
 ## Add Caddy Route (if needed)
 
 If other pods need to access the service, add to `ansible/roles/caddy/defaults/main.yml`:
@@ -114,7 +118,7 @@ argocd app sync <service>
 
 - [ ] Manifests in `argocd/manifests/<service>/`
 - [ ] Application in `argocd/apps/<service>.yaml`
-- [ ] Tailscale Ingress with Homepage annotations
+- [ ] Tailscale Ingress via ProxyGroup with Homepage annotations
 - [ ] Caddy route (if pod-to-service access needed)
 - [ ] Tested on feature branch
 - [ ] PR reviewed and merged