14 min de lectura

Objetivos de aprendizaje

Al final de este módulo, podrás:

  • Configurar el IONOS CLOUD Terraform Provider con una versión fijada y autenticación por token desde el entorno
  • Crear una configuración de Terraform que despliegue un centro de datos, una LAN, un servidor, una NIC y un volumen utilizando los recursos `ionoscloud_`
  • Resolver las imágenes de sistema operativo y las ubicaciones en el momento de la planificación mediante las fuentes de datos `ionoscloud_image` y `ionoscloud_location`
  • Almacenar el estado de Terraform de forma remota en IONOS Cloud Object Storage a través del backend S3
  • Importar recursos existentes en Terraform y desmontar entornos efímeros con `terraform destroy`

Unidad 1.2: Provider de Terraform y patrones principales

Introducción

En la Unidad 1.1 creó el centro de datos de TaskBoard con curl y consultó el estado de la solicitud manualmente. Para un proyecto real, necesita la infraestructura en Git, revisada en solicitudes de extracción (pull requests) y reproducible para cada desarrollador y cada rama.

El proveedor de Terraform de IONOS CLOUD le proporciona esa capacidad. Traduce los recursos HCL en las mismas llamadas a la API v6 que realizó manualmente y espera la finalización de cada solicitud asíncrona. En esta unidad, configurará el proveedor, utilizará los cinco recursos principales de un centro de datos virtual (VDC) básico, buscará imágenes y ubicaciones, almacenará el estado de forma remota e importará recursos existentes. En el laboratorio de código, construirá el VDC base de TaskBoard, lo verificará y lo destruirá.

1. Configuración del proveedor y autenticación

terraform {
  required_providers {
    ionoscloud = {
      source  = "ionos-cloud/ionoscloud"
      version = "6.7.39"
    }
  }
}

provider "ionoscloud" {}

El bloque required_providers es obligatorio: sin él, Terraform no puede localizar ni descargar el proveedor. Fije una versión exacta para que cada desarrollador y cada ejecución de CI utilice la misma versión de lanzamiento, y realice las actualizaciones en una solicitud de extracción (pull request) separada.

1.1 Autenticación por token

La autenticación por token es el método que la documentación del proveedor sugiere encarecidamente. Con un bloque de proveedor vacío, el proveedor lee la variable de entorno IONOS_TOKEN:

export IONOS_TOKEN="$(vault kv get -field=token secret/taskboard/ionos)"
terraform init

El proveedor también acepta username y password (o IONOS_USERNAME y IONOS_PASSWORD) cuando no se establece ningún token.

1.2 Transmisión del token a través de una variable

Cuando prefiere un argumento explícito, declare una variable sensible y establézcala con TF_VAR_:

variable "ionos_token" {
  type      = string
  sensitive = true
}

provider "ionoscloud" {
  token = var.ionos_token
}
export TF_VAR_ionos_token="$IONOS_TOKEN"

Las credenciales en un archivo .tf tienen prioridad sobre las credenciales de las variables de entorno. Nunca escriba un token literal en un archivo .tf: este terminará en el historial de Git.

Para gestionar recursos de IONOS Cloud Object Storage con el proveedor, configure también IONOS_S3_ACCESS_KEY y IONOS_S3_SECRET_KEY.

2. Recursos principales

Todos los recursos del proveedor tienen el prefijo ionoscloud_. Un VDC básico utiliza cinco de ellos.

Recurso Argumentos obligatorios Notas
ionoscloud_datacenter name, location location no es modificable
ionoscloud_lan datacenter_id public = true para una LAN orientada a internet
ionoscloud_server name, datacenter_id type no es modificable; bloques volume y nic en línea
ionoscloud_volume datacenter_id, disk_type, size disk_type no es modificable; server_id lo adjunta
ionoscloud_nic datacenter_id, server_id, lan Añade una NIC adicional a un servidor

2.1 Centro de datos y LAN

variable "location" {
  type    = string
  default = "de/txl"
}

resource "ionoscloud_datacenter" "taskboard" {
  name        = "taskboard-dev"
  location    = var.location
  description = "TaskBoard development environment"
}

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

El location de un centro de datos es inmutable. Modificarlo en el código implica un nuevo centro de datos, por lo que debe seleccionarse una vez por entorno y mantenerse en una variable. Si omite ipv4_cidr_block en una LAN privada, el proveedor asigna un bloque /23 del rango 10.0.0.0/8.

2.2 Servidor con Volume en línea y NIC

