14 min de lecture

Objectifs d'apprentissage

À la fin de ce module, vous serez en mesure de:

  • Vous authentifier auprès de l'API IONOS CLOUD v6 à l'aide d'un jeton d'accès bearer émis par l'API d'authentification
  • Mettre en œuvre une boucle de sondage qui attend qu'une requête asynchrone atteigne l'état `DONE` avant de démarrer les opérations dépendantes
  • Construire un client Python avec des tentatives répétées et un repli exponentiel pour les réponses `429 Too Many Requests`
  • Parcourir de grandes collections à l'aide de `offset` et `limit`, et suivre l'URL `_links.next`
  • Provisionner un centre de données et un serveur via curl, Python et `ionosctl`, et vérifier l'achèvement de chaque opération

Unité 1.1 : IONOS CLOUD API, authentification et modèle asynchrone

Introduction

Tout au long de ce cours, vous créez TaskBoard, une API de gestion de tâches avec un frontend web, provisionnée et déployée entièrement par le code à partir d'un dépôt Git.

Avant d'écrire du Terraform, vous devez comprendre la couche avec laquelle chaque outil communique : l'API IONOS CLOUD. Terraform, ionosctl et les SDK envoient les mêmes requêtes HTTP que vous pouvez envoyer avec curl. Lorsqu'un pipeline échoue, la cause est souvent un problème d'authentification, une requête exécutée avant la fin de sa prédécesseure, ou un client qui a ignoré une limite de débit.

Dans cette unité, vous créez des jetons d'accès, appelez directement l'API v6, gérez son modèle de requêtes asynchrones, et ajoutez le backoff et la pagination à un petit client Python. Dans le Code Lab, vous provisionnez le premier centre de données et les serveurs de TaskBoard de trois manières.

1. L'API IONOS CLOUD v6

L'API IONOS CLOUD v6 est l'API REST d'infrastructure principale. Elle couvre les ressources de calcul, de conteneurs, de réseau et de sauvegarde dans une seule spécification OpenAPI, version 6.0.

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

1.1 Adresses URL de base et gestion des versions

L'adresse URL de base pour l'API v6 est https://api.ionos.com/cloudapi/v6. Les produits tels que Managed Kubernetes, Cross Connect, Flow Logs et Backup Service sont gérés via des points de terminaison situés sous /cloudapi/v6. Les services plus récents, tels que CDN, VPN Gateway et les services de base de données, sont publiés sous forme de spécifications API autonomes distinctes, avec leurs propres adresses URL de base et leur propre gestion des versions.

Pour DBaaS for PostgreSQL, DBaaS for MariaDB et DBaaS for In-Memory DB, utilisez les API v2. Elles fonctionnent sur des hôtes régionaux avec un chemin /v2 :

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

Vous utilisez ces API dans le Module 2. La règle pour le moment : vérifiez l'URL de base de chaque API avant de l'appeler.

1.2 Structure de la requête et paramètres de requête

Envoyez du JSON avec Content-Type: application/json. Pour les requêtes GET, depth (de 0 à 10, valeur par défaut 0) contrôle le nombre de niveaux d'objets enfants que la réponse développe, et pretty (valeur par défaut true) met la sortie en forme lisible.

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

2. Authentification

L'API v6 accepte deux méthodes : un jeton bearer (Authorization: Bearer <access_token>) et l'authentification de base (Authorization: Basic <base64(username:password)>). Utilisez des jetons bearer pour toute charge de travail automatisée.

2.1 Émission d'un jeton d'accès

Les deux méthodes appellent le même point d'entrée de l'API d'authentification, GET https://api.ionos.com/auth/v1/tokens/generate. La réponse contient un JSON Web Token (JWT) dans le champ 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'

Le paramètre de requête ttl définit la durée de validité du jeton en secondes : minimum 60, maximum 31536000, et par défaut, un jeton généré expire après un an. Des durées de validité courtes limitent les dégâts en cas de fuite.

Deux règles limitent l'authentification de base. Les comptes avec l'authentification à deux facteurs activée ou imposée doivent utiliser l'authentification par jeton porteur. La méthode d'authentification de base sera également abandonnée à brève échéance, il ne faut donc pas construire de nouvelles automatisations sur cette base.

2.2 Token Manager et cycle de vie des jetons

Dans Data Center Designer (DCD), le Token Manager se trouve sous Menu > Management > Token Manager. Il génère des jetons avec l'une de ces valeurs de durée de vie (TTL) : 1 heure, 4 heures, 1 jour, 7 jours, 30 jours, 60 jours, 90 jours, 180 jours ou 365 jours.

Trois faits structurent la gestion des jetons :

  • La valeur du jeton n'est affichée qu'une seule fois, lors de sa génération. Vous pouvez la télécharger au format fichier texte à ce moment-là.
  • Vous pouvez disposer de 100 jetons actifs par utilisateur au maximum. Lorsque cette limite est atteinte, l'API renvoie une erreur pour les nouveaux jetons.
  • La suppression d'un jeton dans le Token Manager le désactive immédiatement, même s'il n'a pas expiré.

