--- title: STACKIT Python SDK Software Asset description: Umfassender Leitfaden zum STACKIT Python SDK mit Paketinstallation aus dem Quellcode, dem Service-Account-Key-Authentifizierungsflow und Custom Endpoints. scfAsset: maintainers: - user: "tobias.mueller" managed: false category: "software" external: true tags: ["Python", "SDK", "API", "Automation", "DevOps"] source_url: "https://framework.stackit.cloud/de/architecture/assetcontainer/stackit/python-sdk/" source_file: "docs/de/architecture/assetcontainer/stackit/python-sdk.mdx" --- ## Ü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`. ```bash 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. ```bash pip install services/ ``` - **Service-Umleitung**: Ersetze `` 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`. ```bash 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. 1. **Explizite Instanz-Optionen**: Direkt im Python-Quellcode übergebene Parameter haben die höchste Priorität. 2. **System-Umgebungsvariablen**: Umgebungsvariablen auf Betriebssystemebene werden zur Laufzeit ausgewertet. 3. **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`. ```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. ```json { "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. ```python 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. ```python 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. ```python 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. ```bash 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. ```bash 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. ```bash 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`.