resource "ionoscloud_server" "api" {
  name              = "taskboard-api-01"
  datacenter_id     = ionoscloud_datacenter.taskboard.id
  type              = "ENTERPRISE"
  cores             = 2
  ram               = 2048
  availability_zone = "AUTO"
  image_name        = data.ionoscloud_image.ubuntu.id
  ssh_keys          = [var.ssh_public_key]

  volume {
    name      = "system"
    size      = 20
    disk_type = "BALANCED"
    bus       = "VIRTIO"
  }

  nic {
    lan             = ionoscloud_lan.public.id
    name            = "public"
    dhcp            = true
    firewall_active = false
  }
}

Para los servidores ENTERPRISE debe proporcionar cores, ram (en MB) y el tamaño del volumen size (en GB). Para los servidores CUBE proporciona template_uuid en su lugar, y cores, ram y volume.size no están permitidos. ssh_keys acepta el texto de la clave directamente, y las claves SSH solo funcionan con imágenes públicas de Linux. Para nuevos volúmenes, use las clases de rendimiento de Block Storage (ESSENTIAL, BALANCED, PERFORMANCE), que la documentación recomienda.

2.3 Volúmenes y NIC adicionales

resource "ionoscloud_volume" "data" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  server_id     = ionoscloud_server.api.id
  name          = "taskboard-data"
  size          = 10
  disk_type     = "BALANCED"
  bus           = "VIRTIO"
  licence_type  = "OTHER"
}

El volumen primario se crea junto con el servidor; ionoscloud_volume agrega más. Se requiere image_name o licence_type. Deje server_id sin configurar para un volumen que no esté adjunto a ningún servidor; al cambiarlo, primero se desasocia el volumen del servidor anterior. Para una segunda interfaz de red, el recurso ionoscloud_nic funciona de la misma manera con datacenter_id, server_id y lan.

3. Fuentes de datos: imágenes y ubicaciones

No codifique de forma fija los UUID de las imágenes. Búsquelos en el momento de la planificación.

3.1 Búsqueda de una imagen del sistema operativo

data "ionoscloud_image" "ubuntu" {
  image_alias = "ubuntu:latest"
  type        = "HDD"
  cloud_init  = "V1"
  location    = var.location
}

La fuente de datos de imágenes devuelve una sola coincidencia. Si su búsqueda coincide con más de una imagen, se devuelve un error y debe refinar los argumentos. Para ver el nombre y la ubicación de las imágenes coincidentes, ejecute la operación con TF_LOG=debug. Siempre pase location, configurado con la ubicación de su centro de datos, para que la búsqueda devuelva la imagen correspondiente a esa ubicación.

3.2 Inspección de una ubicación

data "ionoscloud_location" "selected" {
  name    = var.location_name
  feature = "SSD"
}

output "cpu_families" {
  value = [for c in data.ionoscloud_location.selected.cpu_architecture : c.cpu_family]
}

Debe establecerse name o feature, o bien la fuente de datos devolverá un error. El atributo cpu_architecture enumera las familias de CPU, max_cores y max_ram (en MB) para la ubicación, lo que le ayuda a validar un cpu_family antes de aplicarlo.

4. Ciclo de vida, procesamiento asíncrono y estado

4.1 Qué ocurre internamente

terraform init      # downloads ionos-cloud/ionoscloud 6.7.39
terraform plan      # reads current resources, computes the diff, changes nothing
terraform apply     # sends create/update/delete requests and waits for each one
terraform destroy   # deletes every resource in the state

Durante apply, cada creación devuelve una solicitud asíncrona, exactamente como en la Unidad 1.1. El proveedor espera a que el recurso esté aprovisionado antes de crear los recursos que hacen referencia a él. Referencias como ionoscloud_datacenter.taskboard.id le dan a Terraform el orden implícito: centro de datos, luego LAN, luego servidor, y luego el volumen adicional.

Cada recurso que lo admite tiene un bloque timeouts. Los valores predeterminados son de 60 minutos para create, update y delete:

resource "ionoscloud_server" "api" {
  # ...
  timeouts {
    create = "30m"
    delete = "20m"
  }
}

Terraform no realiza una reversión automática ante errores. Su archivo de estado se actualiza parcialmente con los recursos que se completaron. Corrija la causa y ejecute apply nuevamente.

4.2 Depuración de errores del proveedor

De forma predeterminada, el proveedor devuelve solo errores del cliente HTTP, que generalmente consisten únicamente en el código de estado. Para ver el mensaje de error de la API, aumente el nivel de registro:

export IONOS_LOG_LEVEL=debug
terraform apply

El cuerpo de la respuesta muestra entonces httpStatus y messages con el código de error VDC-. Utilice trace solo para depuración: registra la solicitud y la respuesta completas, incluidos los datos sensibles.

4.3 Estado remoto en IONOS Cloud Object Storage

El estado local es adecuado para un solo desarrollador. Para un equipo, almacene el estado en un bucket. IONOS Cloud Object Storage es compatible con el protocolo S3 y se autentica con una Access Key y una Secret Key, por lo que utiliza el backend s3 integrado de Terraform:

