Unidad 2.4: Aprovisionamiento de almacenamiento como código

Introducción

Está construyendo la capa de almacenamiento de TaskBoard, y cada elemento del estado se ubica en un lugar diferente. El servidor de API necesita un volumen de datos persistente que sobreviva a los reinicios y se comporte como un disco local. Los archivos adjuntos subidos por los usuarios deben almacenarse en un almacén de objetos al que se accede mediante HTTP con credenciales de S3, no estar acoplados a una sola VM. Y si más adelante ejecuta varios trabajadores que leen el mismo conjunto de archivos, desea un sistema de archivos compartido en lugar de copias en cada nodo.

Los tres se aprovisionan de la misma manera: recursos declarativos de Terraform contra la API de IONOS CLOUD, con el mismo modelo asíncrono de creación y espera que ha utilizado desde la Unidad 1.1. Las diferencias que le afectan son las restricciones. Block Storage y Compute no comparten las mismas zonas de disponibilidad. Object Storage no utiliza su token de portador en absoluto. NFS solo habla una versión de protocolo. Esta unidad examina cada tipo de almacenamiento a nivel de código y muestra en qué punto estas restricciones cambian lo que escribe.

1. Volumes de Block Storage con Terraform

Block Storage se aprovisiona como ionoscloud_volume y se comporta como un dispositivo de bloque iSCSI adjunto a un servidor. Usted declara el tamaño, el tipo de almacenamiento y la zona de disponibilidad, y Terraform gestiona el aprovisionamiento asíncrono y la adjunción. Un Volume se crea dentro de un centro de datos y se vincula a un único servidor a través del atributo server_id.

El tamaño mínimo del Volume es de 1 GiB y el máximo es de 4096 GiB (4 TiB) para todos los tipos de Block Storage. Se pueden solicitar Volumes de mayor tamaño a través de IONOS CLOUD Support. El tipo de almacenamiento no puede modificarse después del aprovisionamiento, por lo que debe seleccionarlo correctamente en el momento de la creación en lugar de planificar una conversión posterior.

1.1 Declaración y adjunción de un Volume

La siguiente configuración crea un Volume de datos SSD Premium y lo adjunta al servidor de la API de TaskBoard. Los atributos image_name y image_password (o ssh_key_path) son obligatorios cuando el Volume es arrancable; para un disco de datos puro, usted proporciona un licence_type en su lugar y omite la imagen.

resource "ionoscloud_datacenter" "taskboard" {
  name     = "taskboard"
  location = "de/txl"
}

resource "ionoscloud_volume" "api_data" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  server_id     = ionoscloud_server.api.id
  name          = "taskboard-api-data"
  size          = 50
  disk_type     = "SSD Premium"
  licence_type  = "LINUX"
  availability_zone = "AUTO"
}

El disk_type acepta las variantes de tecnología de almacenamiento que expone Block Storage: HDD, SSD Premium y SSD Standard. SSD Premium ofrece el mayor IOPS por Volume, SSD Standard prioriza el costo sobre el rendimiento, y HDD es la opción giratoria de menor costo. Las tres tienen un límite de 4 TiB (4096 GiB) por Volume, con un mínimo de 1 GiB.

1.2 La trampa de la zona de disponibilidad

Las zonas de disponibilidad de Block Storage no son el mismo conjunto que las zonas de disponibilidad de Compute, y este es el error de aprovisionamiento más común en la capa de almacenamiento. Block Storage admite Zone 1, Zone 2, Zone 3 y Auto. Los servidores de Compute solo admiten las zonas 1, 2 y Auto. La zona 3 existe para almacenamiento, pero no hay una zona 3 para compute.

Esto es importante porque un Volume y el servidor al que se adjunta residen en el mismo centro de datos, pero se colocan mediante configuraciones de zona independientes. Si usted fija un Volume en una zona que no se alinea con su estrategia de colocación de servidores, restringirá la programación sin obtener ningún beneficio. El valor predeterminado seguro es AUTO tanto en el servidor como en el Volume, a menos que tenga un requisito específico de fijación de zona.

// Safe default: let the platform place both
resource "ionoscloud_server" "api" {
  datacenter_id     = ionoscloud_datacenter.taskboard.id
  name              = "taskboard-api"
  cores             = 4
  ram               = 8192
  availability_zone = "AUTO" // Zone 1, 2, or AUTO only - never Zone 3
}

resource "ionoscloud_volume" "api_data" {
  # ...
  availability_zone = "AUTO"   # Zone 1, 2, 3, or AUTO permitted for storage
}

