14 min de lectura

Objetivos de aprendizaje

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

  • Autenticarse en la IONOS CLOUD API v6 con un token de acceso de portador emitido desde la API de autenticación
  • Implementar un bucle de sondeo que espere a que una solicitud asíncrona alcance `DONE` antes de iniciar operaciones dependientes
  • Crear un cliente de Python con reintentos y retroceso exponencial para las respuestas `429 Too Many Requests`
  • Iterar colecciones grandes con `offset` y `limit` y seguir la URL `_links.next`
  • Aprovisionar un centro de datos y un servidor mediante curl, Python y `ionosctl`, y verificar la finalización de cada uno

Unidad 1.1: IONOS CLOUD API, autenticación y modelo asíncrono

Introducción

A lo largo de este curso, usted construirá TaskBoard, una API de gestión de tareas con un frontend web, aprovisionada y desplegada completamente mediante código desde un repositorio Git.

Antes de escribir cualquier código de Terraform, necesita comprender la capa con la que interactúa cada herramienta: la API de IONOS CLOUD. Terraform, ionosctl y los SDK envían las mismas solicitudes HTTP que usted puede enviar con curl. Cuando un pipeline falla, la causa suele ser un problema de autenticación, una solicitud que se ejecutó antes de que su predecesora terminara, o un cliente que ignoró un límite de tasa.

En esta unidad, usted generará tokens de acceso, llamará directamente a la API v6, manejará su modelo de solicitud asíncrono y añadirá reintentos con retroceso y paginación a un pequeño cliente en Python. En el laboratorio de código, aprovisionará el primer centro de datos y los servidores de TaskBoard de tres maneras.

1. La IONOS CLOUD API v6

La IONOS CLOUD API v6 es la API REST de infraestructura principal. Cubre recursos de cómputo, contenedores, redes y copias de seguridad en una única especificación OpenAPI, versión 6.0.

curl --request GET 'https://api.ionos.com/cloudapi/v6/datacenters' \
  --header 'Authorization: Bearer <access_token>'

1.1 URL base y versionado

La URL base para la API v6 es https://api.ionos.com/cloudapi/v6. Productos como Managed Kubernetes, Cross Connect, Flow Logs y Backup Service se administran a través de endpoints bajo /cloudapi/v6. Los servicios más recientes, como CDN, VPN Gateway y los servicios de base de datos, se publican como especificaciones de API independientes con sus propias URLs base y versionado.

Para DBaaS for PostgreSQL, DBaaS for MariaDB y DBaaS for In-Memory DB, utilice las API v2. Estas se ejecutan en hosts regionales con una ruta /v2:

export PG_API="https://postgresql.de-txl.ionos.com/v2"
export MARIADB_API="https://mariadb.de-txl.ionos.com/v2"

Usted utiliza estas API en el Módulo 2. La regla por ahora: verifique la URL base de cada API antes de llamarla.

1.2 Estructura de la solicitud y parámetros de consulta

Envíe JSON con Content-Type: application/json. En las solicitudes GET, depth (de 0 a 10, valor predeterminado 0) controla cuántos niveles de objetos hijos expande la respuesta, y pretty (valor predeterminado true) lo imprime con formato legible.

curl --silent 'https://api.ionos.com/cloudapi/v6/datacenters?depth=1' \
  --header "Authorization: Bearer ${IONOS_TOKEN}" | jq '.items[].properties.name'

2. Autenticación

La API v6 acepta dos métodos: un token de portador (Authorization: Bearer <access_token>) y Basic Auth (Authorization: Basic <base64(username:password)>). Utilice tokens de portador para cada carga de trabajo automatizada.

2.1 Emisión de un token de acceso

Ambos métodos llaman al mismo endpoint de la API de autenticación, GET https://api.ionos.com/auth/v1/tokens/generate. La respuesta contiene un JSON Web Token (JWT) en el campo token.

