STACKIT Python SDK Software Asset

Zuletzt aktualisiert am 6. Okt. 2026

Überblick

Das Repository des STACKIT Python SDK enthält die veröffentlichten Python Software Development Kits und ihre offiziellen Releases. Das STACKIT Python SDK ist in ein modulares Ökosystem mit klar getrennten Komponenten aufgeteilt.

Core-Modul: Das Core-Modul stellt zentrale Service-Clients, Authentifizierungsmechanismen und gemeinsame Fallback-Konfigurationen bereit.
Service-Module: Jedes Service-Modul implementiert einen dedizierten Client-Wrapper für eine einzelne Infrastruktur-Ressource wie Redis, Object Storage oder Compute-Dienste.
Beispiel-Katalog: Der Beispiel-Katalog zeigt praxisnahe Orchestrierungs-Implementierungen und individuelle Konfigurationsszenarien.

Erste Schritte

Das STACKIT Python SDK ist in mehrere isolierte Pakete gegliedert, wobei jedes Paket einen dedizierten REST-Client für einen bestimmten STACKIT-Cloud-Dienst implementiert.

Paketinstallation

Um einen bestimmten Dienst zu nutzen, ohne die lokale Umgebung aufzublähen, installiere das einzelne Service-Target über pip.

pip install stackit-redis

Dependency-Auflösung: Der pip-Paketmanager installiert während der Ausführung automatisch alle erforderlichen zugrunde liegenden Abhängigkeiten.
Sofortige Einsatzbereitschaft: Das Paket funktioniert sofort, sobald die Installation erfolgreich abgeschlossen ist.

Installation aus dem Quellcode

Um einzelne Komponenten direkt aus dem Repository-Quellcode zu bauen und zu installieren, führe die gezielten Setup-Befehle aus.

pip install services/<service-name>

Service-Umleitung: Ersetze <service-name> durch den konkreten Unterordner-Bezeichner, etwa services/redis.
Monorepo-Kompilierung: Kompiliere und installiere alle verfügbaren Cloud-Dienste gleichzeitig über die zentrale Automatisierungsschicht mit dem Makefile-Ziel make install.

make install

Authentifizierung und Autorisierung

Um authentifizierte API-Anfragen gegen die souveräne STACKIT-Control-Plane auszuführen, benötigt das STACKIT Python SDK einen gültigen Service-Account. Service-Accounts werden im STACKIT Portal verwaltet und müssen im Ziel-Projekt-Scope explizite Berechtigungen (etwa die Rolle project.owner) erhalten.

Das STACKIT Python SDK implementiert eine automatisierte Auflösungskette, die Anmeldedaten in der folgenden sequenziellen Hierarchie sucht.

Explizite Instanz-Optionen: Direkt im Python-Quellcode übergebene Parameter haben die höchste Priorität.
System-Umgebungsvariablen: Umgebungsvariablen auf Betriebssystemebene werden zur Laufzeit ausgewertet.
Lokale Credentials-Konfigurationsdatei: Eine lokale JSON-Mapping-Datei dient als Fallback-Identitätsspeicher.

Aufbau der Credentials-Datei

Der lokale Credentials-Speicher muss einem strukturierten Schema folgen. Die Auflösungs-Engine des STACKIT Python SDK parst den Pfad aus der Umgebungsvariable STACKIT_CREDENTIALS_PATH und nutzt standardmäßig $HOME/.stackit/credentials.json.

{
  "STACKIT_SERVICE_ACCOUNT_TOKEN": "foo_token",
  "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json"
}

Detaillierte Authentifizierungsflows

Flow A: Key Flow (empfohlen)

Der Key Flow bietet eine robuste, asymmetrische kryptografische Identität über eine RSA-Schlüsselpaar-Architektur, die direkt an den Service-Account gebunden ist.

Setup-Vorgehen:

Schlüsselerzeugung: Erstelle im STACKIT Portal einen neuen Service-Account-Key, indem du den Tab Service-Accounts öffnest, die Identität auswählst und ein Key-Asset generierst.
Datei-Export: Exportiere die generierte Konfigurations-Payload und speichere den Block sicher als lokale JSON-Datei.

Das STACKIT Python SDK erwartet die folgende JSON-Struktur in der Key-Konfigurationsdatei.

