Unidad 1.2: Proveedor Terraform y patrones básicos

Introducción

En la Unidad 1.1, usted provisionó un servidor de tres maneras: API raw con curl, el SDK de Python, y ionosctl. Las tres son imperativas. Usted emite una POST, sondea /requests/{id}/status hasta DONE, y luego emite la siguiente llamada. Eso funciona, pero no le da una descripción reprodudible y controlada por versiones de su infraestructura. Para TaskBoard, la herramienta de gestión de tareas y frontend que está construyendo a lo largo de este curso, usted necesita una infraestructura que viva en Git, que se revise como código y que se desmonte limpiamente para que los entornos de prueba nunca le cobren silenciosamente.

Esta unidad lo lleva a la provisión declarativa con el proveedor IONOS Terraform. Usted escribirá el HCL que construye la VDC base de TaskBoard, verá lo que Terraform hace bajo el capó con el API asíncrono de IONOS, almacenará el estado de manera remota en Object Storage, y adoptará el patrón de entorno efímero que mantiene el costo bajo control. La sondeación asíncrona que manejó manualmente en 1.1 ahora es trabajo del proveedor.

1. Configuración y autenticación del proveedor

El proveedor de IONOS para Terraform interactúa con los recursos de cómputo, almacenamiento y redes de IONOS Cloud. Actualmente, admite las últimas ofertas V5 y V6 de API, y se publica en el Registro de Terraform bajo ionos-cloud/ionoscloud. Antes de que funcione nada, debe tener una cuenta de IONOS cuyas credenciales se autentiquen contra la nube API, exactamente como en la Unidad 1.1.

1.1 Declarar y bloquear la versión del proveedor

Siempre bloquee la versión del proveedor. El bloque required_providers de Terraform lo bloquea en una versión conocida y buena, para que un terraform init el próximo mes no introduzca un cambio de ruptura en su canal.

# versions.tf
terraform {
  required_version = ">= 1.5.0"

  required_providers {
    ionoscloud = {
      source  = "ionos-cloud/ionoscloud"
      version = "~> 6.4"
    }
  }
}

La restricción ~> 6.4 permite actualizaciones de parches y menores dentro de la línea 6.x, pero bloquea un salto a 7.0. Ejecute terraform init para descargar el proveedor bloqueado en .terraform/. Confirme el archivo .terraform.lock.hcl generado para que cada compañero de equipo y ejecutor de CI resuelva la misma compilación del proveedor.

1.2 Autenticación: Variable de entorno vs bloque de proveedor

El patrón más limpio es autenticarse con el token de portador de Token Manager (cubierto en la Unidad 1.1) a través de la variable de entorno IONOS_TOKEN. Nada secreto toca entonces su HCL o su historial de Git.

export IONOS_TOKEN="eyJ0eXAiOiJKV1QiLCJraWQiO..."
terraform plan

Con la variable establecida, el bloque del proveedor puede estar vacío:

# provider.tf
provider "ionoscloud" {}

También puede pasar credenciales explícitamente en el bloque de proveedor, lo que es útil cuando una sola configuración administra recursos en más de una cuenta. El nombre de usuario y la contraseña (autenticación básica) son compatibles como alternativa al token.

provider "ionoscloud" {
  token = var.ionos_token   # never hardcode; pass via TF_VAR_ionos_token
}

Prefiera la variable de entorno IONOS_TOKEN sobre un token comprometido en un archivo .tfvars. Si debe utilizar una variable, márcela sensitive = true y proporciónela a través de TF_VAR_ionos_token en su shell o almacén de secretos de CI.

2. Recursos básicos: Creación de un centro de datos virtual

Un entorno base de TaskBoard necesita un centro de datos virtual, un LAN, un servidor, un arranque Volume y una NIC que conecte el servidor al LAN. Cada recurso de IONOS Terraform tiene un prefijo ionoscloud_, lo que los mantiene inequívocos cuando una configuración combina proveedores.

2.1 Centro de datos, LAN, Servidor, Volume, NIC

Los nombres de los recursos a continuación (ionoscloud_datacenter, ionoscloud_lan, ionoscloud_server, ionoscloud_nic) y sus esquemas de atributos siguen la documentación del proveedor IONOS Terraform. El valor de ubicación y la selección de imagen se basan en las secciones de origen de datos de esta unidad.

