From a5486c2ad5894b38d7bacd910837525254cf55d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Irving=20L=C3=B3pez?= <ilopez@coralware.cloud>
Date: Fri, 22 May 2026 16:56:38 -0500
Subject: [PATCH] =?UTF-8?q?sync:=20GOLDEN-PATH-CHART-HOOK-ORDER=20+=20ADDO?=
 =?UTF-8?q?N-PROVISIONER-IMPL=20=E2=80=94=20desde=20coralware/IDP@9f03643?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sincroniza desde el monorepo IDP la corrección del hook-order del ServiceAccount
(hook pre-install/pre-upgrade, weight -5) que destraba el helm install del
golden-path sin --no-hooks. Cierre del 4º gap del pipeline tenant hands-off:
el smoke E2E valida ahora la cadena completa (addon-provisioner materializa
MariaDB; AddonClaim publica DATABASE_URL en apps).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 README.md                                   |  9 ++++++++-
 helm/APP_NAME/templates/deployment.yaml     | 12 +++++-------
 helm/APP_NAME/templates/serviceaccount.yaml | 21 +++++++++++++++++++++
 3 files changed, 34 insertions(+), 8 deletions(-)
 create mode 100644 helm/APP_NAME/templates/serviceaccount.yaml

diff --git a/README.md b/README.md
index 37701ae..2df655f 100644
--- a/README.md
+++ b/README.md
@@ -24,10 +24,17 @@ diseño** — si tu app necesita base de datos, migra al shape
 │   ├── pyproject.toml
 │   ├── requirements.txt
 │   └── Dockerfile
-├── helm/__APP_NAME__/            ← Helm chart minimal (sin hooks)
+├── helm/__APP_NAME__/            ← Helm chart minimal
 └── .gitea/workflows/             ← CI: tests + build + deploy
 ```
 
+> **Hooks Helm:** el `ServiceAccount` se materializa como hook
+> `pre-install,pre-upgrade` (`hook-weight: -5`,
+> `hook-delete-policy: before-hook-creation`) por **paridad** con el shape
+> `web-backend/python`. Este shape no tiene Job de migración, así que el hook
+> no es estrictamente necesario aquí — se mantiene para que ambos charts sean
+> coherentes. `helm upgrade --install` funciona sin `--no-hooks`.
+
 ---
 
 ## Endpoints obligatorios
diff --git a/helm/APP_NAME/templates/deployment.yaml b/helm/APP_NAME/templates/deployment.yaml
index 5a2b722..a319ad2 100644
--- a/helm/APP_NAME/templates/deployment.yaml
+++ b/helm/APP_NAME/templates/deployment.yaml
@@ -60,13 +60,11 @@ spec:
         - name: tmp
           emptyDir: {}
 ---
-apiVersion: v1
-kind: ServiceAccount
-metadata:
-  name: {{ .Release.Name }}
-  labels:
-    {{- include "app.labels" . | nindent 4 }}
----
+# El ServiceAccount {{ .Release.Name }} NO se define aqui — vive en
+# serviceaccount.yaml como hook pre-install/pre-upgrade (hook-weight "-5"),
+# por paridad con el shape web-backend/python. El Deployment lo referencia en
+# `serviceAccountName` y el SA-hook usa `hook-delete-policy: before-hook-creation`
+# para no quedar huerfano entre upgrades.
 apiVersion: v1
 kind: ConfigMap
 metadata:
diff --git a/helm/APP_NAME/templates/serviceaccount.yaml b/helm/APP_NAME/templates/serviceaccount.yaml
new file mode 100644
index 0000000..c95dd7e
--- /dev/null
+++ b/helm/APP_NAME/templates/serviceaccount.yaml
@@ -0,0 +1,21 @@
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ .Release.Name }}
+  labels:
+    {{- include "app.labels" . | nindent 4 }}
+  annotations:
+    # El ServiceAccount se materializa como hook pre-install/pre-upgrade por
+    # PARIDAD con el shape web-backend/python. Este shape NO tiene Job Alembic,
+    # asi que el hook no es estrictamente necesario aqui — pero mantener ambos
+    # charts coherentes reduce la carga cognitiva en debugging y onboarding, y
+    # deja preparado el orden de hooks si en el futuro se agrega un hook que
+    # dependa del SA. Con hook-weight "-5" el SA se aplica antes que cualquier
+    # hook con weight >= 0.
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "-5"
+    # before-hook-creation (NO hook-succeeded): el Deployment de la fase
+    # principal referencia este SA en runtime — debe seguir vivo tras el hook.
+    # before-hook-creation lo borra y recrea solo al inicio del proximo hook,
+    # haciendo el SA-hook idempotente entre upgrades sin dejarlo huerfano.
+    "helm.sh/hook-delete-policy": before-hook-creation