--- title: STACKIT Python SDK Software Asset description: Comprehensive guide to the STACKIT Python SDK, detailing packages installation from source, service account key authentication flow, and 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/architecture/assetcontainer/stackit/python-sdk/" source_file: "docs/architecture/assetcontainer/stackit/python-sdk.mdx" --- > **Beta Notice**: The STACKIT Python SDK is in beta status and undergoes active development. Technical interfaces might change in subsequent releases. ## Overview The STACKIT Python SDK repository contains the published Python Software Development Kits and corresponding official releases. The architectural components are cleanly separated into a modular ecosystem: - **Core Module**: Provides central service clients, authentication mechanisms, and shared fallback configurations. - **Service Modules**: Implements dedicated client wrappers for individual infrastructure resources like Redis, Object Storage, and compute services. - **Example Catalog**: Demonstrates various practical orchestration implementations and custom configuration scenarios. --- ## Getting started The STACKIT Python SDK is structured into several isolated packages, each implementing a dedicated REST client for a specific cloud service. ### Package installation To utilize a specific service without bloating the local environment, developers can install individual service targets with `pip`. ```bash pip install stackit-redis ``` - **Dependency Resolution:** The pip package manager automatically installs all required underlying dependencies during the run. - **Immediate Readiness:** The package functions out-of-the-box as soon as the installation process completes successfully. ## Installation from source To build and install individual components directly from the repository source code, run the targeted setup commands: ```bash pip install services/ ``` - **Service Redirection:** Developers must replace `` with the literal subfolder identifier, such as services/redis. - **Monorepo Compilation:** Developers can compile and install all available cloud services simultaneously by utilizing the central automation layer with the Makefile: ```bash make install ``` --- ## Authentication & Authorization To perform authenticated API requests against the sovereign STACKIT control plane, the application requires a valid Service Account. Service accounts are managed inside the STACKIT Portal and must be granted explicit permissions (such as the project.owner role) within the target project scope. The STACKIT Python SDK implements an automated resolution chain that searches for credentials in the following sequential hierarchy: 1. **Explicit Instance Options:** Direct parameters passed inside the python source code string. 2. **System Environment Variables:** OS-level environment variables evaluated at runtime. 3. **Local Credentials Configuration File:** A local JSON mapping file acting as a fallback identity store. --- ## Credentials file layout The local credentials store must follow a structured schema. The resolution engine parses the path defined by the STACKIT_CREDENTIALS_PATH environment variable, defaulting to `HOME/.stackit/credentials.json`. ```json { "STACKIT_SERVICE_ACCOUNT_TOKEN": "foo_token", "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json" } ``` --- ## Detailed Authentication Flows ### Flow A: Key flow (recommended) The Key Flow provides a robust, asymmetric cryptographic identity utilizing an RSA key-pair architecture attached directly to the Service Account. ### Setup procedure - **Key Generation:** Create a Service Account Key with the STACKIT Portal by navigating to the Service Accounts tab, selecting the identity, and generating a key asset. - **File Exfiltration:** Export the generated configuration data and store the block securely as a local JSON file. The STACKIT Python SDK expects the following JSON structure inside the key configuration file: ```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" } } ``` --- ## Code configuration alternatives Developers can introduce the service account key to the SDK initialization sequence with three mutually exclusive integration options: - **Option 1 (Code Parameters):** Inject the explicit string reference with the configuration parameters.. ```python from stackit.core.configuration import Configuration config = Configuration( service_account_key_path="/path/to/service_account_key.json" ) ``` - **Option 2 (Environment Mapping):** Set the global shell run flag: export STACKIT_SERVICE_ACCOUNT_KEY_PATH="/path/to/service_account_key.json". - **Option 3 (Credentials Binding):** Register the exact path pointer inside the credentials.json map block. Custom Key-Pair Notice: If the key asset relies on a custom, user-provided key-pair, the PEM-encoded private key must be supplied explicitly with `private_key_path` or the STACKIT_PRIVATE_KEY_PATH environment variable. --- ## Flow B: Token flow (legacy) The Token Flow relies on static, long-lived access tokens. This method exhibits a reduced security posture compared to the Key Flow and should be restricted to isolated testing scenarios. - **Option 1 (Code Parameters):** Pass the token string directly into the initialization configuration object. ```python config = Configuration( service_account_token="your_long_lived_token_string" ) ``` - **Option 2 (Environment Mapping):** Declare the run context with export `STACKIT_SERVICE_ACCOUNT_TOKEN="your_token"`. - **Option 3 (Credentials Binding):** Supply the matching parameter token key inside the local credentials.json setup file. --- ## Advanced architecture pattern: Custom endpoints In isolated network zones, staging environments, or custom sovereignty clusters, the STACKIT Python SDK can be instructed to redirect traffic away from the public Hyperscaler gateways toward internal api endpoints. The following script demonstrates programmatic 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 specialized configuration client = DefaultApi(config) # Fetch isolated platform resource elements print(client.list_project_nics( project_id=project_id, )) ``` --- ## Local sandbox development & contribution To extend the STACKIT Python SDK or test custom local modifications, developers can install packages in editable mode using a local virtual environment managed by Poetry. - **Editable Installation:** Link a local package into the active development runtime context so that updates apply instantly without requiring re-installation cycles. ```bash pip install -e services/redis ``` - **Development Tooling:** Pull specialized code quality tools, static linters, and type checkers into the workspace by targeting the dev dependencies with Poetry: ```bash poetry install -C services/redis --only dev --no-root ``` - **Global Workspace Synchronization:** To configure and symlink all available services and development constraints across the full source tree simultaneously, run the overarching make instruction: ```bash make install-dev ``` Poetry Multi-Environment Safeguard: To prevent Poetry from generating fragmented, isolated python virtual environments for every single micro-service package during multi-package run, ensure global environment inheritance is activated with poetry config virtualenvs.create false.