# main.tf
resource "ionoscloud_datacenter" "taskboard" {
  name        = "taskboard-base"
  location    = "de/fra"
  description = "TaskBoard base VDC, managed by Terraform"
}

resource "ionoscloud_lan" "app" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  name          = "taskboard-app-lan"
  public        = true
}

resource "ionoscloud_server" "api" {
  name              = "taskboard-api"
  datacenter_id     = ionoscloud_datacenter.taskboard.id
  cores             = 2
  ram               = 4096
  cpu_family        = "INTEL_SKYLAKE"
  availability_zone = "AUTO"

  volume {
    name           = "taskboard-api-boot"
    size           = 20
    disk_type      = "SSD"
    image_name     = data.ionoscloud_image.ubuntu.id
    image_password = var.server_password
  }

  nic {
    lan  = ionoscloud_lan.app.id
    dhcp = true
  }
}

Observe que los bloques volume y nic en línea le permiten expresar el disco de arranque y el ajuste de red como parte del servidor. Para una base de datos Volume que se adjunta después del arranque, o para gestionar el ciclo de vida de un disco de forma independiente, declare un ionoscloud_volume independiente en su lugar.

2.2 Base de datos Volume y NIC independientes

resource "ionoscloud_volume" "data" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  server_id     = ionoscloud_server.api.id
  name          = "taskboard-data"
  size          = 50
  disk_type     = "SSD"
  licence_type  = "OTHER"
}

resource "ionoscloud_nic" "extra" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  server_id     = ionoscloud_server.api.id
  lan           = ionoscloud_lan.app.id
  dhcp          = true
}

Las referencias como ionoscloud_datacenter.taskboard.id y ionoscloud_server.api.id son lo que dan a Terraform su orden. Debido a que el Volume lee server_id desde el recurso del servidor, Terraform sabe que el servidor debe existir primero. Usted nunca escribe lógica explícita de "esperar al centro de datos". Ese gráfico de dependencias es el punto principal de abandonar los scripts imperativos de la Unidad 1.1.

3. El ciclo de vida plan/aplicar/destruir

Los tres comandos que ejecutará constantemente son terraform plan, terraform apply, y terraform destroy. Comprender qué hace cada uno contra el IONOS API asíncrono ahorra horas de confusión.

3.1 Qué sucede bajo el capó

terraform plan lee su HCL, lee el estado actual, consulta el IONOS API para el estado en vivo de cada recurso gestionado, e imprime la diferencia. No cambia nada. terraform apply ejecuta esa diferencia emitiendo las mismas llamadas POST, PUT, y DELETE que hizo a mano en 1.1.

Aquí está el punto clave: las operaciones de IONOS API son asíncronas. Un POST devuelve un ID de solicitud y el recurso no está listo todavía. En la Unidad 1.1, usted sondeó /requests/{id}/status hasta DONE antes de la siguiente llamada. El proveedor de IONOS Terraform realiza ese sondeo internamente para cada recurso. Cuando apply muestra un recurso como todavía en creación, está esperando exactamente ese estado de solicitud antes de proceder a los recursos dependientes.

terraform plan -out=taskboard.tfplan
terraform apply taskboard.tfplan

Capturar el plan en un archivo con -out y aplicar ese archivo exacto garantiza que apply haga precisamente lo que revisó, sin desviación entre el plan y la aplicación. Este es el patrón seguro para CI/CD.

3.2 Destruir y operaciones dirigidas

# Preview what will be torn down
terraform plan -destroy

# Tear it all down
terraform destroy

# Operate on a single resource (use sparingly)
terraform apply -target=ionoscloud_server.api

terraform destroy recorre el gráfico de dependencias en reverso: NIC y volúmenes antes del servidor, el servidor antes del LAN, el LAN antes del centro de datos. Este orden inverso es por qué usted debe dejar que Terraform gestione la pila completa en lugar de eliminar recursos manualmente en el DCD, lo que puede dejar el estado de Terraform fuera de sincronización con la realidad.

4. Estado remoto en Object Storage

De forma predeterminada, Terraform escribe el estado en un archivo terraform.tfstate local. Eso no funciona para un equipo o una canalización. El estado debe estar en un lugar compartido, y IONOS Cloud Object Storage es compatible con S3, por lo que sirve como backend de Terraform.

4.1 Configuración del backend de S3

