feat: AddonClaim + InitContainer wait-for-secret en chart helm

Cierra GOLDEN-PATH-ADDONCLAIM-MISSING (P0 hands-off pipeline).

Cambios:
- helm/APP_NAME/templates/addonclaim.yaml (NEW): hook pre-install/pre-upgrade
  weight -10, SIN delete-policy (sobrevive upgrades, evita disparar finalizer
  cleanup-logical). Gated por .Values.database.enabled (default true).
- helm/APP_NAME/templates/role-db-secret-reader.yaml (NEW): Role + RoleBinding
  weight -7 que permite al SA leer el Secret <release>-db-creds. Lo consume
  el InitContainer wait-for-secret del Job Alembic.
- helm/APP_NAME/templates/job-alembic-upgrade.yaml: gated por
  database.enabled, anade InitContainer wait-for-secret (48x5s=240s) que
  espera a que addon-provisioner publique el Secret tras reconciliar el
  AddonClaim. Absorbe la latencia del @kopf.timer (RECONCILE_INTERVAL 300s
  + initial_delay 60s) sin tocar el operator.
- helm/APP_NAME/values.yaml: bloque database completo (enabled, addonType,
  databaseName, user.permissions, deletionPolicy Retain). Opt-out con
  database.enabled=false + alembic.enabled=false.
- .gitea/workflows/APP_NAME-build.yaml: helm timeout 5m -> 7m (margen para
  reconcile addon-provisioner + StatefulSet ready + DDL Job + Alembic).
- claim-mariadb.yaml (DELETED): obsoleto - estaba en la raiz del template
  y nunca se renderizaba por helm. Reemplazado por addonclaim.yaml dentro
  del chart helm.
- README.md: documenta nueva tabla de hook weights, opt-out database, y
  trade-off del orphan AddonClaim post-uninstall (cleanup explicito).

Decision arquitectural: Opcion D modificada (Opus 4.6 consult).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

helm/APP_NAME/templates/addonclaim.yaml

@@ -0,0 +1,39 @@
+{{- if .Values.database.enabled }}
+# AddonClaim — declara la intencion de la app de tener una BD (default MariaDB).
+# Lo materializa addon-provisioner (CRD idp.coralware.cloud/v1alpha1):
+#   - reconcilia este claim cada RECONCILE_INTERVAL (default 300s) por TenantProfile.
+#   - crea BD logica + user + grant via Job DDL efimero en el cluster tenant.
+#   - publica el Secret `{{ .Values.database.secretName }}` en este ns (`apps`)
+#     con DATABASE_URL / DATABASE_HOST / DATABASE_PORT / DATABASE_USER /
+#     DATABASE_PASSWORD / DATABASE_NAME (contrato §2.3 del OpenSpec).
+#
+# Ordering con los hooks del chart (clave para que Alembic encuentre el Secret):
+#   weight -10 (este AddonClaim)
+#     -> weight -5 (ServiceAccount)
+#       -> weight 0 (Job Alembic — espera al Secret via InitContainer wait-for-secret)
+#
+# delete-policy: NO se declara intencionalmente.
+#   - Asi el AddonClaim sobrevive entre `helm upgrade` (re-apply idempotente).
+#   - Evita disparar el finalizer `cleanup-logical` en cada upgrade (que dropearia
+#     el user y regeneraria el password, causando ventana de downtime).
+#   - Trade-off documentado: `helm uninstall` deja el AddonClaim orfano y MariaDB
+#     sigue aprovisionada. Es coherente con `deletionPolicy: Retain` (default):
+#     borrar BD productiva debe ser decision explicita, no side-effect del uninstall.
+#     Cleanup explicito: `kubectl delete addonclaim {{ .Release.Name }}-db -n apps`.
+apiVersion: idp.coralware.cloud/v1alpha1
+kind: AddonClaim
+metadata:
+  name: {{ .Release.Name }}-db
+  labels:
+    {{- include "app.labels" . | nindent 4 }}
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "-10"
+spec:
+  addonType: {{ .Values.database.addonType | default "mariadb" | quote }}
+  databaseName: {{ .Values.database.databaseName | default (printf "%s_db" (.Release.Name | replace "-" "_")) | quote }}
+  user:
+    permissions: {{ .Values.database.user.permissions | default "rw" | quote }}
+  secretName: {{ .Values.database.secretName | quote }}
+  deletionPolicy: {{ .Values.database.deletionPolicy | default "Retain" | quote }}
+{{- end }}

helm/APP_NAME/templates/job-alembic-upgrade.yaml

@@ -1,8 +1,17 @@
-{{- if .Values.alembic.enabled }}
+{{- if and .Values.alembic.enabled .Values.database.enabled }}
 # Job pre-upgrade que corre Alembic antes de rolar el Deployment.
-# - backoffLimit: 0  → si falla, NO reintenta; Helm aborta el upgrade.
-# - hook-delete-policy hook-succeeded → solo se borra al éxito; en fallo queda
-#   visible para `kubectl logs job/...` y diagnóstico.
+# - backoffLimit: 0  -> si falla, NO reintenta; Helm aborta el upgrade.
+# - hook-delete-policy hook-succeeded -> solo se borra al exito; en fallo queda
+#   visible para `kubectl logs job/...` y diagnostico.
+#
+# InitContainer `wait-for-secret`:
+#   - El AddonClaim (hook weight -10) ya fue aplicado, pero addon-provisioner es
+#     timer-based (RECONCILE_INTERVAL 300s, initial_delay 60s) y materializa el
+#     Secret `{{ .Values.database.secretName }}` de forma asincrona.
+#   - El InitContainer hace busy-wait hasta que el Secret existe — absorbe la
+#     latencia del reconcile dentro del pod, sin tocar el operator ni
+#     bajar RECONCILE_INTERVAL global.
+#   - Loop: 48 iteraciones x 5s = 240s — encaja dentro del helm timeout 7m.
 apiVersion: batch/v1
 kind: Job
 metadata:
