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 ionosctlinstallé (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_requestrenvoyé sans erreur - [ ] Le serveur
ionosctla atteintAVAILABLEavec--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é :
-
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
202ne signifie que « accepté ». Le centre de données estBUSYtant que sa requête n'est pasDONE. - Correction : Lire l'en-tête
Locationet appelerwait_for_request()(Section 3.1) avant toute opération dépendante, ou utiliser--waitdansionosctl.
-
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 consignermetadata.message.
-
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
ttlexplicite, 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éfinissezttl, et stockez la valeur en une seule fois - Une création renvoie
202ainsi qu'un en-têteLocation; surveillez/requests/{id}/statusjusqu'à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 avecoffset,limitet_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 avecttllors de la génération - État de la requête : La ressource derrière l'en-tête
Location; signaleQUEUED,RUNNING,DONEouFAILED - 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 :