{
  "id": "uuid",
  "publicKey": "public key data",
  "createdAt": "2023-08-24T14:15:22Z",
  "validUntil": "2023-08-24T14:15:22Z",
  "keyType": "USER_MANAGED",
  "keyOrigin": "USER_PROVIDED",
  "keyAlgorithm": "RSA_2048",
  "active": true,
  "credentials": {
    "kid": "string-key-id",
    "iss": "my-sa@sa.stackit.cloud",
    "sub": "uuid-subject",
    "aud": "target-audience-string",
    "privateKey": "private-key-payload-when-managed-by-stackit"
  }
}

Alternativen zur Code-Konfiguration

Übergib den Service-Account-Key an die Initialisierungssequenz des STACKIT Python SDK über drei sich gegenseitig ausschließende Integrationsoptionen.

Option 1 (Code-Parameter): Injiziere die explizite String-Referenz über die Konfigurationsparameter.

from stackit.core.configuration import Configuration

config = Configuration(
    service_account_key_path="/path/to/service_account_key.json"
)

Option 2 (Environment-Mapping): Setze das Shell-Environment-Flag export STACKIT_SERVICE_ACCOUNT_KEY_PATH="/path/to/service_account_key.json".
Option 3 (Credentials-Binding): Registriere den exakten Pfad-Pointer im credentials.json-Map-Block.

Wenn das Key-Asset auf einem benutzerdefinierten, selbst bereitgestellten Schlüsselpaar basiert, gib den PEM-codierten Private Key explizit über private_key_path oder die Umgebungsvariable STACKIT_PRIVATE_KEY_PATH an.

Flow B: Token Flow (Legacy)

Der Token Flow basiert auf statischen, langlebigen Access-Tokens. Der Token Flow bietet eine schwächere Sicherheitslage als der Key Flow und sollte auf isolierte Testszenarien beschränkt bleiben.

Option 1 (Code-Parameter): Übergib den Token-String direkt an das Initialisierungs-Konfigurationsobjekt.

config = Configuration(
    service_account_token="your_long_lived_token_string"
)

Option 2 (Environment-Mapping): Deklariere den Ausführungskontext über export STACKIT_SERVICE_ACCOUNT_TOKEN="your_token".
Option 3 (Credentials-Binding): Hinterlege den passenden Token-Key in der lokalen credentials.json-Setup-Datei.

Erweitertes Architekturmuster: Custom Endpoints

In isolierten Netzwerkzonen, Staging-Umgebungen oder eigenen Souveränitäts-Clustern kann das STACKIT Python SDK den Traffic von den öffentlichen Gateways auf interne API-Endpunkte umleiten.

Das folgende Skript demonstriert die programmatische Endpoint-Substitution.

from stackit.iaas.api.default_api import DefaultApi
from stackit.core.configuration import Configuration

# Define target workspace scope
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Configure custom authentication gateways and regional endpoint routing
config = Configuration(
    service_account_key_path="/home/bob/.stackit/sa_key.json",
    custom_token_endpoint="https://service-account.api.stackit.cloud/token",
    custom_endpoint="https://iaas.api.eu01.stackit.cloud",
)

# Instantiate the API client with the specialized configuration
client = DefaultApi(config)

# Fetch isolated platform resource elements
print(client.list_project_nics(
    project_id=project_id,
))

Lokale Sandbox-Entwicklung und Beiträge

Um das STACKIT Python SDK zu erweitern oder lokale Anpassungen zu testen, installiere Pakete im Editable-Modus mit einer lokalen, von Poetry verwalteten virtuellen Umgebung.

Editable-Installation: Verlinke ein lokales Paket in die aktive Entwicklungsumgebung, sodass Änderungen sofort ohne Neuinstallation wirken.

pip install -e services/redis

Entwicklungs-Tooling: Hole spezialisierte Code-Quality-Tools, statische Linter und Type-Checker in den Workspace, indem du die Dev-Abhängigkeiten über Poetry ansprichst.

poetry install -C services/redis --only dev --no-root

Globale Workspace-Synchronisierung: Um alle verfügbaren Dienste und Entwicklungs-Constraints über den gesamten Quellbaum zu konfigurieren und zu verlinken, führe die übergreifende make-Anweisung aus.

make install-dev

Um zu verhindern, dass Poetry bei der Ausführung über mehrere Pakete für jedes Micro-Service-Paket fragmentierte, isolierte virtuelle Python-Umgebungen erzeugt, aktiviere die globale Environment-Vererbung über poetry config virtualenvs.create false.

Ihr Feedback

Fast fertig!