Los Volumes pueden combinarse entre tipos en una sola VM. Un servidor puede tener tanto Volumes de SSD como de HDD al mismo tiempo. Una VM admite hasta 24 Volumes adjuntos de cualquier combinación de tipos de almacenamiento; el conteo se comparte entre todos los tipos, no por tipo. Planifique las configuraciones con múltiples Volumes con respecto a ese límite de 24 Volumes.

1.3 Contexto de cifrado y durabilidad

Block Storage proporciona almacenamiento con doble redundancia: los datos se escriben en dos servidores de almacenamiento, cada uno protegido por RAID, para lograr redundancia a nivel de plataforma. El cifrado en reposo para los Volumes lógicos utiliza el algoritmo AES-XTS. No configura ninguno de ellos en el recurso de Volume; ambos son propiedades de la capa de almacenamiento de la plataforma, por lo que su Terraform se centra en el tamaño, el tipo y la ubicación.

2. Cubos de Object Storage y claves de acceso

Object Storage se aprovisiona con ionoscloud_s3_bucket, y sus credenciales de acceso se generan con ionoscloud_s3_key. La diferencia crítica frente a cualquier otro recurso de este curso: Object Storage no autentica con su token de portador de IONOS CLOUD. Implementa la API de AWS S3 y autentica con una Access Key y una Secret Key. Su aplicación, su pipeline de CI y cualquier cliente de S3 utilizan esas claves, nunca el token de la API de la nube.

resource "ionoscloud_s3_key" "taskboard" {
  user_id = var.user_id
}

resource "ionoscloud_s3_bucket" "attachments" {
  name = "taskboard-attachments-prod"
}

Los nombres de bucket deben ser únicos a nivel global en todos los inquilinos de Object Storage y deben tener entre 3 y 63 caracteres. Trate el nombre como una etiqueta de DNS, en minúsculas y con guiones, y asuma que los nombres evidentes ya están en uso. Una colisión de nombres se manifiesta como un fallo de creación en el momento de la aplicación, no en el momento de la planificación.

2.1 Salida de credenciales como valores sensibles

El recurso ionoscloud_s3_key genera una clave de acceso y una clave secreta. La clave secreta nunca debe aparecer en registros ni en la salida en texto plano. Marque las salidas como sensitive = true para que Terraform las oculte en la salida de la CLI y en los registros de CI; los valores siguen almacenándose en el estado, por lo que proteja el backend del estado de manera adecuada.

output "s3_access_key" {
  value     = ionoscloud_s3_key.taskboard.id
  sensitive = true
}

output "s3_secret_key" {
  value     = ionoscloud_s3_key.taskboard.secret_key
  sensitive = true
}

output "s3_bucket_name" {
  value = ionoscloud_s3_bucket.attachments.name
}

Una clave de acceso tiene 92 caracteres y una clave secreta tiene 64 caracteres. Cada usuario puede tener hasta 5 claves de acceso, lo cual es suficiente para realizar la rotación sin tiempo de inactividad: cree la nueva clave, actualice la configuración de su aplicación y luego elimine la clave anterior. Las credenciales no están vinculadas a una región o a un bucket específico; un par de claves funciona en todos los buckets a los que el usuario puede acceder.

2.2 Puntos de acceso y regiones

Object Storage expone la API estándar S3 v2, y se accede a ella a través de un punto de acceso específico de la región. A diferencia de AWS, debe establecer el punto de acceso de forma explícita en cada cliente, ya que los puntos de acceso predeterminados de AWS no se resolverán. La siguiente tabla enumera los puntos de acceso del servicio a los que su código y el backend de Terraform harán referencia.

Seleccione el punto de acceso que corresponda a la región donde cree el bucket y reutilícelo en todas partes: en boto3, en el bloque de backend S3 a continuación y en cualquier generación de URL prefirmada. Las conexiones utilizan TLS, con soporte para TLS 1.2 y 1.3. El tamaño máximo de objeto es de 5 TB. Object Storage ofrece una única clase de almacenamiento, STANDARD, y un bucket admite hasta 1000 reglas de ciclo de vida para la expiración de objetos; las reglas de ciclo de vida no pueden transicionar objetos a otra clase de almacenamiento (no existe un nivel frío ni de archivo).

3. Object Storage como backend de estado de Terraform

Dado que Object Storage es compatible con S3, también funciona como un backend de estado remoto para Terraform. Esto resuelve el problema que se presentó en la Unidad 1.2: el estado local no se conserva entre un equipo o un ejecutor de CI. Almacenar el estado en un bucket proporciona a cada ejecución de la pipeline una fuente de verdad compartida y duradera.

3.1 Configuración del backend

El backend s3 requiere el punto de acceso de IONOS CLOUD y las mismas banderas de omisión que se utilizan para cualquier implementación de S3 que no sea de AWS, ya que de lo contrario el backend intenta validar contra las reglas de cuenta y región de AWS que no son aplicables.

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

Proporcione la clave de acceso y la clave secreta al backend mediante variables de entorno (AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY) en lugar de codificarlas de forma fija. El bucket de estado debe existir ya antes de terraform init, por lo que debe aprovisionarlo una sola vez con una configuración de arranque pequeña o con ionosctl, y luego dirija el backend de su stack principal hacia él.

3.2 Por qué esto es importante para la pipeline

El bucket de estado contiene sus claves secretas de S3 y las cadenas de conexión de la base de datos dentro del archivo de estado. Restricta quién puede leerlo. Un patrón práctico es un bucket por entorno, con prefijos de clave separados por stack, de modo que una pipeline de desarrollo no pueda leer el estado de producción. Esto se aplica directamente al trabajo de CI/CD en el Módulo 3, donde las mismas credenciales se convierten en secretos de la pipeline.

4. Almacenamiento compartido NFS

Cuando varios servidores necesitan leer y escribir los mismos archivos, ni un volumen de Block Storage de un solo adjunto ni un almacén de objetos encajan de forma adecuada. NFS le proporciona un sistema de archivos POSIX montado de forma concurrente en clientes Linux. Se aprovisiona mediante dos recursos: ionoscloud_nfs_cluster define el clúster, y ionoscloud_nfs_share define una unidad compartida dentro de este. Se aplican el mismo ciclo de vida asíncrono y la limpieza de terraform destroy.

resource "ionoscloud_nfs_cluster" "shared" {
  name     = "taskboard-shared"
  location = "de/txl"
  size     = 2

  nfs {
    min_version = "4.2"
  }

  connections {
    datacenter_id = ionoscloud_datacenter.taskboard.id
    ip_address    = "10.7.222.100/24"
    lan           = ionoscloud_lan.app.id
  }
}

resource "ionoscloud_nfs_share" "uploads" {
  cluster_id = ionoscloud_nfs_cluster.shared.id
  location   = ionoscloud_nfs_cluster.shared.location
  name       = "uploads"
  quota      = 1024
  gid        = 1000
  uid        = 1000
}

4.1 Restricciones de protocolo y capacidad

NFS en IONOS CLOUD solo admite NFSv4.2. NFSv3 no está soportado, por lo que cualquier herramienta de cliente o entrada en fstab fijada en v3 no logrará montar el recurso. El tamaño del Cluster va desde un mínimo de 2 TiB hasta un máximo de 42 TiB, y toda la capacidad aprovisionada es totalmente utilizable. Las cuotas de las comparticiones se expresan en MiB.

El cifrado en reposo lo proporciona la plataforma. El cifrado en tránsito no está documentado para NFS, por lo que, para datos sensibles, mantenga la compartición en una LAN privada y confíe en el aislamiento de red en lugar de esperar TLS en el montaje. El Cluster opera en un modo de alta disponibilidad Activo-Pasivo y se accede a él mediante una IP privada que usted asigna en el bloque connections.

4.2 Montaje de la compartición

Tras la aplicación, la compartición se monta desde un cliente Linux utilizando la IP del Cluster y el UUID de la compartición devuelto en la salida nfs_path del recurso. Linux es el sistema operativo de cliente soportado.

sudo mount -t nfs 10.7.222.100:/<share-uuid> /mnt/uploads

Se admite la compresión de root, por lo que debe mapear el UID y el GID de la unidad de almacenamiento para que coincidan con el usuario de la aplicación que lee y escribe los archivos, como lo indican los argumentos uid y gid anteriores. La propiedad no coincidente es la causa habitual de los errores de permiso denegado inmediatamente después de un montaje exitoso.

5. Elegir el almacenamiento adecuado en código

Cada tipo de almacenamiento se corresponde con un patrón de acceso diferente, y elegir mal se manifiesta como una restricción con la que hay que luchar o como una factura que no se esperaba. Block Storage se adjunta a exactamente un servidor y se comporta como un disco local: úsese para bases de datos, volúmenes del sistema operativo y cualquier carga de trabajo de un solo escritor. Object Storage se accede mediante HTTP con credenciales S3 y escala de forma independiente de cualquier VM: úsese para cargas de usuarios, copias de seguridad, recursos estáticos y el estado de Terraform. NFS proporciona acceso POSIX concurrente entre muchos clientes Linux: úsese solo cuando varios servidores deban compartir genuinamente un sistema de archivos.

