How alilotfi23/lxd-management-api works
1. This repository is a FastAPI-based management API that sits between API clients and an LXD server. The API itself is stateless for LXD control-plane calls, but it keeps local user/auth data in a database and proxies nearly all infrastructure actions to LXD over its REST API.
2. The top-level request path is: external client → FastAPI app → API router/middleware → auth/RBAC checks and request-scoped deps → resource route handler → service layer → LXD REST API. Most endpoints are versioned under /api/v1; /health is intentionally unversioned for deployment probing.
3. app/main.py is the application composition root. It wires middleware, CORS, global exception handling, request IDs/logging behavior, and startup/shutdown lifecycle. It also creates the FastAPI app and mounts the versioned router aggregator from app/api/v1/api.py.
4. The API layer is split by resource under app/api/v1/routes/: auth, instances, snapshots, backups, storage, networks, projects, images, operations, and system. These route modules are thin controllers; they validate input/output with Pydantic schemas, enforce authorization, and delegate the actual work to services.
5. Authentication and authorization are handled separately from LXD auth. app/core/security.py implements local user auth with JWT access/refresh tokens and password hashing, while app/api/deps.py provides bearer-token extraction and role checks. The role model is hierarchical (viewer < operator < admin), so higher roles inherit lower-role permissions.
6. Local user identity is persisted in the database layer under app/db/. This appears to be the only durable application state besides Alembic migrations: SQLAlchemy async models, async session management, CRUD helpers, and first-run seeding. The README indicates SQLite is the default datastore, used for users and token-related subjects, not for LXD resources themselves.
7. The infrastructure-control boundary is app/services/lxd_client.py. It is the repo’s adapter over the raw LXD REST API using httpx, and it supports two transport modes: local Unix socket access or remote HTTPS with mutual TLS. This is the main external dependency boundary, and it is where requests to LXD are formed and responses/errors are normalized.
8. Long-running LXD work is modeled explicitly in app/services/lxd_operations.py and the operations routes. Since LXD often returns 202 Accepted plus an operation reference for create/copy/snapshot/migrate actions, the API returns operation metadata immediately and exposes poll, wait, cancel, and WebSocket event-stream endpoints for follow-up observation.
9. The schemas in app/schemas/ define the API contract for each resource family: auth, instances, networks, storage, projects, snapshots, images, and shared LXD structures. These Pydantic v2 models are the boundary between HTTP payloads and service calls, and they keep request validation/response shaping separate from infrastructure code.
10. Cross-cutting utilities live in app/core/ and app/utils/. config.py centralizes environment-driven settings, limiter.py rate-limits sensitive endpoints like auth, logging.py provides structured JSON logging, and pagination.py applies response pagination on top of LXD list results. These are support subsystems rather than business logic.
11. The API exposes a mix of synchronous CRUD endpoints and LXD-native operational endpoints. Examples include instance lifecycle actions, exec/console over WebSocket, image copy/import, storage attach/detach, network lease/state queries, and project-scoped listing via ?project=. The design keeps LXD semantics visible instead of hiding them behind a separate domain model.
12. Database schema changes are managed with Alembic in alembic/ and an initial migration for the users table. This indicates the local database is expected to evolve independently of LXD, but still remains small and focused on application authentication state.
13. Testing is isolated from real infrastructure. tests/ uses pytest with an in-memory SQLite database and a mocked LXD client, so the test boundary validates route/auth/service behavior without requiring a live LXD daemon. That separation is important for the architecture diagram: LXD is an external system, not a test fixture dependency.
14. Deployment is container-oriented. Dockerfile, docker-compose.yml, and the Makefile show the app is intended to run as a service container with environment-based configuration, optionally mounting the host LXD socket or TLS credentials depending on connection mode. The .env.example file is the primary runtime configuration contract.
Main entry points: api.py API v1 · lxd_client.py LXD client · main.py App entry · instances.py Instance routes
Components 29
App runtime
FastAPI application, API routing, auth, services, and schemas
- App entry · Creates the FastAPI app, wires middleware, exception handling, logging, lifecycle hooks, and mounts the versioned API.
app/main.py - API v1 · Versioned router assembly for the public API surface under /api/v1.
app/api/v1/api.py - API deps · Bearer token extraction and role-check dependencies used by routes.
app/api/deps.py - Auth routes · Login, refresh, and user/auth endpoints.
app/api/v1/routes/auth.py - Instance routes · Instance lifecycle and exec/console-style operations.
app/api/v1/routes/instances.py - Snapshot routes · Snapshot CRUD and snapshot-triggered operations.
app/api/v1/routes/snapshots.py - Backup routes · Backup lifecycle endpoints that proxy LXD backup actions.
app/api/v1/routes/backups.py - Network routes · Network listing and state/lease management endpoints.
app/api/v1/routes/networks.py - Storage routes · Storage pool and attachment/detachment endpoints.
app/api/v1/routes/storage.py - Project routes · Project-scoped listing and project management endpoints.
app/api/v1/routes/projects.py - Image routes · Image import, copy, and image metadata endpoints.
app/api/v1/routes/images.py - Operation routes · Poll, wait, cancel, and event-stream endpoints for asynchronous LXD operations.
app/api/v1/routes/operations.py - System routes · System and health endpoints, including unversioned deployment probing.
app/api/v1/routes/system.py - Security · Local user auth, password hashing, access/refresh JWT handling, and role model logic.
app/core/security.py - Config · Environment-driven application and connection settings.
app/core/config.py - Rate limit · Rate-limits sensitive endpoints such as authentication.
app/core/limiter.py - Ops model · Models and coordinates LXD long-running operations and their metadata lifecycle.
app/services/lxd_operations.py - Pagination · Applies pagination over LXD list responses.
app/utils/pagination.py - Logging · Structured JSON logging utilities and request log behavior.
app/utils/logging.py - API schemas · Shared request/response models for auth, instances, networks, storage, projects, snapshots, images, and LXD structures.
app/schemas/__init__.py
Persistence
Local database layer and migration management
- DB models · Persistent user and token-related subject models.
app/db/models.py - DB session · Async SQLAlchemy session management.
app/db/session.py - DB CRUD · Database access helpers for local user/auth state.
app/db/crud.py - Migrations · Database schema evolution, including the initial users table migration.
alembic/versions/0001_create_users_table.py
Platform
Deployment, runtime configuration, and external systems
- LXD client · HTTPX-based adapter over the LXD REST API with local socket or remote mTLS transport.
app/services/lxd_client.py - LXD server · External LXD daemon reached through the REST API.
- Local DB · Durable local application state for users and auth-related records.
- API clients · Consumers calling the management API.
Tests
Isolated tests with mocked infrastructure
- Tests · Isolated tests using in-memory SQLite and a mocked LXD client.
tests/conftest.py
Connections 44
- API clients → App entry: HTTP requests · External clients call the API entrypoint.
- App entry → API v1: mounts · The application wires the versioned router aggregator.
- App entry → Config: loads settings · Runtime configuration is injected at startup.
- App entry → Logging: configures logs · Startup sets request and structured logging behavior.
- App entry → Rate limit: installs · Cross-cutting rate limiting is attached to the app.
- API v1 → Auth routes: routes · Versioned API exposes auth endpoints.
- API v1 → Instance routes: routes · Versioned API exposes instance endpoints.
- API v1 → Snapshot routes: routes · Versioned API exposes snapshot endpoints.
- API v1 → Backup routes: routes · Versioned API exposes backup endpoints.
- API v1 → Network routes: routes · Versioned API exposes network endpoints.
- API v1 → Storage routes: routes · Versioned API exposes storage endpoints.
- API v1 → Project routes: routes · Versioned API exposes project endpoints.
- API v1 → Image routes: routes · Versioned API exposes image endpoints.
- API v1 → Operation routes: routes · Versioned API exposes operation follow-up endpoints.
- API v1 → System routes: routes · Versioned API exposes system and health endpoints.
- Auth routes → API deps: auth checks · Route handlers enforce bearer auth and role checks.
- Instance routes → API deps: auth checks · Instance actions are gated by dependency checks.
- Auth routes → Security: uses · Auth handlers rely on local JWT and password logic.
- Security → DB CRUD: reads users · Local auth reads and writes database-backed user state.
- DB CRUD → DB session: sessions · CRUD helpers run through async sessions.
- DB CRUD → DB models: maps models · Database helpers operate on SQLAlchemy models.
- DB session → Local DB: connects to · Async sessions persist state in the local database.
- DB models → Local DB: persists to · Application state is stored in the local database.
- DB models → Migrations: evolved by · Schema changes are managed independently by Alembic.
- Instance routes → API schemas: validates payloads · Routes use Pydantic contracts for request and response shaping.
- Snapshot routes → API schemas: validates payloads · Snapshot endpoints use shared schemas.
- Image routes → API schemas: validates payloads · Image endpoints use shared schemas.
- Instance routes → LXD client: proxies to · Resource actions are delegated to the LXD adapter.
- Snapshot routes → LXD client: proxies to · Snapshot operations are delegated to the LXD adapter.
- Backup routes → LXD client: proxies to · Backup operations are delegated to the LXD adapter.
- Network routes → LXD client: proxies to · Network queries and updates are delegated to the LXD adapter.
- Storage routes → LXD client: proxies to · Storage operations are delegated to the LXD adapter.
- Project routes → LXD client: proxies to · Project operations are delegated to the LXD adapter.
- Image routes → LXD client: proxies to · Image actions are delegated to the LXD adapter.
- Operation routes → Ops model: tracks · Operation endpoints manage asynchronous operation metadata.
- Ops model → LXD client: polls via · Operations are checked and controlled through the LXD adapter.
- LXD client → LXD server: REST API · The adapter talks to the external LXD daemon.
- Operation routes → LXD server: ws/events · Long-running work is exposed as poll/wait/cancel/event streams.
- System routes → LXD client: status · System endpoints query infrastructure state through the adapter.
- Instance routes → Pagination: lists · List endpoints paginate LXD results.
- Network routes → Pagination: lists · Network listing is paginated when applicable.
- App entry → Tests: validated by · The app structure is exercised by the test suite.
- Tests → Local DB: in-memory SQLite · Tests use an isolated local database.
- Tests → LXD client: mocked · Tests replace the real LXD client with a mock.