terraform {
  backend "s3" {
    bucket = "taskboard-tfstate"
    key    = "dev/terraform.tfstate"
    region = "eu-central-3"
    endpoints = {
      s3 = "https://s3.eu-central-3.ionoscloud.com"
    }
    skip_credentials_validation = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
  }
}
export AWS_ACCESS_KEY_ID="<object-storage-access-key>"
export AWS_SECRET_ACCESS_KEY="<object-storage-secret-key>"
terraform init -migrate-state

La configuración de skip_* desactiva las comprobaciones específicas de AWS que un servicio compatible con S3 no puede responder. El bloqueo de estado impide que dos aplicaciones escriban el mismo estado al mismo tiempo. Hasta que haya verificado un método de bloqueo con su bucket, serialice las aplicaciones en CI para que solo se ejecute un pipeline por entorno a la vez.

5. Importación y toma de conciencia sobre costos

5.1 Importación de recursos existentes

Los servidores que creó en la Unidad 1.1 no están en ningún archivo de estado. Ponga un recurso bajo Terraform mediante un bloque import:

import {
  to = ionoscloud_server.legacy_api
  id = "<datacenter-id>/<server-id>"
}
terraform plan -generate-config-out=generated.tf

El comando escribe un bloque de recursos coincidente en generated.tf. La sintaxis de línea de comandos anterior sigue siendo compatible:

terraform import ionoscloud_server.example <datacenter-id>/<server-id>
terraform import ionoscloud_lan.public <datacenter-id>/<lan-id>
terraform import ionoscloud_datacenter.taskboard <datacenter-id>

La importación de un servidor solo con el ID del centro de datos y el ID del servidor lo importa sin un bloque nic en línea. Sus NIC se dejan como recursos ionoscloud_nic separados, que usted importa por separado. Revise la configuración generada y ejecute terraform plan hasta que muestre que no hay cambios.

5.2 Entornos efímeros

Cada apply aprovisiona recursos por los que usted paga. Tres hábitos mantienen los costos bajo control:

terraform plan -out=tfplan        # review what will be created
terraform apply tfplan            # apply exactly the reviewed plan
terraform destroy -auto-approve   # tear down when the test is finished

Cree entornos de vida corta por rama de función con un estado independiente key (por ejemplo, branches/<branch>/terraform.tfstate) y destrúyalos cuando se integre la rama. Automatizará esta eliminación en el Módulo 5.

Tarjeta rápida de referencia de la API

Endpoints principales de la API detrás de los recursos de esta unidad:

Método Endpoint Descripción
POST /datacenters Creado por ionoscloud_datacenter
POST /datacenters/{datacenterId}/lans Creado por ionoscloud_lan
POST /datacenters/{datacenterId}/servers Creado por ionoscloud_server
GET /images Buscado por la fuente de datos ionoscloud_image
GET /requests/{requestId}/status Consultado mientras el proveedor espera la aprovisionamiento

URL base: https://api.ionos.com/cloudapi/v6 Autenticación: Authorization: Bearer <token>

Laboratorio de código

Objetivo: Construir el VDC base de TaskBoard con Terraform (centro de datos, LAN, servidor con volumen adjunto), y luego planificarlo, aplicarlo, verificarlo y destruirlo.

Requisitos previos:

  • Cuenta de IONOS CLOUD con un token de API en IONOS_TOKEN
  • Terraform instalado localmente
  • ionosctl (Unidad 1.1) y una clave pública SSH

Paso 1: Crear el proyecto con versions.tf y variables.tf

# mkdir taskboard-infra && cd taskboard-infra
# versions.tf: the terraform block from Section 1, with an empty provider "ionoscloud" {}

# variables.tf
variable "location" {
  type    = string
  default = "de/txl"
}
variable "ssh_public_key" {
  type = string
}

Salida esperada:

(files saved)

Paso 2: Escriba main.tf y outputs.tf

Copie la fuente de datos de la imagen (sección 3.1), el centro de datos y la LAN (sección 2.1), el servidor (sección 2.2) y el volumen de datos (sección 2.3) en main.tf. Luego agregue:

output "datacenter_id" { value = ionoscloud_datacenter.taskboard.id }
output "server_id"     { value = ionoscloud_server.api.id }
output "server_ip"     { value = ionoscloud_server.api.primary_ip }

Salida esperada:

(files saved)

Paso 3: Inicializar y planificar

export TF_VAR_ssh_public_key="$(cat ~/.ssh/id_ed25519.pub)"
terraform init
terraform plan -out=tfplan

Salida esperada:

Terraform has been successfully initialized!
...
Plan: 4 to add, 0 to change, 0 to destroy.

