Saltar al contenido principal

Terraform — provider.tf

Objetivo: documentar exactamente cómo está configurado el provider.tf del repo (rama master), qué providers declara, qué variables consume, implicaciones operativas y pasos prácticos para comprobar, recuperar y actualizar sin romper producción.

1) Resumen de qué hace​

El provider.tf declara y fija las versiones del Cloudflare, Helm y Kubernetes providers, y enlaza su autenticación al var.cf_api_token y al var.kubeconfig_path. Es el punto de conexión entre Terraform y: Cloudflare (R2, DNS, etc.) y el cluster Kubernetes (instalación de charts y recursos K8s).

2) Desglose por provider (qué controla y ejemplos en el repo)​

a) cloudflare (source = cloudflare/cloudflare, version = ~> 4.26.0)​

  • Qué gestiona: recursos Cloudflare usados en el repo (por ejemplo cloudflare_r2_bucket en 05-object-storage.tf, registros DNS si se usara, posibles settings de proxy/zone).
  • Autenticación: mediante api_token = var.cf_api_token.
  • Implicación práctica: el token debe tener permisos adecuados para las APIs que el repo usa (crear/gestionar buckets R2, modificar DNS/zones).
  • Notas sobre la versión: ~> 4.26.0 significa: acepta >= 4.26.0 y < 4.27.0 (parches sí, salto de minor no). Esto evita saltos automáticos destructivos de major/minor.

Ejemplo de recursos en el repo: cloudflare_r2_bucket "mediawiki_uploads" y cloudflare_r2_bucket "mediawiki_db_backups".

b) helm (source = hashicorp/helm, version = ~> 2.12.0)​

  • Qué gestiona: despliegue de charts Helm desde Terraform (helm_release), p. ej. cert-manager, kube-prometheus-stack, external-dns, mariadb-operator, betterstack-logs.
  • Conexión al cluster: se le pasa la configuración K8s a través de la sección kubernetes { config_path = var.kubeconfig_path }. Eso significa que el provider Helm va a usar el mismo kubeconfig que el provider Kubernetes.
  • Precaución: Helm tiene su propia lógica (charts, hooks, upgrades). Cambios de versión en el provider o en charts pueden causar modificaciones de recursos Kubernetes (jobs de post-install, CRDs, etc.).

c) kubernetes (source = hashicorp/kubernetes, version = ~> 2.32.0)​

  • Qué gestiona: recursos nativos Kubernetes declarados con recursos kubernetes_* y kubernetes_manifest (namespaces, services, configmaps, CRs como MariaDB del operator, CronJob, Deployments, etc.).
  • Autenticación: config_path = var.kubeconfig_path (path al kubeconfig).

Importante: el provider Kubernetes es el que crea montones de recursos críticos (StatefulSets, PVCs, Services, Ingresses). Si falla la conexión del provider, terraform plan y apply no podrán ejecutarse correctamente.

3) Variables relacionadas (y sus riesgos)​

  • var.cf_api_token → token de Cloudflare. NO subirlo al repo. Debe estar como variable secreta en Spacelift o en un vault. Permisos mínimos recomendados: sólo lo necesario para R2 y DNS (crear buckets, escribir objetos, gestionar zone/bindings si aplica).

Probar Cloudflare API (básico)​

No expongas token en la shell: usa un pequeño curl para validar permisos (ejemplo conceptual):

curl -s -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json"

(Verifica que la respuesta sea 200 OK. Ajusta según la API).

Plan / Apply (recomendado flujo)​

terraform init
terraform plan -out plan.tfplan
# revisa plan.tfplan con 'terraform show plan.tfplan' o en Spacelift UI
terraform apply "plan.tfplan"

5) Cosas que se pueden romper si tocas los providers mal​

  • Cambiar config_path a una ruta inválida → Terraform no puede comunicarse con K8s → plan/apply fallan.
  • Cambiar versión del provider sin probar → cambios en schema/atributos de recursos → terraform plan puede mostrar recreaciones y cambios involuntarios.
  • Rotar cf_api_token sin actualizar Spacelift → errores para crear buckets o recursos Cloudflare en los próximos applies.
  • Borrar .terraform.lock.hcl o forzar upgrades sin testing → actualizaciones no intencionales.

6) Cómo actualizar providers de forma segura (pasos concretos)​

  1. Respaldar el state (si es manejado localmente o por Spacelift):
terraform state pull > backup-$(date -u +%Y%m%dT%H%M%SZ).tfstate
  1. Preparar rama y PR en master (nunca cambiar directo en production). En tu flujo: PR → Spacelift plan → revisión → approval → Spacelift apply.
  2. Probar upgrade localmente (si puedes reproducir el environment):
terraform init -upgrade
terraform plan -out upgrade-plan.tfplan
  1. Revisar cuidadosamente el plan. Busca recursos que se vayan a recrear. Si aparecen CRDs o hooks, revisa si helm releases van a ejecutar jobs.
  2. Aplicar en ventana de mantenimiento vía Spacelift con aprobación manual. No forzar apply automático en master si no hay validación humana.

7) Recuperación ante fallo de provider (guía rápida)​

Si terraform plan falla por provider Kubernetes (no puede conectar):

  1. Verifica KUBECONFIG y ruta var.kubeconfig_path. Comprueba permisos/propietario del archivo y que el runner lo puede leer.
  2. Verifica conectividad de red entre el runner (o Spacelift runner) y API-server (puede ser IP/firewall).

8) Recomendaciones de seguridad y buenas prácticas aplicadas a este repo​

  • No commitear secretos (cf_api_token, claves AWS). Guardarlos como secrets en Spacelift o Vault.
  • Usar rutas absolutas para kubeconfig en CI/runners. Evitar ~ en el var por problemas de expansión.
  • Fijar versiones de providers (como ya se hizo) y mantener .terraform.lock.hcl en el repo.
  • Probar upgrades en entorno no-producción antes de PR a master.
  • Hacer backup del state antes de cualquier cambio mayor (terraform state pull).

9) Checklist rápido (antes de abrir PR que toca providers)​

  • terraform init exitó sin errores (o terraform init -upgrade en branch de prueba)
  • terraform validate OK
  • terraform plan revisado y ningún recurso crítico marcado para recrear sin autorización
  • Backup de state guardado
  • Secrets (kubeconfig, cf token) verificados en Spacelift
  • Ventana de mantenimiento programada (si toca cambios en grafana/prometheus/DB)