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 applycreó cuatro recursos sin errores - [ ]
ionosctlmuestra el servidor comoAVAILABLEen el nuevo centro de datos - [ ] El servidor tiene dos volúmenes adjuntos
- [ ] Un segundo
terraform planno informa cambios
Limpieza:
terraform destroy -auto-approve
Errores comunes
Errores de desarrollo a evitar con el tema de esta unidad:
-
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
versionexacto enrequired_providers,terraform initen 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.hcly realice la actualización en una solicitud de extracción dedicada.
-
Cambio de un argumento inmutable
- Problema: Cambia
locationen un centro de datos, otypeen un servidor, y el plan desea destruirlo y volver a crearlo. - Por qué ocurre: Estos argumentos son inmutables. En un servidor,
allow_replace = truelos 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 useallow_replacesolo cuando acepte la recreación.
- Problema: Cambia
-
Búsquedas de imagen ambiguas
- Problema:
terraform planfalla en la fuente de datosionoscloud_imagecon 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
typeolocation. - Solución: Agregue
location,typeycloud_inita la fuente de datos, y ejecute conTF_LOG=debugpara ver qué imágenes coincidieron.
- Problema:
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/ionosclouda una versión exacta enrequired_providers; autentíquese conIONOS_TOKEN locationen un centro de datos ytypeen 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-outy destruya los entornos efímeros
Terminología importante:
- Fijación del proveedor: Una versión exacta de
versionenrequired_providerspara 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
s3apuntando 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: