OpenStack Emulator

A lightweight OpenStack API emulator for testing purposes. This emulator provides simplified implementations of OpenStack services, allowing you to develop and test OpenStack clients without a full OpenStack deployment.

pip install -e .

# Or with uv
uv pip install -e .

# Development installation
pip install -e ".[dev]"

A published Helm chart deploys the emulator as a single-replica Deployment + ClusterIP Service that exposes all twelve ports. Consumers in the same cluster reach Keystone at http://<release>-openstack-emulator.<ns>.svc.cluster.local:5000/v3 with the admin/s4l4dus/Default credentials.

helm repo add openstack-emulator https://waldur.github.io/openstack-emulator/
helm install ose openstack-emulator/openstack-emulator \
  --namespace ose --create-namespace --version 0.4.1
helm test ose -n ose      # curls /health on the five main service ports

See docs/kubernetes.md for the full operator guide (presets, persistence, Ingress, Gateway API, troubleshooting). The chart source lives at charts/openstack-emulator/ — also installable from disk via helm install ose ./charts/openstack-emulator.

# Run all services
openstack-emulator

# Run a specific service
openstack-emulator --service=nova

# Run with persistence enabled
openstack-emulator --persist-db=emulator_data.json --auto-save

# Seed sample resources from a built-in preset
openstack-emulator --list-presets
openstack-emulator --preset development

# Shift every port (useful when 5000 is taken) — keystone then listens on 6000
openstack-emulator --port-offset 1000

export OS_AUTH_URL=http://localhost:5000/v3
export OS_PROJECT_NAME=admin
export OS_USERNAME=admin
export OS_PASSWORD=s4l4dus
export OS_USER_DOMAIN_NAME=Default
export OS_PROJECT_DOMAIN_NAME=Default
export OS_IDENTITY_API_VERSION=3

openstack server list
openstack network list
openstack volume list

Every service serves Swagger UI at /docs and a health probe at /health:

• Keystone: http://localhost:5000/docs
• Nova: http://localhost:8774/docs
• Cinder: http://localhost:8776/docs
• Glance: http://localhost:9292/docs
• Neutron: http://localhost:9696/docs
• Octavia: http://localhost:9876/docs
• Placement: http://localhost:8778/docs
• Swift: http://localhost:8080/docs
• OIDC: http://localhost:5556/docs
• CloudKitty: http://localhost:8889/docs
• Scenarios: http://localhost:8999/docs
• Status UI: http://localhost:10000/

• Usage Guide - Detailed usage instructions
• Kubernetes Deployment Guide - Helm chart install + cross-namespace use + Ingress/Gateway API
• API Examples - curl and SDK examples
• Federated identity (OIDC) - Keystone federation and the embedded OpenID Provider
• Scenario Injection - Failure testing guide
• Development Guide - Code style, adding a service, release pipeline
• API Compliance - Comparing the emulator against official OpenStack specs
• Architecture - System design documentation
  • Overview - Architecture overview
  • Data Models - Model definitions
  • Tenant Isolation - Multi-tenancy

openstack-emulator/
├── emulator/
│   ├── api/           # REST API routes
│   ├── core/          # Business logic and models
│   └── presets/       # Built-in preset YAMLs (development, production, …)
├── charts/
│   └── openstack-emulator/  # Helm chart published to GitHub Pages
├── scripts/
│   ├── release.py     # Tag-driven release helper (status / check / release X.Y.Z / build)
│   ├── changelog.sh   # Interactive CHANGELOG.md entry generator
│   └── check-api-compliance.sh  # OpenStack API compliance comparison
├── tests/             # Python test suite
├── docs/              # User-facing documentation
├── .gitlab-ci.yml     # CI: linters, tests, helm lint, chart publish, docker publish
├── CLAUDE.md          # Development guide for AI assistants
└── README.md

uv run pytest
uv run pytest --cov=emulator --cov-report=html

Releases are tag-driven. Pushing a X.Y.Z tag triggers GitLab CI to:

• Run the full Python test matrix (3.10–3.13), linters, type checks, and helm lint + helm unittest
• Package the chart and push charts/openstack-emulator-X.Y.Z.tgz + an updated index.yaml to the gh-pages branch of the GitHub mirror at github.com/waldur/openstack-emulator
• GitHub Pages serves the branch at https://waldur.github.io/openstack-emulator/, where helm repo add consumers pick up the new version
• Build and push the Docker image as both :X.Y.Z and :latest

The scripts/release.py helper bundles the version bump + checks + changelog + tag + push:

uv run scripts/release.py status                   # show current versions + recent tags
uv run scripts/release.py check                    # run the same gates CI runs (fast subset)
uv run scripts/release.py version-update 0.4.2     # bump pyproject.toml + Chart.yaml only
uv run scripts/release.py release 0.4.2            # bump → check → changelog → commit → tag → (confirm) push
uv run scripts/release.py build                    # build the sdist/wheel and package the chart locally

The release script keeps pyproject.toml's [project].version and both version: and appVersion: in charts/openstack-emulator/Chart.yaml in lockstep — appVersion is the image tag the chart deploys, and CI publishes a matching :X.Y.Z image on tag.

release also drafts a CHANGELOG.md entry via scripts/changelog.sh, which shells out to the claude CLI and prompts you to accept/edit/regenerate it. That step is interactive and local-only; pass --skip-changelog to bypass it.

This is a testing emulator with several limitations:

• No real virtualization: Servers are simulated, not actual VMs
• In-memory storage: Data is lost on restart (unless persistence is enabled)
• Limited API coverage: Only essential endpoints implemented
• Simulated resources: Networks, volumes don't route real traffic

See Architecture Overview for more details.

Contributions welcome! Please see the Development Guide for guidelines.

MIT License