OSDU SPI Stack

Deploy OSDU to AKS Automatic using Azure-native services.

SPI Stack provisions Azure infrastructure, bootstraps AKS, and hands application lifecycle management to Flux GitOps. It gives developers and platform engineers a reproducible environment for evaluating OSDU on Azure.

Important

SPI Stack is designed for development, testing, and platform evaluation. It is not intended for production deployments.

Quick Start

1. Install

Install uv, then install the latest SPI Stack release.

macOS and Linux

uv tool install --default-index https://packagefeedproxy.microsoft.io/pypi/simple/ \
  "$(curl -fsSL https://api.github.com/repos/Azure/osdu-spi-stack/releases/latest \
  | grep -o 'https://github.com/Azure/osdu-spi-stack/releases/download/[^"]*-py3-none-any.whl')"

Windows PowerShell

$wheel = (irm https://api.github.com/repos/Azure/osdu-spi-stack/releases/latest).assets.where({ $_.name -like '*-py3-none-any.whl' }).browser_download_url
uv tool install --default-index https://packagefeedproxy.microsoft.io/pypi/simple/ $wheel

Verify the installation:

spi --version

Optionally, add shell completion for bash, zsh, or fish, then open a new shell:

spi --install-completion

On PowerShell, --install-completion is refused because Typer's installer runs Set-ExecutionPolicy Unrestricted; append the output of spi --show-completion to your $PROFILE instead.

See Installation for pinned versions, upgrades, and troubleshooting.

2. Check prerequisites

Deployment requires az, Bicep, kubectl, kubelogin, Flux, and two role assignments on the Azure subscription: Contributor, and Role Based Access Control Administrator limited by a condition to the roles the stack assigns. spi check verifies the tools and the signed-in identity's permissions, and prints the grant an administrator runs when one is missing. See Permissions.

spi check

3. Deploy

spi up --env dev1

Note

A full deployment typically takes 45-50 minutes, dominated by AKS Automatic provisioning.

Warning

spi up creates billable Azure resources. Cost varies by region, profile, partition count, and runtime. Remove the environment when it is no longer needed.

4. Inspect and remove

spi status          # Monitor deployment health
spi info            # View endpoints

# Delete the environment when finished (managed identities stay; add --purge to remove the group)
spi down --env dev1

Why SPI Stack

• Transparent: Shows each az and kubectl command before running it.
• Azure-native services: Uses Cosmos DB, Service Bus, Storage, Key Vault, and Entra ID.
• AKS Automatic: Includes managed Istio, Karpenter, and Deployment Safeguards.
• GitOps-driven: Flux owns in-cluster reconciliation after bootstrap.
• Secretless authentication: Workloads access Azure through federated Workload Identity.
• Multi-partition: Creates isolated Cosmos DB, Service Bus, and Storage resources for each OSDU partition.

Architecture

Bicep declares the Azure resources, the spi CLI orchestrates provisioning and cluster bootstrap, and Flux reconciles the Kubernetes workloads from this repository. OSDU services reach Azure PaaS through Workload Identity; no Azure access keys or SAS tokens are stored.

See Architecture for the control planes, deployment pipeline, namespace model, and service topology.

What It Deploys

SPI Stack creates AKS Automatic plus the Azure services required by OSDU: Cosmos DB, Service Bus, Storage Accounts, Key Vault, Azure Container Registry, and Managed Identity.

Flux deploys three application namespaces:

Namespace	Contents
foundation	ECK, CNPG, cert-manager, and trust-manager
platform	Elasticsearch, Redis, PostgreSQL, Airflow, and the TLS certificates
osdu	Core OSDU APIs, bootstrap jobs, schema load, and reference services

Profiles

Profile	Deploys	Use when
core (default)	Middleware and OSDU services	Evaluating the full stack
minimal	Operators and middleware only	Developing or validating the platform layer
bare	Azure infrastructure and activated GitOps	Iterating on infrastructure, identity, or custom workloads

See Stack profiles for the exact layer boundaries.

Deployment Options

The default command creates the opendes partition and uses an Azure-assigned hostname. Common variations include:

# Multiple OSDU partitions
spi up --env dev1 --partition opendes --partition tenant1

# Hostnames in an existing Azure DNS zone
spi up --env dev1 --ingress-mode dns --dns-zone example.com

# Middleware without OSDU services
spi up --env dev1 --profile minimal

See Ingress modes and Deployment lifecycle for the complete behavior.

Common Commands

Command	Purpose
spi check	Validate tools and Azure permissions
spi up	Provision Azure resources and activate GitOps
spi connect	Point kubectl at an existing environment's cluster
spi status	Show deployment health and reconciliation progress
spi info	Show cluster endpoints and optional credentials
spi reconcile	Suspend, resume, or refresh Flux reconciliation
spi build	Build a service image from a fork checkout into the environment's own registry, as <registry>/local/<service>
spi service	Pin services to merge-request or fork-built images, or with pin --source <checkout> build and pin a local one, and refresh one service's canonical image, or the fork-sourced ones with --forks, without touching the rest
spi onboard	Trust a fork repository to deploy against the environment, and with --canonical-source fork make its main the service's canonical image; --reconcile restores what the environment's declaration lists; plans by default, --write applies
spi token	Mint an app-only bearer as the deploy identity for acceptance suites; --member for the suites' NO_ACCESS_USER caller, --no-access for 401 tests, --me for your own az token
spi users	Let a person call the OSDU APIs with their own token: add --me sets your role (viewer, editor, admin, ops) and verifies it, add <id> sets a colleague's, list shows members and roles, remove drops one
spi load	Load the data the environment's registry names: reports the schema load and loads reference data from its pinned release, one Job per partition; --status shows each load's state, --force runs one again
spi test	Run a service's suite as its deployed commit shipped it, from the paired acceptance image or natively with --source <checkout>; --dry-run shows the command and variables a run would use and --env-file writes them for an IDE; --report writes a page of what ran, --review adds which contract rows each test proves
spi update	Check for and install a newer CLI release
spi maintenance	Set or clear the deploy-blocking maintenance flag
spi down	Delete the environment's Azure resources; --purge removes the group and its identities

Run spi --help or spi <command> --help for the complete command reference.

Documentation

• Installation: release installation, version pinning, and upgrades
• Architecture: system overview and deployed components
• Deployment lifecycle: provisioning and reconciliation phases
• Flux reconciliation: image locks, refreshes, and service pins
• Gateway and ingress: hostname, TLS, and routing modes
• Workload Identity: identity and Azure RBAC flow
• Design guides: subsystem ownership, diagnostics, and limitations
• Environment lifecycle: shared version, maintenance, and upgrades
• Fork deployment: pin, verify, and restore fork images
• Architecture decisions: governing decisions and trade-offs

Development and Support

To work on the CLI from a checkout:

git clone https://github.com/Azure/osdu-spi-stack.git
cd osdu-spi-stack
uv sync
uv run spi --help

Development workflow and contribution requirements are in CONTRIBUTING.md. For support boundaries and reporting guidance, see SUPPORT.md. Bugs and feature requests are tracked in GitHub Issues.

License

Licensed under the Apache License 2.0.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.