Paso 4: Aplicar

terraform apply tfplan

Salida esperada:

ionoscloud_datacenter.taskboard: Creation complete after ...
ionoscloud_lan.public: Creation complete after ...
ionoscloud_server.api: Creation complete after ...
ionoscloud_volume.data: Creation complete after ...
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Paso 5: Verificar fuera de Terraform

DC=$(terraform output -raw datacenter_id)
ionosctl compute server list --datacenter-id "$DC" --cols Name,Type,Cores,State
ionosctl compute server volume list --datacenter-id "$DC" \
  --server-id "$(terraform output -raw server_id)" --cols Name,Size,Type,State

Salida esperada:

Name               Type         Cores   State
taskboard-api-01   ENTERPRISE   2       AVAILABLE
Name             Size   Type       State
system           20     BALANCED   AVAILABLE
taskboard-data   10     BALANCED   AVAILABLE

Paso 6: Confirmar que no hay desviación

terraform plan

Salida esperada:

No changes. Your infrastructure matches the configuration.

Lista de verificación de validación:

  • [ ] terraform apply creó cuatro recursos sin errores
  • [ ] ionosctl muestra el servidor como AVAILABLE en el nuevo centro de datos
  • [ ] El servidor tiene dos volúmenes adjuntos
  • [ ] Un segundo terraform plan no informa cambios

Limpieza:

terraform destroy -auto-approve

Errores comunes

Errores de desarrollo a evitar con el tema de esta unidad:

  1. Versión del proveedor sin fijar

    • Problema: Un plan que estaba limpio ayer de repente muestra cambios, o un argumento deja de funcionar en CI.
    • Por qué ocurre: Sin un version exacto en required_providers, terraform init en un runner nuevo puede descargar una versión más reciente del proveedor que la que probó.
    • Solución: Fije version = "6.7.39", commitee .terraform.lock.hcl y realice la actualización en una solicitud de extracción dedicada.
  2. Cambio de un argumento inmutable

    • Problema: Cambia location en un centro de datos, o type en un servidor, y el plan desea destruirlo y volver a crearlo.
    • Por qué ocurre: Estos argumentos son inmutables. En un servidor, allow_replace = true los actualiza destruyendo y volviendo a crear el servidor.
    • Solución: Mantenga los valores inmutables en variables por entorno, revise cada línea de -/+ en el plan y use allow_replace solo cuando acepte la recreación.
  3. Búsquedas de imagen ambiguas

    • Problema: terraform plan falla en la fuente de datos ionoscloud_image con un error sobre múltiples coincidencias.
    • Por qué ocurre: Los argumentos de búsqueda coinciden con más de una imagen, por ejemplo, un alias sin type o location.
    • Solución: Agregue location, type y cloud_init a la fuente de datos, y ejecute con TF_LOG=debug para ver qué imágenes coincidieron.

Resumen

Ahora puede describir la infraestructura base de TaskBoard como código. El proveedor fijado se autentica con un token del entorno y convierte cinco recursos principales de ionoscloud_ en llamadas a la API v6, esperando por cada solicitud asíncrona. Las imágenes provienen de fuentes de datos, el estado se almacena en IONOS Cloud Object Storage, los recursos creados manualmente pueden importarse y cada entorno se crea a partir de un plan revisado y se destruye nuevamente.

Puntos clave:

  • Fije ionos-cloud/ionoscloud a una versión exacta en required_providers; autentíquese con IONOS_TOKEN
  • location en un centro de datos y type en un servidor son inmutables; al cambiarlos se recrea el recurso
  • El proveedor espera por cada solicitud asíncrona; ajuste las esperas con timeouts (60 minutos por defecto)
  • Utilice el backend S3 con un endpoint de IONOS Cloud Object Storage y una Access Key junto con una Secret Key para el estado compartido
  • Importe con <datacenter-id>/<server-id>, genere la configuración con -generate-config-out y destruya los entornos efímeros

Terminología importante:

  • Fijación del proveedor: Una versión exacta de version en required_providers para que cada ejecución utilice la misma versión del proveedor
  • Fuente de datos: Una consulta de solo lectura en el momento de la planificación, como ionoscloud_image, que devuelve una única coincidencia o falla
  • Argumento inmutable: Un argumento que la API no puede modificar in situ, como location; los cambios fuerzan la recreación
  • Backend remoto: El backend s3 apuntando a un endpoint de IONOS Cloud Object Storage para compartir el estado entre un equipo
  • Bloque de importación: HCL que adopta un recurso existente en el estado por su ID, generando opcionalmente su configuración

Próximos pasos

Continúe aprendiendo: Unidad 1.3: Verificación de conocimientos - Fundamentos programáticos

Temas relacionados: