Terraform está implementado exclusivamente en sport-app-platform. No estará dentro de backend o frontend porque administra recursos compartidos y debe desplegar una combinación compatible de todos los componentes.

La plataforma se clona como carpeta hermana de backend, frontend, movil y documentacion. Para Terraform se usa git clone --no-recurse-submodules: descarga solo la plataforma y deja los tres submódulos sin inicializar. .gitmodules usa update = none y deshabilita el fetch recursivo como protección adicional.

El comando git submodule status debe mostrar el prefijo - para backend, frontend y móvil. Solo integración/E2E puede habilitarlos expresamente con git submodule update --init --checkout. Un push de plataforma usa git push --no-recurse-submodules y no puede publicar cambios de los componentes; actualizar un puntero exige un PR de release y la actualización simultánea del manifiesto.

El procedimiento completo está en la Guía de clonado seguro.

Hay dos ambientes (ADR-022): desarrollo, en el Kubernetes kubeadm de Docker Desktop, y producción, en GCP. Antes del primer apply se completa la Preparación local y de GCP para Terraform: activar Kubernetes con kubeadm en local, o crear los proyectos, autenticarse sin llaves y completar bootstrap.auto.tfvars, gcp.auto.tfvars y backend.hcl en GCP. La operación diaria está en la guía de Terraform.

flowchart TB
    P["sport-app-platform<br/>Terraform centralizado"]
    B["Backend<br/>imagen y migraciones"]
    W["Frontend<br/>imagen o paquete"]
    M["Móvil<br/>APK o AAB"]
    L[Desarrollo local<br/>Docker Desktop kubeadm]
    S["Candidato futuro<br/>Staging no creado"]
    R[Producción GCP]

    B -. digest .-> P
    W -. digest o checksum .-> P
    M -. versión y checksum .-> P
    P --> L
    P --> R
    P -. requiere una decisión nueva .-> S

Nota — significado de checksum: un checksum es una huella digital calculada sobre el contenido de un artefacto, normalmente con SHA-256. Permite comprobar que el archivo, paquete o imagen recibido es exactamente el que fue validado y que no fue alterado. La versión proporciona un nombre legible —por ejemplo, v1.2.0—, mientras que el checksum identifica su contenido exacto. En imágenes OCI se usa el digest @sha256:...; en Terraform, .terraform.lock.hcl conserva hashes para verificar los proveedores descargados. La plataforma registra versiones, digests o checksums compatibles para reproducir la misma release.

Nota — alcance de staging: las líneas continuas representan los dos ambientes vigentes: desarrollo local y producción GCP. Staging es únicamente un candidato futuro y no tiene hoy raíz Terraform, proyecto GCP, estado remoto, identidad, presupuesto, datos ni despliegue. Su creación exigirá una decisión arquitectónica y económica explícita.

infra/
├── kubernetes/local/           # PostgreSQL, emulador Pub/Sub, tópicos y accesos de desarrollo
└── terraform/
    ├── bootstrap/gcp-state/    # estado, WIF, cuentas y presupuesto de producción
    ├── modules/gcp/            # red, GKE, Cloud SQL, Pub/Sub, Cloud Run, IAM, secretos, alertas
    └── environments/
        ├── local/              # desarrollo
        └── production/         # producción

Cada ambiente es una raíz independiente, con estado, variables e identidad propios. No se utilizarán workspaces para representar ambientes.

flowchart LR
    TF[Terraform local]
    subgraph K8S[Kubernetes local desechable]
      WEB[Frontend]
      BFF[BFF]
      API[Microservicios]
      DB[(PostgreSQL)]
      PS[Emulador Pub/Sub]
    end
    TF --> WEB
    TF --> BFF
    TF --> API
    TF --> DB
    TF --> PS
    WEB --> BFF --> API --> DB
    API <--> PS