IONOS Object Storage se autentica con una clave de acceso y una clave secreta, no con tokens de portador. Estas son las mismas credenciales de S3 que genera en la gestión de claves de Object Storage. Object Storage está disponible en varias regiones, cada una con su propio punto de conexión, incluyendo Frankfurt (de) en s3.eu-central-1.ionoscloud.com, Berlín (eu-central-2) en s3.eu-central-2.ionoscloud.com, y Logroño (eu-south-2) en s3.eu-south-2.ionoscloud.com.

# backend.tf
terraform {
  backend "s3" {
    bucket   = "taskboard-tfstate"
    key      = "base/terraform.tfstate"
    region   = "eu-central-1"
    endpoints = {
      s3 = "https://s3.eu-central-1.ionoscloud.com"
    }
    skip_credentials_validation = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
    skip_s3_checksum            = true
  }
}

Las banderas skip_* son necesarias porque este es un proveedor externo (no AWS) S3. Sin ellas, el backend intenta llamar a puntos de conexión específicos de AWS como el Security Token Service y falla. Proporcione las credenciales a través de las variables de entorno estándar de S3 para que nunca entren en su HCL:

export AWS_ACCESS_KEY_ID="your-object-storage-access-key"
export AWS_SECRET_ACCESS_KEY="your-object-storage-secret-key"
terraform init   # migrates local state into the bucket

4.2 Consideraciones de bloqueo de estado

El bloqueo de estado evita que dos ejecuciones de apply corrompan el estado simultáneamente. Los backends de AWS S3 tradicionalmente confían en una tabla de DynamoDB para bloqueos, que IONOS Object Storage no proporciona. Trate el backend de IONOS S3 como desbloqueado: serialize las aplicaciones a través de una sola tubería de CI/CD, nunca ejecute aplicaciones concurrentes contra la misma clave de estado, y utilice un estado key separado por entorno (por ejemplo, base/, staging/, prod/) para que las pilas no relacionadas nunca entren en conflicto.

5. Fuentes de datos, importaciones y control de costes

Codificar IDs de imagen y cadenas de región en los archivos de configuración los hace frágiles. Las fuentes de datos consultan el IONOS API en el momento de planificación para que su HCL permanezca portable. Las importaciones llevan recursos creados fuera de Terraform bajo gestión. Y la destrucción disciplinada mantiene su factura honesta.

5.1 Fuentes de datos de imagen y ubicación

data "ionoscloud_location" "frankfurt" {
  name    = "fra"
  feature = "SSD"
}

data "ionoscloud_image" "ubuntu" {
  type     = "HDD"
  location = "de/fra"
  cloud_init = "V1"
  image_alias = "ubuntu:latest"
}

La fuente de datos ionoscloud_image resuelve una imagen actual para que no esté utilizando un ID de imagen UUID obsoleto que puede estar retirado. La fuente de datos ionoscloud_location confirma una región y su disponibilidad de características antes de que se provisione en ella. Haga referencia al resultado con data.ionoscloud_image.ubuntu.id en el bloque volume del servidor, como se muestra en la Sección 2.

La siguiente tabla resume las cuatro formas de impulsar la provisión de IONOS que ha visto a lo largo de las Unidades 1.1 y 1.2.

Utilice Terraform cuando la infraestructura deba ser reproductible y revisada. Utilice SDK o ionosctl para operaciones en tiempo de ejecución y comprobaciones rápidas que no pertenecen a su pila declarativa.

5.2 Importación de recursos existentes

Si un centro de datos o servidor ya existe, quizás creado en el DCD o por un script curl anterior, importelo en lugar de recrearlo. Escriba un bloque de recursos coincidente primero, luego importe. Las importaciones de IONOS utilizan un ID compuesto que une el ID del centro de datos y el ID del recurso.

# Import an existing server: format is datacenter_id/server_id
terraform import ionoscloud_server.api \
  3fa85f64-5717-4562-b3fc-2c963f66afa6/9bc92f81-1234-4cde-8901-abcdef012345

# Import a datacenter (single ID)
terraform import ionoscloud_datacenter.taskboard 3fa85f64-5717-4562-b3fc-2c963f66afa6

Después de la importación, ejecute terraform plan. Si el plan muestra cambios, su HCL aún no coincide con la realidad. Reconcilie los atributos del bloque de recursos con la configuración en vivo hasta que plan informe que no hay cambios. Solo entonces el recurso está seguro bajo gestión.