# Option A: bootstrap with your credentials (Basic Auth)
BASIC=$(printf '%s' 'username:password' | base64)
curl --silent --request GET 'https://api.ionos.com/auth/v1/tokens/generate?ttl=86400' \
  --header "Authorization: Basic ${BASIC}" | jq -r '.token'

# Option B: mint a new access token with an existing secure token
curl --silent --request GET 'https://api.ionos.com/auth/v1/tokens/generate?ttl=86400' \
  --header "Authorization: Bearer ${SECURE_TOKEN}" | jq -r '.token'

El parámetro de consulta ttl establece la vida útil del token en segundos: mínimo 60, máximo 31536000, y por defecto un token generado expira después de un año. Las vidas útiles cortas limitan el daño causado por una fuga.

Dos reglas limitan la autenticación básica. Las cuentas con autenticación de dos factores habilitada o forzada deben utilizar la autenticación con token de portador. El método de autenticación básica también se discontinuará en un futuro próximo, por lo que no debe construir nuevas automatizaciones sobre él.

2.2 Token Manager y ciclo de vida del token

En Data Center Designer (DCD), Token Manager se encuentra bajo Menú > Gestión > Token Manager. Genera tokens con uno de estos valores de tiempo de vida (TTL): 1 hora, 4 horas, 1 día, 7 días, 30 días, 60 días, 90 días, 180 días o 365 días.

Tres hechos determinan el manejo de los tokens:

  • El valor del token se muestra solo una vez, en el momento de la generación. En ese momento, puede descargarlo como un archivo de texto.
  • Puede tener hasta 100 tokens activos por usuario. Al alcanzar este límite, la API devuelve un error para los nuevos tokens.
  • Eliminar un token en Token Manager lo desactiva de inmediato, incluso si no ha expirado.

Mantenga el valor en un almacén de secretos e inyéctelo como variable de entorno:

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

2.3 Alcance con privilegios mínimos

Para limitar las acciones que puede realizar un token, genérelo bajo un subusuario dedicado cuyos grupos otorguen únicamente los privilegios que el servicio necesita. Los privilegios son concesiones para acciones específicas, como createDatacenter, createSnapshot o reserveIp. Las autorizaciones de recursos son Read, Edit y Sharing.

Para TaskBoard, cree taskboard-ci para cambios de infraestructura y un usuario de solo lectura para los scripts de monitorización. De este modo, un token de monitorización que se filtre no podrá crear recursos.

3. El modelo aprovisionamiento asíncrono

Para la API v6, los recursos se crean de forma asíncrona. Una POST que crea un recurso devuelve 202 Accepted mientras el aprovisionamiento sigue en ejecución, y la cabecera de respuesta Location contiene una URL de callback para consultar el estado de la operación.

curl --include --request POST 'https://api.ionos.com/cloudapi/v6/datacenters' \
  --header "Authorization: Bearer ${IONOS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"properties": {"name": "taskboard-dev", "location": "de/txl"}}'
HTTP/1.1 202 Accepted
Location: https://api.ionos.com/cloudapi/v6/requests/<requestId>/status
...
"metadata": { "state": "BUSY" }

3.1 Consulta del estado de la solicitud

GET /requests/{requestId}/status devuelve metadata.status, que es uno de QUEUED, RUNNING, DONE o FAILED. La consulta no es opcional: un recurso BUSY tiene al menos una solicitud de modificación pendiente, y todas las solicitudes siguientes se encolan detrás de ella.

import time
import requests

def wait_for_request(session, status_url, timeout=600):
    """Poll a request status URL until DONE; raise on FAILED or timeout."""
    deadline = time.monotonic() + timeout
    delay = 2
    while time.monotonic() < deadline:
        resp = session.get(status_url)
        resp.raise_for_status()
        meta = resp.json()["metadata"]
        if meta["status"] == "DONE":
            return
        if meta["status"] == "FAILED":
            raise RuntimeError(f"Request failed: {meta.get('message')}")
        time.sleep(delay)
        delay = min(delay * 2, 30)
    raise TimeoutError(f"Request not DONE after {timeout}s: {status_url}")