Conservez la valeur dans un coffre-fort de secrets et injectez-la en tant que variable d'environnement :

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

2.3 Limitation des privilèges au minimum

Pour restreindre les actions qu'un jeton peut effectuer, générez-le sous un sous-utilisateur dédié dont les groupes n'accordent que les privilèges nécessaires au service. Les privilèges sont des autorisations pour des actions spécifiques, telles que createDatacenter, createSnapshot ou reserveIp. Les autorisations de ressources sont Read, Edit et Sharing.

Pour TaskBoard, créez taskboard-ci pour les modifications d'infrastructure et un utilisateur en lecture seule pour les scripts de surveillance. Un jeton de surveillance compromis ne pourra alors pas créer de ressources.

3. Le modèle d'approvisionnement asynchrone

Pour l'API v6, les ressources sont créées de manière asynchrone. Un POST qui crée une resource renvoie 202 Accepted pendant que l'approvisionnement est toujours en cours, et l'en-tête de réponse Location contient une URL de rappel pour interroger l'état de l'opération.

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 Statut de la demande de sondage

GET /requests/{requestId}/status renvoie metadata.status, qui est l'un des éléments suivants : QUEUED, RUNNING, DONE ou FAILED. Le sondage n'est pas facultatif : une ressource BUSY a au moins une demande de modification en attente, et toutes les demandes suivantes sont mises en file d'attente derrière celle-ci.

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 Deux types d'erreurs

La validation en échec rapide s'exécute en premier : autorisation, ressources du contrat, et vérification que la configuration est compatible avec le produit et l'emplacement. Ces erreurs sont renvoyées de manière synchrone, et l'API ne renvoie que la première erreur de validation détectée, de sorte qu'une nouvelle tentative peut révéler l'erreur suivante.

Les erreurs de provisionnement surviennent plus tard et apparaissent dans l'état de la requête, avec un code d'erreur au format VDC-x-xxx. Vérifiez à la fois la réponse POST et l'état final de la requête.

4. Construction d'un client résilient

4.1 Limitation de débit et repli exponentiel

Lorsque vous dépassez la limite de débit des requêtes, l'API renvoie 429. Trois en-têtes de réponse vous permettent de réguler le débit avant que cela ne se produise :

En-tête Signification
X-RateLimit-Remaining Nombre de requêtes qui peuvent encore être effectuées sans déclencher une réponse d'échec
X-RateLimit-Limit Nombre moyen de requêtes par minute autorisé
X-RateLimit-Burst Nombre maximal de requêtes API simultanées autorisé

Enveloppez chaque appel dans une nouvelle tentative avec repli exponentiel et gigue :

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 Pagination

Les collections acceptent offset (valeur par défaut 0) et limit (minimum 1, maximum 10000). La réponse contient _links.next uniquement lorsque offset + limit est inférieur au nombre total d'éléments.

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 Codes de statut et corps d'erreur

Les réponses d'erreur contiennent httpStatus et un tableau messages de errorCode et message :

{ "httpStatus": 422, "messages": [ { "errorCode": "200", "message": "[VDC-yy-xxxx] ..." } ] }
Code Action du client
401 Émettre un nouveau jeton ; vérifier son expiration
403 Vérifier les privilèges de groupe de l'utilisateur
404 Vérifier l'UUID, et que la demande de création est DONE
409 Attendre que la ressource sorte de l'état BUSY, puis réessayer
422 Corriger le corps de la demande
429, 500, 503 Réessayer avec un délai d'attente ; contacter le support si un 500 persiste

5. SDK et ionosctl

5.1 Les SDK

Les SDK qui encapsulent l'API v6 sont disponibles pour Go, Java, Ruby, Python et NodeJS, publiés sur github.com/ionos-cloud/sdk-go, sdk-java, sdk-ruby, sdk-python et sdk-nodejs. Leur documentation est disponible sur https://docs.ionos.com/cloud/sdk-tools-home. Les SDK encapsulent la même API, donc la règle asynchrone de la section 3 s'applique sans modification. Cette unité utilise HTTP pur en Python afin que chaque en-tête reste visible.

5.2 ionosctl

Installez ionosctl à l'aide d'un gestionnaire de paquets :

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

ionosctl vérifie d'abord les variables d'environnement (IONOS_TOKEN, ou IONOS_USERNAME et IONOS_PASSWORD), puis son fichier de configuration. Pour écrire un fichier de configuration, exécutez 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

Les commandes de création acceptent --wait (-w) pour bloquer jusqu'à ce que la ressource soit AVAILABLE. --timeout limite l'attente, 600 secondes par défaut.

Fiche de référence rapide de l'API

Principaux points de terminaison de l'API pour le sujet de cette unité :

Méthode Point de terminaison Description
GET https://api.ionos.com/auth/v1/tokens/generate Émettre un nouveau jeton d'accès (ttl en secondes)
GET /datacenters Lister les centres de données (offset, limit, depth)
POST /datacenters Créer un centre de données (renvoie 202 et Location)
POST /datacenters/{datacenterId}/servers Créer un serveur
GET /requests/{requestId}/status Interroger une requête asynchrone : QUEUED, RUNNING, DONE, FAILED