5.3 Conciencia de costes y entornos efímeros

Cada recurso que Terraform provisiona en apply incurre en cargos desde el momento en que existe. El flujo de trabajo disciplinado es: siempre plan antes de apply, siempre destroy lo que se activa para pruebas. El patrón de entorno efímero crea una pila completa para una ejecución de prueba y luego la desmonta.

# Spin up a throwaway environment for a feature branch
terraform workspace new pr-142
terraform apply -auto-approve

# ... run integration tests against the live infrastructure ...

# Tear it all down so it stops billing
terraform destroy -auto-approve
terraform workspace delete pr-142

Conectar terraform destroy al paso de desmontaje de un trabajo de CI garantiza que un entorno de rama olvidado no pueda acumular costos silenciosamente durante semanas.

API Tarjeta de referencia rápida

El proveedor IONOS Terraform llama a estos puntos de conexión de Cloud API bajo la capa. Conocerlos le ayuda a depurar un apply atascado.

URL base: https://api.ionos.com/cloudapi/v6 Autenticación: Authorization: Bearer <token> (el proveedor lee IONOS_TOKEN)

Laboratorio de código

Objetivo: Construir la base de TaskBoard con Terraform: un centro de datos, un LAN, y un servidor con un Volume adjunto. Planificar, aplicar, verificar y destruir.

Requisitos previos:

• Cuenta de IONOS Cloud con un token API exportado como IONOS_TOKEN
• Terraform 1.5 o posterior instalado localmente
• ionosctl configurado (desde la Unidad 1.1) para verificación

Paso 1: Crear el esqueleto de la configuración

mkdir taskboard-base && cd taskboard-base
touch versions.tf provider.tf main.tf

Salida esperada:

(no output; three empty files created)

Paso 2: Agregar el proveedor y fijar la versión

Coloque el contenido de versions.tf de la Sección 1.1 y provider "ionoscloud" {} de la Sección 1.2 en sus archivos, luego inicialice.

terraform init

Salida esperada:

Initializing provider plugins...
- Installing ionos-cloud/ionoscloud v6.4.x...
Terraform has been successfully initialized!

Paso 3: Escribir los recursos del centro de datos virtual

Agregue los bloques ionoscloud_datacenter, ionoscloud_lan, y ionoscloud_server de la Sección 2.1, más la fuente de datos ionoscloud_image de la Sección 5.1 a main.tf.

Paso 4: Planificar y revisar

export TF_VAR_server_password="ChangeMe-Strong-Pw-1"
terraform plan -out=taskboard.tfplan

Salida esperada:

Plan: 3 to add, 0 to change, 0 to destroy.

Paso 5: Aplicar

terraform apply taskboard.tfplan

Salida esperada:

ionoscloud_datacenter.taskboard: Creation complete after 25s [id=3fa85f64-...]
ionoscloud_server.api: Still creating... [1m20s elapsed]
ionoscloud_server.api: Creation complete after 2m10s [id=9bc92f81-...]
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Paso 6: Verificar con ionosctl

terraform output -raw datacenter_id 2>/dev/null || true
ionosctl server list --datacenter-id $(terraform state show ionoscloud_datacenter.taskboard | grep -m1 'id ' | awk '{print $3}' | tr -d '"')

Salida esperada:

ServerId   Name            State       Cores   Ram
9bc92f81   taskboard-api   AVAILABLE   2       4096

Paso 7: Inspeccionar el estado

terraform state list

Salida esperada:

data.ionoscloud_image.ubuntu
ionoscloud_datacenter.taskboard
ionoscloud_lan.app
ionoscloud_server.api

Lista de verificación:

• [ ] terraform apply completado con 3 recursos agregados
• [ ] ionosctl server list muestra el servidor como AVAILABLE
• [ ] terraform state list muestra todos los recursos administrados

Limpieza:

terraform destroy -auto-approve

Errores comunes

1. Eliminar recursos en el DCD que Terraform gestiona

   • Problema: Usted elimina el servidor manualmente en la interfaz web, luego terraform apply produce errores o intenta recrear recursos no relacionados.
   • Por qué sucede: El estado de Terraform todavía registra el servidor eliminado. El API en vivo ya no lo tiene, por lo que el estado y la realidad divergen.
   • Solución: Elimine la entrada obsoleta del estado, luego permita que Terraform reconcilie:

   terraform state rm ionoscloud_server.api
   terraform plan   # now matches reality
   