@@ -28,6 +37,42 @@ spec:
       securityContext:
         runAsNonRoot: true
         runAsUser: 1001
+      initContainers:
+        - name: wait-for-secret
+          image: bitnami/kubectl:1.30
+          command:
+            - sh
+            - -c
+            - |
+              set -eu
+              # Espera hasta que addon-provisioner publique el Secret tras
+              # reconciliar el AddonClaim (hook weight -10). 48 x 5s = 240s.
+              SECRET="{{ .Values.database.secretName }}"
+              i=1
+              while [ "$i" -le 48 ]; do
+                if kubectl get secret "$SECRET" -n "$NAMESPACE" >/dev/null 2>&1; then
+                  echo "Secret $SECRET encontrado en intento $i"
+                  exit 0
+                fi
+                echo "[$i/48] Secret $SECRET aun no publicado, esperando 5s..."
+                sleep 5
+                i=$((i + 1))
+              done
+              echo "ERROR: Secret $SECRET no aparecio tras 240s — addon-provisioner stuck?"
+              exit 1
+          env:
+            - name: NAMESPACE
+              valueFrom:
+                fieldRef:
+                  fieldPath: metadata.namespace
+          resources:
+            requests: {cpu: 10m, memory: 32Mi}
+            limits:   {cpu: 100m, memory: 64Mi}
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
       containers:
         - name: alembic
           image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
@@ -37,7 +82,7 @@ spec:
                 name: {{ .Values.database.secretName }}
           env:
             # Si el Secret expone MIGRATION_DATABASE_URL, lo usa; si no, env.py
-            # cae a DATABASE_URL automáticamente (ver settings.migration_url).
+            # cae a DATABASE_URL automaticamente (ver settings.migration_url).
             - name: DATABASE_URL
               valueFrom:
                 secretKeyRef:

helm/APP_NAME/templates/role-db-secret-reader.yaml

@@ -0,0 +1,50 @@
+{{- if .Values.database.enabled }}
+# Role + RoleBinding que permiten al SA de la app leer el Secret `<release>-db-creds`
+# en el ns `apps`. Lo consume el InitContainer `wait-for-secret` del Job Alembic
+# (hook pre-install/pre-upgrade weight 0) que hace busy-wait hasta que
+# addon-provisioner publica el Secret tras reconciliar el AddonClaim.
+#
+# Hook weight "-7" — entre AddonClaim (-10) y SA (-5):
+#   - Garantiza que RBAC exista antes de que el SA del hook -5 se materialice
+#     y antes de que el Job -0 intente leer el Secret.
+#   - delete-policy: before-hook-creation para que sea idempotente entre upgrades
+#     sin dejar Roles huerfanos.
+#
+# Scope minimo: solo lectura (get/watch) del Secret `<release>-db-creds`, no
+# secrets cluster-wide ni del ns `addons`. El root Secret de MariaDB vive en
+# `addons` y nunca debe ser accesible desde `apps` (ADR-052 §6.1).
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: {{ .Release.Name }}-db-secret-reader
+  labels:
+    {{- include "app.labels" . | nindent 4 }}
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "-7"
+    "helm.sh/hook-delete-policy": before-hook-creation
+rules:
+  - apiGroups: [""]
+    resources: ["secrets"]
+    resourceNames: [{{ .Values.database.secretName | quote }}]
+    verbs: ["get", "watch", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: {{ .Release.Name }}-db-secret-reader
+  labels:
+    {{- include "app.labels" . | nindent 4 }}
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "-7"
+    "helm.sh/hook-delete-policy": before-hook-creation
+subjects:
+  - kind: ServiceAccount
+    name: {{ .Release.Name }}
+    namespace: {{ .Release.Namespace }}
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: {{ .Release.Name }}-db-secret-reader
+{{- end }}

helm/APP_NAME/values.yaml

@@ -18,7 +18,24 @@ goldenPath: web-backend
 goldenPathLang: python
 
 database:
+  # Si enabled=false: no se aplica AddonClaim, no se crea Role/RoleBinding,
+  # ni corre el Job Alembic. El shape web-backend/python es BD-first por
+  # diseño, asi que el default es true. Para una app stateless, el dev
+  # opt-out poniendo database.enabled=false (y alembic.enabled=false).
+  enabled: true
+  # Tipo de add-on solicitado al addon-provisioner. R1 solo soporta mariadb.
+  addonType: mariadb
+  # Nombre del Secret a publicar en el ns `apps` con el connection string.
+  # El Job Alembic y el Deployment lo montan via envFrom.
   secretName: __APP_NAME__-db-creds
+  # Nombre de la BD logica. Vacio -> addon-provisioner deriva del Release.Name
+  # (snake_case + "_db"). Ver template addonclaim.yaml.
+  databaseName: ""
+  user:
+    permissions: rw          # rw | ro
+  # Retain (default) | Delete — ver ADR-052 §6.2. Retain preserva la BD
+  # logica si el claim se borra (recomendado para PoC/free-trial).
+  deletionPolicy: Retain
 
 config:
   logLevel: INFO