3.2 Dos tipos de errores

La validación de fallo rápido se ejecuta primero: autorización, recursos del contrato y si la configuración es compatible con el producto y la ubicación. Estos errores se devuelven de forma síncrona, y la API solo devuelve el primer error de validación que encuentra, por lo que una nueva solicitud puede revelar el siguiente.

Los errores de aprovisionamiento ocurren más tarde y aparecen en el estado de la solicitud, con un código de error en el formato VDC-x-xxx. Revise tanto la respuesta de POST como el estado final de la solicitud.

4. Construcción de un cliente resiliente

4.1 Limitación de velocidad y retroceso

Cuando se supera el límite de velocidad de solicitudes, la API devuelve 429. Tres cabeceras de respuesta le permiten regular el tráfico antes de que eso ocurra:

Cabecera Significado
X-RateLimit-Remaining Solicitudes que aún pueden realizarse sin provocar una respuesta de error
X-RateLimit-Limit Número medio de solicitudes por minuto permitido
X-RateLimit-Burst Número máximo de solicitudes de API simultáneas permitidas

Envuelva cada llamada en un reintento con retroceso exponencial y aleatorización:

import random

RETRYABLE = {429, 500, 503}

def call(session, method, url, max_attempts=6, **kwargs):
    for attempt in range(max_attempts):
        resp = session.request(method, url, **kwargs)
        if resp.status_code not in RETRYABLE:
            return resp
        retry_after = resp.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else min(2 ** attempt, 60)
        time.sleep(delay + random.uniform(0, 1))
    resp.raise_for_status()
    return resp

4.2 Paginación

Las colecciones aceptan offset (predeterminado 0) y limit (mínimo 1, máximo 10000). La respuesta contiene _links.next solo cuando offset + limit es menor que el número total de elementos.

def list_all(session, url, page_size=100):
    params = {"offset": 0, "limit": page_size}
    while url:
        page = call(session, "GET", url, params=params).json()
        yield from page.get("items", [])
        url = page.get("_links", {}).get("next")
        params = None  # the next URL already carries offset and limit

4.3 Códigos de estado y cuerpos de error

Las respuestas de error incluyen httpStatus y un arreglo messages de errorCode y message:

{ "httpStatus": 422, "messages": [ { "errorCode": "200", "message": "[VDC-yy-xxxx] ..." } ] }
Código Acción del cliente
401 Emitir un nuevo token; verificar su caducidad
403 Verificar los privilegios de grupo del usuario
404 Verificar el UUID y que la solicitud de creación sea DONE
409 Esperar a que el recurso salga de BUSY y, a continuación, reintentar
422 Corregir el cuerpo de la solicitud
429, 500, 503 Reintentar con backoff; contactar al soporte si un 500 persiste

5. SDKs e ionosctl

5.1 Los SDKs

Los SDKs que encapsulan la API v6 están disponibles para Go, Java, Ruby, Python y NodeJS, publicados en github.com/ionos-cloud/sdk-go, sdk-java, sdk-ruby, sdk-python y sdk-nodejs. Su documentación se encuentra en https://docs.ionos.com/cloud/sdk-tools-home. Los SDKs encapsulan la misma API, por lo que la regla asíncrona de la Sección 3 se aplica sin cambios. Esta unidad utiliza HTTP plano en Python para que cada encabezado quede visible.

5.2 ionosctl

Instale ionosctl con un gestor de paquetes:

brew tap ionos-cloud/homebrew-ionos-cloud && brew install ionosctl   # Homebrew
snap install ionosctl                                                 # snap
scoop install ionos-cloud/ionosctl                                    # Scoop

ionosctl verifica primero las variables de entorno (IONOS_TOKEN, o IONOS_USERNAME y IONOS_PASSWORD), y luego su archivo de configuración. Para escribir un archivo de configuración, ejecute ionosctl config login --token "$IONOS_TOKEN".