El ambiente local es el ambiente de desarrollo. Permite probar composición, migraciones, contratos, outbox, eventos y recorridos E2E sin conectarse a GCP. Terraform compone las dependencias de la plataforma con los manifiestos deploy/k8s/base del backend, de modo que cada cambio del backend llega con un terraform apply y un tag de imagen nuevo. Su estado es desechable y no se versiona. IAM, cuotas, alta disponibilidad y servicios administrados solo se ejercitan en producción, con plan revisado por otra persona.

flowchart TB
    GH[GitHub Actions<br/>OIDC/WIF] --> TF[Terraform del ambiente]
    TF <--> STATE[(Estado GCS separado<br/>proyecto de gestión)]
    subgraph GCP[Proyecto GCP del ambiente]
      NET[VPC]
      AR[Artifact Registry]
      RUN[Cloud Run]
      GKE[GKE]
      SQL[(Cloud SQL)]
      PS[Pub/Sub]
      SM[Secret Manager]
      OBS[Logging y Monitoring]
    end
    TF --> NET
    TF --> AR
    TF --> RUN
    TF --> GKE
    TF --> SQL
    TF --> PS
    TF --> SM
    TF --> OBS
    AR -. imágenes por digest .-> RUN
    AR -. imágenes por digest .-> GKE

flowchart LR
    PR[Pull request] --> V[fmt y validate]
    V --> T[pruebas y análisis]
    T --> P[plan]
    P --> R[revisión]
    R --> A[apply autorizado]
    A --> S[smoke y evidencia]

Nota — fmt y validate: terraform fmt -check -recursive comprueba que los archivos .tf usan el formato estándar de Terraform; en CI informa un error si requieren formateo, pero no cambia la infraestructura. terraform validate comprueba la sintaxis y la coherencia interna de la configuración —por ejemplo, tipos, referencias y argumentos requeridos— después de inicializar los proveedores. Ninguno de los dos comandos crea, modifica o elimina recursos; para conocer los cambios propuestos todavía se debe ejecutar terraform plan.

El backend GCS se crea primero mediante un bootstrap controlado. Terraform crea contenedores y referencias de secretos, no sus valores. La release utiliza las imágenes por digest y versiones consignadas en el manifiesto de plataforma.

flowchart LR
    OFF[Sin ambiente local] -->|terraform apply| ON[Desarrollo en Docker Desktop]
    ON -->|terraform apply con tag nuevo| ON
    ON -->|terraform destroy| OFF

Producción se apaga manualmente con Terraform, siempre con plan revisado: suspender (suspended = true: Cloud SQL detenido, Cloud Run y nodos GKE en 0; quedan costos como la tarifa del clúster) o destruir con confirmación explícita del ID del proyecto (casi sin costo; se pierden datos e imágenes). Procedimiento: guía de preparación, sección 9.

Desarrollo es local y no genera costos de nube. Staging no existe, no participa en el flujo vigente y su ubicación deberá decidirse antes de implementarlo. Producción no admite destrucción programada y tendrá presupuesto, alertas, cuotas y política de limpieza. Una alerta de presupuesto no limita por sí sola el gasto.

La estimación económica, sus supuestos y el presupuesto inicial de producción se mantienen en Costos estimados de producción en GCP.

• Decisión y arquitectura: aprobadas.
• Repositorio propietario: sport-app-platform.
• Raíz local (desarrollo): implementada, aplicada en Docker Desktop kubeadm y verificada con un registro de usuario de punta a punta (BFF → servicio → PostgreSQL → outbox → Pub/Sub).
• Bootstrap, módulos GCP y raíz de producción: implementados y validados con terraform validate y terraform test; sin aplicar.
• Preparación local/GCP: guía actualizada con el paso a paso de cada plataforma.
• Workflows de Terraform, overlay Kubernetes de producción e imagen del frontend: pendientes.
• Despliegue y evidencia en GCP: pendientes.

La especificación operativa completa se encuentra en Arquitectura Terraform de SportApp.

Volver a Arquitectura de la solución