STACKIT Python SDK Software Asset

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.

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:

pip install services/<service-name>

• Service Redirection: Developers must replace <service-name> 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:

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.

{
  "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:

{
  "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..

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.

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:

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.

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:

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:

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.