URL de base : https://api.ionos.com/cloudapi/v6 Authentification : Authorization: Bearer <token>

Atelier de code

Objectif : Provisionner le centre de données de développement de TaskBoard à l'aide de curl, ajouter un serveur avec Python et un avec ionosctl, et vérifier l'achèvement asynchrone pour chacun.

Prérequis :

  • Compte IONOS CLOUD avec un jeton API dans IONOS_TOKEN
  • curl, jq et Python 3 avec le package requests
  • ionosctl installé (section 5.2)

Étape 1 : Créer le centre de données avec curl et capturer l'URL de la requête

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"

Sortie attendue :

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

Étape 2 : Interroger jusqu'à l'achèvement

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

Sortie attendue :

datacenter ready

Étape 3 : Créer un serveur avec Python

Enregistrez sous create_server.py, en réutilisant wait_for_request et call des sections 3.1 et 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"])

Sortie attendue :

server ready: <server-uuid>

Étape 4 : Créer un serveur avec ionosctl

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

Sortie attendue :

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

Étape 5 : Comparer les résultats

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

Sortie attendue :

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

Liste de contrôle de validation :

  • [ ] Centre de données créé via curl et sa requête a atteint DONE
  • [ ] Serveur Python créé et wait_for_request renvoyé sans erreur
  • [ ] Le serveur ionosctl a atteint AVAILABLE avec --wait
  • [ ] Les deux serveurs affichent le même type et le même nombre de cœurs à l'étape 5

Nettoyage :

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

Erreurs courantes

Erreurs de développement à éviter concernant le sujet de cette unité :

  1. Oubli de l'interrogation de la requête

    • Problème : Votre script crée un centre de données et crée immédiatement un serveur à l'intérieur, puis lit le serveur avant qu'il n'existe. La logique subséquente échoue ou expirée.
    • Pourquoi cela arrive : La réponse 202 ne signifie que « accepté ». Le centre de données est BUSY tant que sa requête n'est pas DONE.
    • Correction : Lire l'en-tête Location et appeler wait_for_request() (Section 3.1) avant toute opération dépendante, ou utiliser --wait dans ionosctl.
  2. Considérer un 202 comme un succès

    • Problème : Le pipeline signale le vert, mais la ressource n'apparaît jamais.
    • Pourquoi cela arrive : Les erreurs de provisionnement n'apparaissent que dans l'état de la requête (Section 3.2).
    • Correction : Échouer le travail lorsque l'état de la requête est FAILED, et consigner metadata.message.
  3. Codage en dur d'un jeton personnel à longue durée de vie

    • Problème : Un jeton dans une variable CI fuit, ou cesse de fonctionner lorsqu'il expire et personne ne sait qui en est le propriétaire.
    • Pourquoi cela arrive : Les jetons sont générés avec une durée de vie par défaut d'un an, et un jeton généré sous un compte d'administrateur personnel n'est pas limité à un service.
    • Correction : Générer le jeton sous un sous-utilisateur dédié avec des privilèges minimaux, définir une ttl explicite, et le stocker dans un coffre de secrets.

Résumé

Vous pouvez désormais interagir avec IONOS CLOUD de la même manière que tous les outils : générer un jeton bearer, appeler l'API v6, et attendre la fin des requêtes asynchrones avant de construire dessus. Votre client Python effectue des nouvelles tentatives avec un recul, parcourt les collections paginées et lit les corps d'erreur structurés. Dans l'unité 1.2, Terraform prend en charge cette surveillance pour vous, et la connaître ici vous permet de la déboguer là-bas.

Points clés :

  • L'URL de base de l'API v6 est https://api.ionos.com/cloudapi/v6 ; les API DBaaS ont leurs propres hôtes régionaux
  • Générez des jetons d'accès avec GET /auth/v1/tokens/generate, définissez ttl, et stockez la valeur en une seule fois
  • Une création renvoie 202 ainsi qu'un en-tête Location ; surveillez /requests/{id}/status jusqu'à DONE
  • Les erreurs de validation en mode échec rapide sont synchrones ; les erreurs de provisionnement n'apparaissent que dans l'état de la requête
  • Utilisez un recul pour 429, et paginez avec offset, limit et _links.next

Terminologie importante :

  • Jeton d'accès : Un JWT envoyé en tant que Authorization: Bearer <token> ; sa durée de vie est définie avec ttl lors de la génération
  • État de la requête : La ressource derrière l'en-tête Location ; signale QUEUED, RUNNING, DONE ou FAILED
  • BUSY : État de la ressource indiquant qu'au moins une requête de modification est en attente ; les requêtes suivantes sont mises en file d'attente
  • Validation en mode échec rapide : Vérifications synchrones avant la mise en file d'attente ; l'API ne renvoie que la première erreur trouvée
  • depth : Paramètre de requête (de 0 à 10) qui contrôle le nombre de niveaux d'objets enfants qu'une réponse développe

Prochaines étapes

Continuer l'apprentissage : Unité 1.2 : Fournisseur Terraform et motifs fondamentaux

Sujets connexes :