Saltar a contenido

Estados remotos y contratos entre capas

Cada raíz declara backend "http" {}. Las URLs y credenciales se inyectan durante el job, sin fijar en HCL el ID de proyecto o una contraseña. Los estados residen en el proyecto terraform-modules; el directorio local de la raíz cambia según proveedor y capa.

Nombre y dirección

TF_ROOT       = <CLOUD_PROVIDER>/<STACK>
TF_STATE_NAME = <ENVIRONMENT>-<CLOUD_PROVIDER>-<STACK>
STATE_URL     = <CI_API_V4_URL>/projects/<CI_PROJECT_ID>/terraform/state/<TF_STATE_NAME>

Para un entorno cuyo nombre aprobado sea dev:

Capa AWS GCP
Red dev-aws-network dev-gcp-network
Kubernetes dev-aws-kubernetes dev-gcp-kubernetes
Base de datos dev-aws-database dev-gcp-database
Plataforma dev-aws-platform dev-gcp-platform

El valor predeterminado del snapshot es pro, no dev; la tabla ilustra el patrón. Elegir un nombre distinto no migra recursos de un estado a otro. Tampoco cambia automáticamente nombres cloud, región, credenciales, etiquetas o rangos de red.

Dos rutas de autenticación

Uso Usuario Credencial Configuración
Leer/escribir el estado de la raíz actual gitlab-ci-token CI_JOB_TOKEN TF_HTTP_*
Leer outputs de otras raíces oauth2 TF_STATE_TOKEN TF_VAR_<capa>_state_* y terraform_remote_state

El backend actual configura endpoints /lock, POST para bloquear, DELETE para desbloquear y espera mínima de reintento de 5 segundos. El pipeline entrega además los nombres de los cuatro estados a cada job.

TF_STATE_TOKEN debe ser una credencial admitida por el backend con acceso a los estados necesarios. Su tipo, alcance y permisos concretos no aparecen en el repositorio: deben verificarse en GitLab. No se necesita publicar su valor para documentar o reproducir el esquema de configuración. GitLab documenta el comportamiento y permisos del backend en Terraform/OpenTofu state.

Los nombres históricos se conservan mediante alias: eks_state_* apunta al estado kubernetes de AWS; rds_state_* al estado database; gke_state_* al estado kubernetes de GCP. Son alias de variables, no estados duplicados.

Contratos de outputs

Consumidor Estado que lee Datos utilizados
AWS Kubernetes network VPC y subredes privadas
AWS database network, kubernetes mediante eks VPC, subredes y security group de nodos
AWS platform network, kubernetes mediante eks, database mediante rds VPC para ALB, endpoint/CA/OIDC/nombre del clúster, conexión DB
GCP Kubernetes network VPC, subred y nombres de rangos secundarios
GCP database network VPC para Private Service Access y SQL
GCP platform network, kubernetes mediante gke, database Declara lectura de red; endpoint/CA del clúster y conexión DB

Los nombres de outputs forman una API entre raíces. Renombrar un output requiere actualizar consumidores y planificar el cambio en orden. Un estado vacío o todavía no creado impide resolver las referencias de la capa siguiente; por eso la primera creación se organiza secuencialmente.

La lectura terraform_remote_state también requiere proteger el origen completo del estado. Exponer un output como sensitive afecta a la presentación de algunas salidas, no convierte el resto del estado en una API de secretos con acceso granular.

Concurrencia y planes obsoletos

Cada job usa resource_group: <entorno>-<proveedor>-<capa>, además del bloqueo del backend. Son controles complementarios: uno ordena jobs de GitLab y el otro protege operaciones de estado. No bloquean toda la secuencia plan → espera manual → apply como una única transacción.

Si otro pipeline cambia la misma capa mientras un plan espera aprobación, el plan guardado puede dejar de ser aplicable. Se debe regenerar y revisar el plan; no buscar una forma de aplicarlo a un estado diferente. El job excepcional de GCP que ejecuta state rm también modifica el estado y puede invalidar planes ya creados.

Los cuatro estados de un proveedor no constituyen una transacción atómica. Un fallo en platform puede dejar correctamente creadas red, Kubernetes y base de datos. El diagnóstico debe empezar por identificar cuál es la última capa aplicada y qué estados contienen recursos.

Secretos, planes y artefactos

La base de datos recibe una contraseña y la plataforma crea secretos Kubernetes y releases Helm con tokens. Sus valores pueden participar en estado y planes. El pipeline guarda plan.cache/plan.json o equivalentes de destrucción durante una semana y no fija artifacts:access ni cifrado de OpenTofu.

El JSON se genera con tofu show -json, por lo que no debe asumirse que es una vista sin secretos. Las recomendaciones para una reutilización son restringir el acceso a artefactos y estados, revisar la visibilidad de pipelines, definir conservación/cifrado y tratar los backups de estado como material sensible. Son mejoras operativas propuestas; no se describen como controles ya desplegados. GitLab documenta expresamente la sensibilidad de estos ficheros.

No se incluyen estados reales, planes, credenciales ni copias de secretos en este repositorio documental.

Recuperación y cambios de namespace

Antes de restaurar o modificar un estado, identificar proyecto, nombre, lineage/serial, proveedor y recursos esperados; detener operaciones concurrentes y conservar una copia protegida. Una restauración de estado no restaura datos SQL ni recupera automáticamente objetos cloud eliminados.

Cambiar el nombre visible del grupo no altera los nombres de estado. Si se cambia la ruta del grupo, las URLs del backend construidas con CI_PROJECT_ID siguen basándose en un ID numérico dentro del proyecto; las rutas de agentes, includes y repositorios son un asunto distinto. Si se recrea o importa el proyecto con otro ID, los estados no aparecen por el mero hecho de copiar el código.

Véanse acceso del agente, pipeline y destrucción y recuperación.

Fuentes