2. Olvidar las banderas de salto de backend de S3

   • Problema: terraform init contra el backend de Object Storage se cuelga o falla con un error de STS o ID de cuenta.
   • Por qué sucede: El backend de S3 asume AWS y realiza llamadas exclusivas de AWS que IONOS Object Storage no implementa.
   • Solución: Agregue las banderas de salto y el punto de conexión explícito al bloque de backend:

   skip_credentials_validation = true
   skip_region_validation      = true
   skip_requesting_account_id  = true
   endpoints = { s3 = "https://s3.eu-central-1.ionoscloud.com" }
   

3. Fijar un UUID de imagen obsoleta en lugar de utilizar una fuente de datos

   • Problema: terraform apply falla con un error de imagen no encontrada meses después de que la configuración última funcionara.
   • Por qué sucede: Un UUID de imagen codificado en duro se retiró en el flujo de trabajo ascendente. La creación de servidor asíncrona se aborta porque su arranque Volume hace referencia a una imagen que falta.
   • Solución: Resuelva la imagen en el momento de planificación con la fuente de datos y haga referencia a ella:

   data "ionoscloud_image" "ubuntu" {
     type        = "HDD"
     location    = "de/fra"
     image_alias = "ubuntu:latest"
   }
   # volume { image_name = data.ionoscloud_image.ubuntu.id }
   

Resumen

Ahora puede describir la infraestructura de IONOS de forma declarativa y gestionar su ciclo de vida completo desde el código. Configuró y fijó la versión del proveedor IONOS Terraform, se autenticó con IONOS_TOKEN y creó la base de VDC de TaskBoard desde los recursos ionoscloud_datacenter, ionoscloud_lan, ionoscloud_server, ionoscloud_volume y ionoscloud_nic. Movió el estado a un backend compatible con S3 de Object Storage, utilizó fuentes de datos para resolver imágenes y ubicaciones de forma dinámica, importó recursos existentes y adoptó el patrón de entorno efímero para que la infraestructura de prueba se desmonte de forma limpia.

El modelo de aprovisionamiento asíncrono que manejó manualmente en la Unidad 1.1 ahora es una preocupación interna del proveedor: Terraform sondea el estado de la solicitud para usted y ordena operaciones a través de su gráfica de dependencias. A partir de aquí, cada unidad de infraestructura en este curso se basa en esta misma fundación de Terraform.

Puntos clave:

• El proveedor de IONOS admite las ofertas de API V5 y V6; siempre fije la versión con required_providers y comprometa el archivo de bloqueo
• Autentíquese con IONOS_TOKEN para que no ingrese ningún secreto en su HCL; todos los recursos tienen el prefijo ionoscloud_
• Terraform sondea el punto de conexión asíncrono /requests/{id}/status internamente y ordena operaciones a través de la gráfica de dependencias de recursos
• El backend de Object Storage de S3 necesita las banderas skip_* y un punto de conexión de IONOS explícito, y se autentica con la clave de acceso más la clave secreta, no con un token de portador
• Siempre plan antes de apply y destroy entornos efímeros para controlar el costo

Terminología importante:

• Proveedor: El plugin que traduce los recursos de HCL en llamadas a API de IONOS Cloud, publicado como ionos-cloud/ionoscloud
• Estado: El registro de Terraform de qué recursos de IONOS reales gestiona, almacenado localmente o en un backend de Object Storage
• Fuente de datos: Una consulta de solo lectura contra el API de IONOS en el momento del plan, como ionoscloud_image, utilizada para evitar codificar IDs de forma dura
• Importación: Llevar un recurso de IONOS existente bajo la gestión de Terraform utilizando una datacenter_id/resource_id compuesta
• Entorno efímero: Una pila completa creada para una ejecución de prueba y desmontada con terraform destroy para evitar cargos persistentes

Próximos pasos

Continuar aprendiendo: Unidad 1.3: Verificación de conocimientos - Fundamentos programáticos

Temas relacionados:

• Unidad 1.1: IONOS API, autenticación y modelo asíncrono
• Unidad 2.1: Cómputo y automatización de servidores