Einheit 1.1: IONOS CLOUD API, Authentifizierung und asynchrones Modell
Einführung
Im gesamten Kurs bauen Sie TaskBoard, eine Task-Management-API mit Web-Frontend, die vollständig über Code aus einem Git-Repository provisioniert und deployed wird.
Bevor Sie Terraform schreiben, müssen Sie die Ebene verstehen, mit der jedes Tool kommuniziert: die IONOS CLOUD API. Terraform, ionosctl und die SDKs senden dieselben HTTP-Anfragen, die Sie auch mit curl senden können. Wenn eine Pipeline fehlschlägt, liegt die Ursache oft in einem Authentifizierungsproblem, in einer Anfrage, die vor dem Abschluss ihrer Vorgängeranfrage ausgeführt wurde, oder in einem Client, der ein Rate Limit ignoriert hat.
In dieser Einheit erstellen Sie Access Tokens, rufen die API v6 direkt auf, behandeln ihr asynchrones Anfrage-Modell und fügen einem kleinen Python-Client Backoff und Pagination hinzu. Im Code Lab provisionieren Sie das erste Rechenzentrum und die Server von TaskBoard auf drei Arten.
1. Die IONOS CLOUD API v6
Die IONOS CLOUD API v6 ist die zentrale Infrastruktur REST API. Sie umfasst Compute-, Container-, Netzwerk- und Sicherungsressourcen in einer einzigen OpenAPI-Spezifikation, Version 6.0.
curl --request GET 'https://api.ionos.com/cloudapi/v6/datacenters' \
--header 'Authorization: Bearer <access_token>'
1.1 Basis-URLs und Versionierung
Die Basis-URL für die API v6 lautet https://api.ionos.com/cloudapi/v6. Produkte wie Managed Kubernetes, Cross Connect, Flow Logs und Backup Service werden über Endpunkte unter /cloudapi/v6 verwaltet. Neuere Dienste, wie CDN, VPN Gateway und die Datenbankdienste, werden als eigenständige, separate API-Spezifikationen mit eigenen Basis-URLs und eigener Versionierung veröffentlicht.
Für DBaaS for PostgreSQL, DBaaS for MariaDB und DBaaS for In-Memory DB werden die v2-APIs verwendet. Diese laufen auf regionalen Hosts mit einem /v2-Pfad:
export PG_API="https://postgresql.de-txl.ionos.com/v2"
export MARIADB_API="https://mariadb.de-txl.ionos.com/v2"
Sie verwenden diese APIs in Modul 2. Die Regel für den Moment: Prüfen Sie die Basis-URL jeder API, bevor Sie sie aufrufen.
1.2 Struktur der Anfrage und Abfrageparameter
Senden Sie JSON mit Content-Type: application/json. Bei GET-Anfragen steuert depth (0 bis 10, Standardwert 0), wie viele Ebenen von Kindobjekten die Antwort aufklappt, und pretty (Standardwert true) formatiert sie lesbar.
curl --silent 'https://api.ionos.com/cloudapi/v6/datacenters?depth=1' \
--header "Authorization: Bearer ${IONOS_TOKEN}" | jq '.items[].properties.name'
2. Authentifizierung
Die API v6 akzeptiert zwei Methoden: ein Bearer-Token (Authorization: Bearer <access_token>) und Basic Auth (Authorization: Basic <base64(username:password)>). Verwenden Sie Bearer-Tokens für jede automatisierte Arbeitslast.
2.1 Erstellen eines Zugriffstokens
Beide Methoden rufen denselben Auth-API-Endpunkt auf, GET https://api.ionos.com/auth/v1/tokens/generate. Die Antwort enthält ein JSON Web Token (JWT) im Feld 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'
Der Abfrageparameter ttl legt die Token-Lebensdauer in Sekunden fest: Minimum 60, Maximum 31536000, und standardmäßig läuft ein generiertes Token nach einem Jahr ab. Kurze Lebensdauern begrenzen den Schaden bei einem Leak.
Zwei Regeln beschränken Basic Auth. Konten mit aktivierter oder erzwungener Zwei-Faktor-Authentifizierung müssen die Bearer-Token-Authentifizierung verwenden. Die Methode Basic Authentication wird in naher Zukunft ebenfalls eingestellt, daher sollten keine neuen Automatisierungen darauf aufbauen.
2.2 Token Manager und Token-Lebenszyklus
Im Data Center Designer (DCD) befindet sich der Token Manager unter Menü > Verwaltung > Token Manager. Er generiert Tokens mit einem der folgenden Time to Live (TTL)-Werte: 1 Stunde, 4 Stunden, 1 Tag, 7 Tage, 30 Tage, 60 Tage, 90 Tage, 180 Tage oder 365 Tage.
Drei Fakten prägen die Token-Verwaltung:
- Der Token-Wert wird nur einmal, bei der Generierung, angezeigt. Zu diesem Zeitpunkt kann er als Textdatei heruntergeladen werden.
- Pro Benutzer sind bis zu 100 aktive Tokens möglich. Wird dieses Limit erreicht, gibt die API für neue Tokens einen Fehler zurück.
- Das Löschen eines Tokens im Token Manager deaktiviert es sofort, auch wenn es noch nicht abgelaufen ist.
Bewahren Sie den Wert in einem Secret Store auf und injizieren Sie ihn als Umgebungsvariable:
export IONOS_TOKEN="$(vault kv get -field=token secret/taskboard/ionos)"
2.3 Least-Privilege Scoping
Um die Handlungsfähigkeit eines Tokens einzuschränken, wird es unter einem dedizierten Sub-User erzeugt, dessen Gruppen nur die Berechtigungen gewähren, die der Dienst benötigt. Berechtigungen sind Genehmigungen für bestimmte Aktionen, wie createDatacenter, createSnapshot oder reserveIp. Ressourcen-Autorisierungen sind Read, Edit und Sharing.
Für TaskBoard wird taskboard-ci für Infrastrukturänderungen und ein nur-lesender User für Monitoring-Skripte erstellt. Ein geleaktes Monitoring-Token kann dann keine Ressourcen erstellen.
3. Das asynchrone Bereitstellungsmodell
Für die API v6 werden Ressourcen asynchron erstellt. Eine POST, die eine Ressource erstellt, gibt 202 Accepted zurück, während die Bereitstellung noch läuft, und der Location-Response-Header enthält eine Callback-URL, um den Status der Operation abzufragen.
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 Status von Abfrageanfragen
GET /requests/{requestId}/status gibt metadata.status zurück, wobei es sich um eines der folgenden Werte handelt: QUEUED, RUNNING, DONE oder FAILED. Abfragen sind nicht optional: Eine BUSY-Ressource hat mindestens eine ausstehende Änderungsanfrage, und alle nachfolgenden Anfragen werden dahinter in einer Warteschlange abgearbeitet.
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 Zwei Arten von Fehlern
Die Fail-Fast-Validierung wird zuerst ausgeführt: Autorisierung, Vertragsressourcen und ob die Konfiguration zum Produkt und zum Standort passt. Diese Fehler werden synchron zurückgegeben, und die API gibt nur den ersten gefundenen Validierungsfehler zurück, sodass ein erneuter Versuch den nächsten Fehler aufdecken kann.
Provisionierungsfehler treten später auf und erscheinen im Status der Anfrage, mit einem Fehlercode im Format VDC-x-xxx. Prüfen Sie sowohl die POST-Antwort als auch den endgültigen Status der Anfrage.
4. Aufbau eines resilienten Clients
4.1 Rate Limiting und Backoff
Wenn Sie das Anfrage-Ratenlimit überschreiten, gibt die API 429 zurück. Drei Antwort-Header ermöglichen es Ihnen, die Anfragegeschwindigkeit zu drosseln, bevor dies geschieht:
| Header | Bedeutung |
|---|---|
X-RateLimit-Remaining |
Anzahl der Anfragen, die noch gestellt werden können, ohne eine Fehlerantwort auszulösen |
X-RateLimit-Limit |
Die durchschnittliche Anzahl der erlaubten Anfragen pro Minute |
X-RateLimit-Burst |
Die maximale Anzahl der erlaubten parallelen API-Anfragen |
Verpacken Sie jeden Aufruf in einen Wiederholungsversuch mit exponentiellem Backoff und Jitter:
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 Paginierung
Sammlungen akzeptieren offset (Standard: 0) und limit (Minimum: 1, Maximum: 10000). Die Antwort enthält _links.next nur, wenn offset + limit kleiner ist als die Gesamtzahl der Elemente.
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 Statuscodes und Fehlerkörper
Fehlerantworten enthalten httpStatus und ein messages-Array mit errorCode und message:
{ "httpStatus": 422, "messages": [ { "errorCode": "200", "message": "[VDC-yy-xxxx] ..." } ] }
| Code | Client-Aktion |
|---|---|
401 |
Erstellen Sie ein neues Token und prüfen Sie dessen Ablaufdatum |
403 |
Prüfen Sie die Gruppenberechtigungen des Benutzers |
404 |
Prüfen Sie die UUID und, dass die Erstellungsanfrage DONE ist |
409 |
Warten Sie, bis die Ressource den Status BUSY verlässt, und versuchen Sie es erneut |
422 |
Korrigieren Sie den Anfrageinhalt |
429, 500, 503 |
Versuchen Sie es mit Backoff erneut; wenden Sie sich an den Support, wenn ein 500 weiterhin besteht |
5. SDKs und ionosctl
5.1 Die SDKs
Die SDKs, die die API v6 kapseln, sind für Go, Java, Ruby, Python und NodeJS verfügbar und werden unter github.com/ionos-cloud/sdk-go, sdk-java, sdk-ruby, sdk-python und sdk-nodejs veröffentlicht. Ihre Dokumentation befindet sich unter https://docs.ionos.com/cloud/sdk-tools-home. Die SDKs kapseln dieselbe API, daher gilt die asynchrone Regel aus Abschnitt 3 unverändert. Diese Einheit verwendet reines HTTP in Python, damit jeder Header sichtbar bleibt.
5.2 ionosctl
Installieren Sie ionosctl mit einem Paketmanager:
brew tap ionos-cloud/homebrew-ionos-cloud && brew install ionosctl # Homebrew
snap install ionosctl # snap
scoop install ionos-cloud/ionosctl # Scoop
ionosctl prüft zuerst die Umgebungsvariablen (IONOS_TOKEN, oder IONOS_USERNAME und IONOS_PASSWORD), dann die Konfigurationsdatei. Um eine Konfigurationsdatei zu erstellen, führen Sie ionosctl config login --token "$IONOS_TOKEN" aus.
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
Befehle zum Erstellen akzeptieren --wait (-w), um zu blockieren, bis die Ressource AVAILABLE ist. --timeout begrenzt die Wartezeit, standardmäßig auf 600 Sekunden.
API-Referenz Schnellkarte
Wichtige API-Endpunkte für das Thema dieser Einheit:
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
https://api.ionos.com/auth/v1/tokens/generate |
Erzeugt ein neues Zugriffstoken (ttl in Sekunden) |
GET |
/datacenters |
Listet Rechenzentren auf (offset, limit, depth) |
POST |
/datacenters |
Erstellt ein Rechenzentrum (gibt 202 und Location zurück) |
POST |
/datacenters/{datacenterId}/servers |
Erstellt einen Server |
GET |
/requests/{requestId}/status |
Abfrage eines asynchronen Antrags: QUEUED, RUNNING, DONE, FAILED |
Basis-URL: https://api.ionos.com/cloudapi/v6
Authentifizierung: Authorization: Bearer <token>
Code Lab
Ziel: Das Entwicklung-Rechenzentrum von TaskBoard mit curl bereitstellen, einen Server mit Python und einen mit ionosctl hinzufügen und die asynchrone Fertigstellung für jeden einzelnen Schritt überprüfen.
Voraussetzungen:
- IONOS CLOUD-Konto mit einem API-Token in
IONOS_TOKEN - curl, jq und Python 3 mit dem Paket
requests ionosctlinstalliert (Abschnitt 5.2)
Schritt 1: Das Rechenzentrum mit curl erstellen und die Anfrage-URL erfassen
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"
Erwartete Ausgabe:
<datacenter-uuid> https://api.ionos.com/cloudapi/v6/requests/<requestId>/status
Schritt 2: Abfragen, bis DONE erreicht ist
until [ "$(curl -s "$STATUS_URL" -H "Authorization: Bearer ${IONOS_TOKEN}" | jq -r '.metadata.status')" = "DONE" ]; do
sleep 5
done; echo "datacenter ready"
Erwartete Ausgabe:
datacenter ready
Schritt 3: Erstellen Sie einen Server mit Python
Speichern Sie als create_server.py und verwenden Sie wait_for_request und call aus den Abschnitten 3.1 und 4.1 erneut:
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"])
Erwartete Ausgabe:
server ready: <server-uuid>
Schritt 4: Erstellen eines Servers mit ionosctl
ionosctl compute server create --datacenter-id "$DC_ID" --name taskboard-api-cli \
--type VCPU --cores 1 --ram 2GB --wait
Erwartete Ausgabe:
ServerId Name Type ... State
<server-uuid> taskboard-api-cli VCPU ... AVAILABLE
Schritt 5: Vergleichen Sie die Ergebnisse
ionosctl compute server list --datacenter-id "$DC_ID" --cols ServerId,Name,Type,Cores,State
Erwartete Ausgabe:
ServerId Name Type Cores State
<uuid> taskboard-api-py VCPU 1 AVAILABLE
<uuid> taskboard-api-cli VCPU 1 AVAILABLE
Prüfliste:
- [ ] Rechenzentrum über curl erstellt und seine Anfrage erreichte
DONE - [ ] Python-Server erstellt und
wait_for_requestwurde ohne Fehler zurückgegeben - [ ]
ionosctl-Server erreichteAVAILABLEmit--wait - [ ] Beide Server zeigen in Schritt 5 denselben Typ und dieselbe Kernanzahl
Bereinigung:
# Deletes the data center and every resource it contains
ionosctl compute datacenter delete --datacenter-id "$DC_ID" --force --wait
Häufige Fehler
Fehler von Entwicklerinnen und Entwicklern, die bei diesem Thema der Einheit zu vermeiden sind:
-
Das Abfragen der Anfrage wird übersprungen
- Problem: Ihr Skript erstellt ein Rechenzentrum und erstellt sofort einen Server darin, liest den Server dann aber, bevor er existiert. Die nachfolgende Logik schlägt fehl oder läuft in eine Zeitüberschreitung.
- Grund: Die
202-Antwort bedeutet nur „angenommen“. Das Rechenzentrum istBUSY, bis seine AnfrageDONEist. - Lösung: Lesen Sie den
Location-Header und rufen Siewait_for_request()(Abschnitt 3.1) vor jeder abhängigen Operation auf, oder verwenden Sie--waitinionosctl.
-
202 als Erfolg behandeln
- Problem: Die Pipeline meldet grün, aber die Ressource erscheint nie.
- Grund: Bereitstellungsfehler erscheinen nur im Status der Anfrage (Abschnitt 3.2).
- Lösung: Lassen Sie den Job fehlschlagen, wenn der Status der Anfrage
FAILEDist, und protokollieren Siemetadata.message.
-
Ein langlebiges persönliches Token hartkodieren
- Problem: Ein Token in einer CI-Variablen wird geleakt oder funktioniert nicht mehr, wenn es abläuft, und niemand weiß, wem es gehört.
- Grund: Token werden standardmäßig mit einer Lebensdauer von einem Jahr erstellt, und ein Token, das unter einem persönlichen Administratorkonto erstellt wird, ist nicht auf einen einzelnen Dienst beschränkt.
- Lösung: Erstellen Sie das Token unter einem dedizierten Benutzerkonto mit minimalen Berechtigungen, setzen Sie eine explizite
ttlund speichern Sie es in einem Secret Store.
Zusammenfassung
Sie können sich nun mit IONOS CLOUD so wie jedes andere Tool auch verbinden: Erzeugen Sie ein Bearer-Token, rufen Sie die API v6 auf und warten Sie darauf, dass asynchrone Anfragen abgeschlossen sind, bevor Sie darauf aufbauen. Ihr Python-Client wiederholt Anfragen mit Backoff, durchläuft paginierte Sammlungen und liest strukturierte Fehlerantworten. In Einheit 1.2 übernimmt Terraform dieses Polling für Sie, und das Wissen darüber ermöglicht es Ihnen, es dort zu debuggen.
Wichtige Punkte:
- Die Basis-URL der API v6 ist
https://api.ionos.com/cloudapi/v6; DBaaS-APIs haben eigene regionale Hosts - Erzeugen Sie Zugriffstokens mit
GET /auth/v1/tokens/generate, setzen Siettlund speichern Sie den Wert sofort - Eine Erstellungsanfrage gibt
202plus einenLocation-Header zurück; pollen Sie/requests/{id}/status, bisDONE - Fail-Fast-Validierungsfehler sind synchron; Bereitstellungsfehler erscheinen nur im Status der Anfrage
- Verwenden Sie Backoff für
429und paginieren Sie mitoffset,limitund_links.next
Wichtige Begriffe:
- Access token: Ein JWT, das als
Authorization: Bearer <token>gesendet wird; seine Lebensdauer wird bei der Generierung mitttlfestgelegt - Request status: Die Ressource hinter dem
Location-Header; meldetQUEUED,RUNNING,DONEoderFAILED - BUSY: Ressourcenstatus, der bedeutet, dass mindestens eine Änderungsanfrage ausstehend ist; weitere Anfragen werden in die Warteschlange aufgenommen
- Fail-fast validation: Synchron durchgeführte Prüfungen vor der Aufnahme in die Warteschlange; die API gibt nur den ersten gefundenen Fehler zurück
- depth: Abfrageparameter (0 bis 10), der steuert, wie viele Ebenen von Kindobjekten eine Antwort aufklappt
Nächste Schritte
Weiter lernen: Einheit 1.2: Terraform Provider und Kernmuster
Verwandte Themen: