Irving López
fcec92ea1d
Sincroniza el scaffold canónico desde templates/web-backend-python/ del repo IDP. Reemplaza el placeholder mínimo previo (.gitea/workflows/ci.yaml, README.md, .gitignore, catalog-info.yaml) por el scaffold completo documentado en ADR-053 §3: - code/ — FastAPI app con /health (db check), /metrics, /demo estático, middleware correlation_id, settings Pydantic, db.py con SQLAlchemy - code/alembic/ — migración inicial vacía + env.py usando MIGRATION_DATABASE_URL - code/tests/ — pytest + httpx TestClient (test_health, test_demo) - helm/APP_NAME/ — chart con Deployment, Service, IngressRoute Traefik, NetworkPolicy, ServiceMonitor, Job alembic-upgrade como hook pre-upgrade,pre-install (backoffLimit: 0) - coralware-shape.yaml — manifiesto v1alpha1 del contrato del shape - claim-mariadb.yaml — AddonClaim declarativo (uso futuro ADR-052) - catalog-info.yaml — entidad Backstage actualizada - .gitea/workflows/APP_NAME-build.yaml — invoca reusable workflow ADR-038 + job helm-deploy con KUBECONFIG_TENANT_B64 Placeholders __APP_NAME__, __TIER__, __TENANT_ID__, __TENANT_ID_NODASHES__ serán sustituidos server-side por repo-provisioner cuando materialice el template para un tenant (pendiente — ADR-053 §11.5). El openspec/ del golden path NO se sincroniza al repo Gitea (gobernanza interna de Coralware). Refs: ADR-052, ADR-053, poc-nexobms.md (PoC NexoBMS Demetrio).
APP_NAME — Web Backend Python (FastAPI + Alembic)
App generada desde el Golden Path web-backend/python de Coralware Cove IDP.
Este repositorio contiene el scaffold completo: aplicación FastAPI, migraciones
Alembic, frontend estático en /demo, Helm chart, workflow de CI y manifiesto
de contrato con la plataforma. Cuando se materializa este template para tu
tenant, los placeholders en mayúsculas se sustituyen automáticamente.
Contrato del shape: ver
coralware-shape.yamlen la raíz. Define los endpoints obligatorios, la BD esperada y la versión del shape. No elimines ese archivo — la plataforma lo lee.
Estructura
.
├── coralware-shape.yaml ← contrato con la plataforma
├── catalog-info.yaml ← entidad Backstage
├── code/
│ ├── app/ ← FastAPI app
│ ├── alembic/ ← migraciones DB
│ ├── tests/ ← pytest + cobertura
│ ├── pyproject.toml
│ ├── requirements.txt
│ └── Dockerfile
├── helm/__APP_NAME__/ ← Helm chart con hook Alembic pre-upgrade
├── claim-mariadb.yaml ← AddonClaim de la BD (ver §Base de datos)
└── .gitea/workflows/ ← CI: tests + build + deploy
Ciclo de vida
- Tú escribes código — endpoints en
code/app/routers/, modelos encode/app/models/, migraciones conalembic revision --autogenerate. git pushamaindispara el workflow Gitea Actions.- El CI corre
black,ruff,bandit,pytest --cov. Si algo falla, el pipeline aborta. - Si pasa, builda imagen multi-arch con BuildKit y la publica en Harbor.
helm upgrade --installaplica el chart al cluster de tu tenant. Antes del rollout, un Job pre-upgrade correalembic upgrade head. Si Alembic falla, Helm aborta y la app vieja queda intacta.- Tras rollout exitoso, smoke check valida
/health200.
Endpoints obligatorios
| Path | Auth | Propósito |
|---|---|---|
/health |
none | Liveness + readiness; devuelve {status: ok, db: up|down} |
/docs |
configurable (OPENAPI_REQUIRE_AUTH) |
Swagger UI |
/openapi.json |
igual que /docs |
Schema OpenAPI |
/demo |
none | Frontend estático servido desde code/app/static/demo/ |
/metrics |
restringido vía NetworkPolicy | Métricas Prometheus |
/health, /docs, /demo son contrato del shape — NO renombres.
Base de datos
Tu app espera un Secret __APP_NAME__-db-creds en su namespace con las
claves DATABASE_URL y MIGRATION_DATABASE_URL. El Secret lo provisiona la
plataforma:
- PoC / MVP — Coralware lo crea manualmente siguiendo el runbook
docs/runbook-mariadb-poc.mden el repo IDP. Tú no haces nada. - Producción (Fase 5.5+) —
claim-mariadb.yamllo materializa automáticamente cuando esté disponible el controlleraddon-provisioner(ver ADR-052).
Variables de entorno
| Variable | Origen | Default | Descripción |
|---|---|---|---|
DATABASE_URL |
Secret | — | Connection string runtime |
MIGRATION_DATABASE_URL |
Secret | = DATABASE_URL |
Connection para Alembic |
LOG_LEVEL |
ConfigMap | INFO |
DEBUG para troubleshooting |
CORRELATION_ID_HEADER |
ConfigMap | X-Correlation-ID |
Header de trazabilidad |
OPENAPI_REQUIRE_AUTH |
ConfigMap | false |
Activar JWT en /docs |
KEYCLOAK_ISSUER |
ConfigMap | — | URL del realm cuando auth activado |
STATIC_DEMO_PATH |
ConfigMap | /app/static/demo |
Path al frontend estático |
Migraciones Alembic
Migración base vacía en code/alembic/versions/0001_initial.py. Para crear
una nueva tras agregar modelos:
cd code
alembic revision --autogenerate -m "agregar tabla users"
Desarrollo local
cd code
pip install -r requirements-dev.txt
docker run --rm -d --name mariadb-dev \
-e MARIADB_ROOT_PASSWORD=dev -e MARIADB_DATABASE=app \
-p 3306:3306 mariadb:11
export DATABASE_URL="mysql+pymysql://root:dev@127.0.0.1:3306/app"
export MIGRATION_DATABASE_URL="$DATABASE_URL"
alembic upgrade head
uvicorn app.main:app --reload --port 8000
Plan de salida
Si decides migrar fuera de Cove, todo lo que necesitas vive en formato estándar:
| Componente | Cómo lo exportas |
|---|---|
| Código | git remote add github && git push github main |
| Imagen | docker pull desde Harbor + push a tu registry |
| Manifests | Ya están en helm/ — helm template genera YAML aplicable |
| Datos | Coralware ejecuta mariadb-dump y entrega .sql.gz |
Sin lock-in técnico.
Referencias
docs/adr-053-shape-web-backend-python.md— anatomía del shapedocs/adr-052-tenant-addon-claim-model.md— modelo de add-ons (BD)docs/adr-038-ci-estandar-reusable-workflow.md— pipeline Python