ionosctl compute datacenter list
ionosctl compute server list --all
ionosctl compute request list --cols RequestId,Method,Status,Message,Targets
ionosctl compute request wait --request-id REQUEST_ID --timeout 120

Los comandos de creación aceptan --wait (-w) para bloquear la ejecución hasta que el recurso esté AVAILABLE. --timeout limita la espera, con un valor predeterminado de 600 segundos.

Tarjeta rápida de referencia de la API

Endpoints principales de la API para el tema de esta unidad:

Método Endpoint Descripción
GET https://api.ionos.com/auth/v1/tokens/generate Emitir un nuevo token de acceso (ttl en segundos)
GET /datacenters Listar centros de datos (offset, limit, depth)
POST /datacenters Crear un centro de datos (devuelve 202 y Location)
POST /datacenters/{datacenterId}/servers Crear un servidor
GET /requests/{requestId}/status Consultar una solicitud asíncrona: QUEUED, RUNNING, DONE, FAILED

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

Laboratorio de código

Objetivo: Aprovisionar el centro de datos de desarrollo de TaskBoard con curl, agregar un servidor con Python y otro con ionosctl, y verificar la finalización asíncrona de cada uno.

Requisitos previos:

  • Cuenta de IONOS CLOUD con un token de API en IONOS_TOKEN
  • curl, jq y Python 3 con el paquete requests
  • ionosctl instalado (Sección 5.2)

Paso 1: Crear el centro de datos con curl y capturar la URL de la solicitud