La siguiente tabla resume la decisión a nivel de lo que se necesita al escribir Terraform.

Para TaskBoard, esto se resuelve de forma clara. El volumen de datos del servidor de API es Block Storage, adjunto a un solo servidor y dimensionado para el conjunto de trabajo. Los archivos adjuntos van a Object Storage porque el navegador sube directamente con URLs prefirmadas y la API nunca proxy los bytes. NFS no se utiliza en la compilación base de TaskBoard; es el patrón al que se recurre más adelante si se añade una flota de trabajadores que debe compartir un directorio de contenido.

Tarjeta rápida de referencia de la API

Puntos finales de API clave para la aprovisionación de almacenamiento:

URL base de la API de la nube: https://api.ionos.com/cloudapi/v6 Punto final S3 de Object Storage: https://s3.eu-central-4.ionoscloud.com (específico de la región) URL base de la API de NFS: https://nfs.{region}.ionos.com Autenticación: La API de la nube utiliza Authorization: Bearer <token>; Object Storage utiliza Access Key + Secret Key (firma de AWS)

Laboratorio de código

Objetivo: Desplegar la capa de almacenamiento de TaskBoard con Terraform: un volumen de datos de Block Storage conectado al servidor de API y un contenedor de Object Storage con las credenciales de acceso como valores sensibles de salida.

Requisitos previos:

• Cuenta de IONOS CLOUD con token de API (IONOS_TOKEN exportado)
• Terraform 1.5 o superior con el proveedor ionos-cloud/ionoscloud
• Un centro de datos y un servidor de API existentes (del laboratorio de la Unidad 2.1) o créelos en línea

Paso 1: Fijar el proveedor

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

provider "ionoscloud" {}

Salida esperada:

(no output; init resolves the provider in Step 4)

Paso 2: Declarar el volumen de datos de Block Storage

variable "user_id" { type = string }

resource "ionoscloud_volume" "api_data" {
  datacenter_id     = var.datacenter_id
  server_id         = var.server_id
  name              = "taskboard-api-data"
  size              = 50
  disk_type         = "SSD Premium"
  licence_type      = "LINUX"
  availability_zone = "AUTO"
}

Paso 3: Declarar el bucket y la clave de Object Storage

resource "ionoscloud_s3_key" "taskboard" {
  user_id = var.user_id
}

resource "ionoscloud_s3_bucket" "attachments" {
  name = "taskboard-attachments-${var.user_id}"
}

output "s3_access_key" {
  value     = ionoscloud_s3_key.taskboard.id
  sensitive = true
}

output "s3_secret_key" {
  value     = ionoscloud_s3_key.taskboard.secret_key
  sensitive = true
}

Paso 4: Inicializar y planificar

terraform init
terraform plan -out=storage.plan

Salida esperada:

Plan: 3 to add, 0 to change, 0 to destroy.
Changes to Outputs:
  + s3_access_key = (sensitive value)
  + s3_secret_key = (sensitive value)

Paso 5: Aplicar

terraform apply storage.plan

Salida esperada:

ionoscloud_s3_key.taskboard: Creation complete
ionoscloud_s3_bucket.attachments: Creation complete
ionoscloud_volume.api_data: Creation complete after 1m12s
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Paso 6: Leer las credenciales sensibles

terraform output -raw s3_access_key
terraform output -raw s3_secret_key

Salida esperada:

(a 92-character access key, then a 64-character secret key)

Paso 7: Verificar el bucket con un cliente de S3

export AWS_ACCESS_KEY_ID=$(terraform output -raw s3_access_key)
export AWS_SECRET_ACCESS_KEY=$(terraform output -raw s3_secret_key)

aws --endpoint-url https://s3.eu-central-4.ionoscloud.com s3 ls

Salida esperada:

2026-06-05 12:01:33 taskboard-attachments-<user_id>

Lista de verificación de validación:

• [ ] El Volume muestra Creation complete y está adjunto al servidor de API
• [ ] terraform output devuelve entradas de (sensitive value) censuradas sin -raw
• [ ] El cliente S3 enumera el bucket usando Access Key + Secret Key, no el bearer token

Limpieza:

terraform destroy -auto-approve

Errores comunes

Errores de desarrollo a evitar al aprovisionar almacenamiento en IONOS CLOUD:

1. Fijar un volumen en la zona 3 mientras el servidor está en la zona 1 o 2

   • Problema: Un volumen creado en ZONE_3 no puede colocarse en el mismo sitio que un servidor de cómputo, porque Compute no tiene zona 3.
   • Por qué ocurre: Las zonas de disponibilidad de Block Storage son Zone 1, Zone 2, Zone 3, Auto, pero Compute solo admite Zone 1, Zone 2, Auto. Los desarrolladores asumen que los conjuntos de zonas coinciden.
   • Solución: Use availability_zone = "AUTO" tanto en el servidor como en el volumen, a menos que tenga un plan deliberado de fijación de zona, y no establezca nunca ZONE_3 en un servidor.

2. Enviar el token de portador de IONOS CLOUD a Object Storage

   • Problema: Las solicitudes S3 devuelven 403 SignatureDoesNotMatch o AccessDenied, aunque su token de API de la nube sea válido.
   • Por qué ocurre: Object Storage implementa la API de AWS S3 y autentica con una Access Key y una Secret Key. El token de portador utilizado para api.ionos.com no es aceptado por el punto de acceso S3.
   • Solución: Genere credenciales con ionoscloud_s3_key, establezca AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY, y pase siempre la URL explícita del punto de acceso S3 de IONOS CLOUD.

3. Montar una unidad NFS con NFSv3

   • Problema: mount -t nfs -o vers=3 ... se queda colgado o falla; la unidad rechaza la conexión.
   • Por qué ocurre: IONOS CLOUD NFS solo admite NFSv4.2. NFSv3 no está disponible, por lo que cualquier opción de montaje fijada a v3 o entrada heredada de fstab no negociará.
   • Solución: Monte sin una opción de v3 (NFSv4.2 se negocia de forma predeterminada) y alinee la uid/gid de la unidad con el usuario de la aplicación, ya que el root squash está en vigor:

   sudo mount -t nfs 10.7.222.100:/<share-uuid> /mnt/uploads
   

Resumen

Ahora puede aprovisionar los tres niveles de almacenamiento de IONOS CLOUD por completo en Terraform e integrarlos en una aplicación. Los volúmenes de Block Storage se adjuntan a un solo servidor con ionoscloud_volume, con un tamaño entre 1 GiB y 4 TiB, y el tipo de almacenamiento y la zona se fijan en el momento de la creación. Los cubos de Object Storage y las claves S3 se declaran con ionoscloud_s3_bucket y ionoscloud_s3_key, autenticados con Access Key y Secret Key en lugar de su token de portador, y los mismos cubos respaldan el estado remoto de Terraform. Los clústeres y las participaciones de NFS ofrecen acceso concurrente NFSv4.2 para los casos en los que muchos clientes Linux deben compartir un sistema de archivos. La lección recurrente es que las restricciones, y no la sintaxis de los recursos, determinan su diseño: las incompatibilidades de zona, el modelo de autenticación S3 y la versión del protocolo NFS son donde se pierde tiempo en producción.

Puntos clave:

• ionoscloud_volume aprovisiona Block Storage de 1 GiB a 4 TiB; el tipo de almacenamiento y la zona son inmutables después de la creación
• Block Storage admite la Zona 1, 2, 3 y Auto, pero Compute no tiene Zona 3; establezca ambos en AUTO por defecto
• Object Storage se autentica con Access Key + Secret Key a través de un endpoint S3 específico de la región, nunca con el token de portador de IONOS CLOUD
• Los cubos de Object Storage funcionan como un backend de estado remoto de Terraform compatible con S3 con las banderas de omisión de validación establecidas
• NFS proporciona almacenamiento compartido NFSv4.2 de 2 TiB a 42 TiB; NFSv3 no está admitido

Terminología importante:

• ionoscloud_volume: Recurso de Terraform para un volumen iSCSI de Block Storage adjunto a un solo servidor.
• ionoscloud_s3_key: Recurso de Terraform que genera un par de Access Key y Secret Key para Object Storage; se muestra como sensible.
• Endpoint S3: URL específica de la región (por ejemplo s3.eu-central-1.ionoscloud.com) que todos los clientes de Object Storage deben establecer explícitamente.
• Backend de estado remoto: Un almacén compartido y duradero para el estado de Terraform; un cubo de Object Storage configurado con el tipo de backend s3.
• Root squash: Comportamiento de NFS que mapea la raíz del cliente a una identidad sin privilegios; requiere alinear la participación uid/gid con el usuario de la aplicación.

Próximos pasos

Continuar aprendiendo: Unidad 2.5: Aprovisionamiento de base de datos y servicio de streaming

Temas relacionados:

• Unidad 1.2: Terraform Provider y patrones principales
• Unidad 4.2: Integración de Object Storage