RESP=$(curl --silent --dump-header headers.txt --request POST \
  'https://api.ionos.com/cloudapi/v6/datacenters' \
  --header "Authorization: Bearer ${IONOS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"properties": {"name": "taskboard-dev", "location": "de/txl"}}')
export DC_ID=$(echo "$RESP" | jq -r '.id')
export STATUS_URL=$(grep -i '^location:' headers.txt | awk '{print $2}' | tr -d '\r')
echo "$DC_ID $STATUS_URL"

Salida esperada:

<datacenter-uuid> https://api.ionos.com/cloudapi/v6/requests/<requestId>/status

Paso 2: Realizar consultas hasta que el estado sea DONE

until [ "$(curl -s "$STATUS_URL" -H "Authorization: Bearer ${IONOS_TOKEN}" | jq -r '.metadata.status')" = "DONE" ]; do
  sleep 5
done; echo "datacenter ready"

Salida esperada:

datacenter ready

Paso 3: Crear un servidor con Python

Guárdelo como create_server.py, reutilizando wait_for_request y call de las secciones 3.1 y 4.1:

import os, requests

API = "https://api.ionos.com/cloudapi/v6"
s = requests.Session()
s.headers.update({"Authorization": f"Bearer {os.environ['IONOS_TOKEN']}",
                  "Content-Type": "application/json"})

body = {"properties": {"name": "taskboard-api-py", "type": "VCPU",
                       "availabilityZone": "AUTO", "cores": 1, "ram": 2048}}
resp = call(s, "POST", f"{API}/datacenters/{os.environ['DC_ID']}/servers", json=body)
resp.raise_for_status()
wait_for_request(s, resp.headers["Location"])
print("server ready:", resp.json()["id"])

Salida esperada:

server ready: <server-uuid>

Paso 4: Crear un servidor con ionosctl

ionosctl compute server create --datacenter-id "$DC_ID" --name taskboard-api-cli \
  --type VCPU --cores 1 --ram 2GB --wait

Salida esperada:

ServerId        Name               Type   ...  State
<server-uuid>   taskboard-api-cli  VCPU   ...  AVAILABLE

Paso 5: Compare los resultados

ionosctl compute server list --datacenter-id "$DC_ID" --cols ServerId,Name,Type,Cores,State

Salida esperada:

ServerId        Name               Type   Cores   State
<uuid>          taskboard-api-py   VCPU   1       AVAILABLE
<uuid>          taskboard-api-cli  VCPU   1       AVAILABLE

Lista de verificación:

  • [ ] Centro de datos creado mediante curl y su solicitud llegó a DONE
  • [ ] Servidor Python creado y wait_for_request se devolvió sin error
  • [ ] El servidor ionosctl llegó a AVAILABLE con --wait
  • [ ] Ambos servidores muestran el mismo tipo y número de núcleos en el paso 5

Limpieza:

# Deletes the data center and every resource it contains
ionosctl compute datacenter delete --datacenter-id "$DC_ID" --force --wait

Errores comunes

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

  1. Omitir la consulta del estado de la solicitud

    • Problema: Su script crea un centro de datos y de inmediato crea un servidor en él, y luego lee el servidor antes de que exista. La lógica posterior falla o agota el tiempo de espera.
    • Por qué ocurre: La respuesta de 202 solo significa "aceptada". El centro de datos está BUSY hasta que su solicitud esté DONE.
    • Solución: Lea la cabecera Location y llame a wait_for_request() (Sección 3.1) antes de cada operación dependiente, o use --wait en ionosctl.
  2. Tratar un 202 como éxito

    • Problema: El pipeline informa en verde, pero el recurso nunca aparece.
    • Por qué ocurre: Los errores de aprovisionamiento solo aparecen en el estado de la solicitud (Sección 3.2).
    • Solución: Haga que el trabajo falle cuando el estado de la solicitud sea FAILED, y registre metadata.message.
  3. Codificar de forma fija un token personal de larga duración

    • Problema: Un token en una variable de integración continua se filtra, o deja de funcionar cuando expira y nadie sabe quién es su propietario.
    • Por qué ocurre: Los tokens se generan con una duración predeterminada de un año, y un token generado bajo una cuenta de administrador personal no está acotado a un solo servicio.
    • Solución: Genere el token bajo un subusuario dedicado con privilegios mínimos, establezca una ttl explícita y guárdelo en un almacén de secretos.

Resumen

Ahora puede comunicarse con IONOS CLOUD de la misma manera que lo hace cualquier herramienta: generar un token de portador, llamar a la API v6 y esperar a que las solicitudes asíncronas finalicen antes de construir sobre ellas. Su cliente de Python reintenta con retroceso, recorre colecciones paginadas y lee cuerpos de error estructurados. En la Unidad 1.2, Terraform asume este sondeo por usted, y conocerlo aquí le permite depurarlo allí.

Puntos clave:

  • La URL base de la API v6 es https://api.ionos.com/cloudapi/v6; las APIs de DBaaS tienen sus propios hosts regionales
  • Genere tokens de acceso con GET /auth/v1/tokens/generate, establezca ttl y almacene el valor de una sola vez
  • Una creación devuelve 202 junto con un encabezado Location; realice el sondeo de /requests/{id}/status hasta DONE
  • Los errores de validación de detección rápida son síncronos; los errores de aprovisionamiento solo aparecen en el estado de la solicitud
  • Use retroceso para 429, y pagine con offset, limit y _links.next

Terminología importante:

  • Token de acceso: Un JWT enviado como Authorization: Bearer <token>; su tiempo de vida se establece con ttl en la generación
  • Estado de la solicitud: El recurso detrás del encabezado Location; informa QUEUED, RUNNING, DONE o FAILED
  • BUSY: Estado del recurso que significa que al menos una solicitud de modificación está pendiente; las solicitudes adicionales se encolan
  • Validación de detección rápida: Verificaciones síncronas antes de encolar; la API devuelve solo el primer error que encuentra
  • depth: Parámetro de consulta (de 0 a 10) que controla cuántos niveles de objetos hijos expande una respuesta

Próximos pasos

Siga aprendiendo: Unidad 1.2: Terraform Provider and Core Patterns

Temas relacionados: