{"id":51229755,"url":"https://github.com/alilotfi23/lxd-management-api","last_synced_at":"2026-06-28T15:01:49.917Z","repository":{"id":367818766,"uuid":"1282436762","full_name":"alilotfi23/LXD-Management-API","owner":"alilotfi23","description":"A production-ready CRUD REST API for managing an LXD server","archived":false,"fork":false,"pushed_at":"2026-06-27T19:21:07.000Z","size":100,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T21:10:13.198Z","etag":null,"topics":["fastapi","linux","linuxcontainers","lxd","lxd-container","lxd-containers","rbac","slowapi","virtual-machine","vm"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alilotfi23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-27T19:12:01.000Z","updated_at":"2026-06-27T19:21:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alilotfi23/LXD-Management-API","commit_stats":null,"previous_names":["alilotfi23/lxd-management-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/alilotfi23/LXD-Management-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FLXD-Management-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FLXD-Management-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FLXD-Management-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FLXD-Management-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alilotfi23","download_url":"https://codeload.github.com/alilotfi23/LXD-Management-API/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FLXD-Management-API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34892547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","linux","linuxcontainers","lxd","lxd-container","lxd-containers","rbac","slowapi","virtual-machine","vm"],"created_at":"2026-06-28T15:01:43.769Z","updated_at":"2026-06-28T15:01:49.911Z","avatar_url":"https://github.com/alilotfi23.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LXD Management API\n\nA production-ready CRUD REST API for managing an [LXD](https://linuxcontainers.org/lxd/)\nserver — instances, storage, networks, projects, and images — built with\n**FastAPI + Pydantic v2** and talking **directly to the LXD REST API** over raw\n`httpx` (no `pylxd` or any LXD SDK).\n\nIt supports **both** ways LXD's own clients connect:\n\n| Mode   | Transport                         | Auth                          | Use when                                |\n|--------|-----------------------------------|-------------------------------|-----------------------------------------|\n| local  | Unix socket (`unix.socket`)       | implicit (socket access)      | API runs on the LXD host / same pod     |\n| remote | HTTPS with **mutual TLS**         | client cert + key (trust add) | API runs elsewhere; `lxc remote add`    |\n\n\u003e This API's own client auth (JWT) is **separate** from LXD's mTLS auth, which\n\u003e is used only for the API-to-LXD connection.\n\n---\n\n## Features\n\n- **Versioned API** — everything under `/api/v1`; `/health` stays unversioned.\n- **Instances** — CRUD, start/stop/restart/freeze/unfreeze, exec \u0026 console over\n  WebSocket, state (CPU/mem/IPs), logs, snapshots, backups (with tarball export).\n- **Storage** — pools + volumes CRUD, resize, attach/detach volumes to instances.\n- **Networks** — CRUD, state/leases, NIC attach/detach.\n- **Projects** — CRUD + per-request project scoping (`?project=`).\n- **Images** — list/get/delete, copy from remote image servers (`ubuntu:`, `images:`).\n- **Async operations** — list/get/wait/cancel + a WebSocket relay of LXD's event stream.\n- **JWT auth + RBAC** — `admin` \u003e `operator` \u003e `viewer` role hierarchy.\n- **Resilience** — structured JSON logging, request IDs, global error handler,\n  CORS, rate-limited auth endpoints, deep `/health` that checks LXD connectivity.\n\n---\n\n## Quick start (Docker)\n\n```bash\n# 1. Configure\ncp .env.example .env\n#   -\u003e set LXD_CONNECTION_MODE and edit connection details\n\n# 2. Build \u0026 run\nmake up          # docker compose up --build -d\n\n# 3. Check it\ncurl http://localhost:8000/health\n# -\u003e {\"status\":\"ok\",\"version\":\"1.0.0\"}\n\n# 4. Open the docs\nopen http://localhost:8000/docs\n```\n\nThe default admin account is seeded from `SEED_ADMIN_USERNAME` /\n`SEED_ADMIN_PASSWORD` on first startup (set both in `.env`, or leave blank and\ncreate users via `/auth/register` after seeding one manually).\n\n---\n\n## Connection modes (concrete config)\n\n### A) Local — Unix socket\n\nThe API container mounts the host's LXD socket. **Two socket paths exist**,\ndepending on how LXD was installed:\n\n| Install | Socket path                                   |\n|---------|-----------------------------------------------|\n| snap    | `/var/snap/lxd/common/lxd/unix.socket`        |\n| native  | `/var/lib/lxd/unix.socket`                    |\n\n`.env`:\n```ini\nLXD_CONNECTION_MODE=local\nLXD_SOCKET_PATH=/var/snap/lxd/common/lxd/unix.socket\n```\n\n`docker-compose.yml` mounts it read-only:\n```yaml\nvolumes:\n  - \"${LXD_SOCKET_PATH}:/var/snap/lxd/common/lxd/unix.socket:ro\"\n```\n\n### B) Remote — mutual TLS\n\nLXD's network API authenticates with **client certificates** (this is what\n`lxc remote add \u003cname\u003e \u003curl\u003e` does — it exchanges certs and trusts them).\nGenerate a client cert, add it to the LXD server's trust store, then point the\nAPI at the cert/key files.\n\nGenerate a client cert/key pair:\n```bash\nopenssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \\\n  -keyout client.key -out client.crt -subj \"/CN=lxd-api\"\n```\n\nTrust it on the LXD server (one of):\n```bash\n# From a trusted machine:\nlxc config trust add client.crt\n# Or via the LXD REST API on the server:\nlxc remote add lxd-api https://lxd-host:8443   # then confirm fingerprint\n```\n\n`.env`:\n```ini\nLXD_CONNECTION_MODE=remote\nLXD_REMOTE_URL=https://lxd-host:8443\nLXD_CLIENT_CERT_PATH=/run/secrets/lxd/client.crt\nLXD_CLIENT_KEY_PATH=/run/secrets/lxd/client.key\nLXD_TRUSTED_CA_PATH=/run/secrets/lxd/server-ca.crt   # \"\" to skip verification (dev)\n```\n\nMount the cert directory in compose (uncomment the `LXD_TLS_DIR` volume):\n```yaml\nvolumes:\n  - \"${LXD_TLS_DIR:-./tls}:/run/secrets/lxd:ro\"\n```\n\n---\n\n## Environment variables\n\nAll settings live in `.env` (see `.env.example`). Key ones:\n\n| Variable                          | Default                                           | Description                              |\n|-----------------------------------|---------------------------------------------------|------------------------------------------|\n| `APP_PORT`                        | `8000`                                            | HTTP port                                |\n| `CORS_ORIGINS`                    | `*`                                               | Comma-separated allowed origins          |\n| `LXD_CONNECTION_MODE`             | `local`                                           | `local` or `remote`                      |\n| `LXD_SOCKET_PATH`                 | `/var/snap/lxd/common/lxd/unix.socket`            | Local-mode socket                        |\n| `LXD_REMOTE_URL`                  | `https://lxd-host:8443`                           | Remote-mode LXD URL                      |\n| `LXD_CLIENT_CERT_PATH`            |                                                   | Client cert (remote mTLS)                |\n| `LXD_CLIENT_KEY_PATH`             |                                                   | Client key (remote mTLS)                 |\n| `LXD_TRUSTED_CA_PATH`             |                                                   | Server CA (remote); `\"\"` = skip verify   |\n| `LXD_TIMEOUT`                     | `30`                                              | Per-request LXD timeout (s)              |\n| `DATABASE_URL`                    | `sqlite+aiosqlite:///./data/lxd_api.db`           | User store (JWT subjects)                |\n| `JWT_SECRET`                      | *(change me)*                                     | HS256 signing secret                     |\n| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | `30`                                              | Access token lifetime                    |\n| `JWT_REFRESH_TOKEN_EXPIRE_DAYS`   | `7`                                               | Refresh token lifetime                   |\n| `SEED_ADMIN_USERNAME`             |                                                   | First-run admin username                 |\n| `SEED_ADMIN_PASSWORD`             |                                                   | First-run admin password                 |\n\n---\n\n## Roles \u0026 permissions (RBAC)\n\nRoles are hierarchical — `require_role(\"operator\")` also admits `admin`.\n\n| Role      | Level | Can do                                                                 |\n|-----------|-------|------------------------------------------------------------------------|\n| `viewer`  | 1     | All `GET` endpoints (read-only)                                        |\n| `operator`| 2     | Instance lifecycle, exec/console, snapshots/backups, attach/detach     |\n| `admin`   | 3     | Everything: CRUD on pools/networks/projects/images, user management    |\n\nExamples: `POST /instances/{name}/start` → operator+; `DELETE /storage/pools/{name}` → admin only.\n\n---\n\n## Authentication (JWT)\n\n```bash\n# Login (rate-limited) -\u003e access + refresh tokens\nTOKEN=$(curl -s localhost:8000/api/v1/auth/login \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"username\":\"admin\",\"password\":\"changeme123\"}' | jq -r .access_token)\n\n# Use it\ncurl localhost:8000/api/v1/instances -H \"Authorization: Bearer $TOKEN\"\n\n# Refresh\ncurl localhost:8000/api/v1/auth/refresh \\\n  -H 'Content-Type: application/json' \\\n  -d \"{\\\"refresh_token\\\":\\\"$REFRESH\\\"}\"\n```\n\n**WebSocket auth:** browsers can't set headers on a WS upgrade, so pass the\nJWT as a query param: `ws://host/api/v1/instances/{name}/exec/ws?token=\u003cjwt\u003e`.\n\n---\n\n## Example curl requests\n\nSee `api.http` for a complete, runnable collection (works in VS Code REST\nClient / JetBrains). Highlights per resource:\n\n```bash\n# Instances\ncurl localhost:8000/api/v1/instances -H \"Authorization: Bearer $TOKEN\"\ncurl -X POST localhost:8000/api/v1/instances -H \"Authorization: Bearer $TOKEN\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\":\"web1\",\"source\":{\"type\":\"image\",\"alias\":\"ubuntu/22.04\"}}'\ncurl -X PUT localhost:8000/api/v1/instances/web1/state -H \"Authorization: Bearer $TOKEN\" \\\n  -H 'Content-Type: application/json' -d '{\"action\":\"start\"}'\n\n# Project-scoped request\ncurl \"localhost:8000/api/v1/instances?project=staging\" -H \"Authorization: Bearer $TOKEN\"\n\n# Storage\ncurl localhost:8000/api/v1/storage/pools -H \"Authorization: Bearer $TOKEN\"\n\n# Networks\ncurl localhost:8000/api/v1/networks -H \"Authorization: Bearer $TOKEN\"\n\n# Projects\ncurl -X POST localhost:8000/api/v1/projects -H \"Authorization: Bearer $TOKEN\" \\\n  -H 'Content-Type: application/json' -d '{\"name\":\"staging\"}'\n\n# Images (async — returns an operation ref)\ncurl -X POST localhost:8000/api/v1/images -H \"Authorization: Bearer $TOKEN\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"source\":{\"type\":\"image\",\"alias\":\"ubuntu/22.04\",\"server\":\"https://images.linuxcontainers.org\",\"protocol\":\"simplestreams\"}}'\n\n# Operations (poll the async op from above)\ncurl localhost:8000/api/v1/operations/\u003cid\u003e/wait -H \"Authorization: Bearer $TOKEN\"\n\n# System\ncurl localhost:8000/api/v1/system/info -H \"Authorization: Bearer $TOKEN\"\ncurl localhost:8000/api/v1/system/health\n```\n\n---\n\n## Why async operations need polling\n\nMany LXD actions (create instance, copy image, snapshot, migrate) are\n**long-running**. LXD returns `202 Accepted` + an operation URL immediately and\nruns the work in the background. Blocking the HTTP request until completion\nwould tie up a worker and risk client timeouts.\n\nSo this API **returns an operation reference** right away:\n\n```json\n{\n  \"operation_id\": \"abc-123\",\n  \"operation_url\": \"/1.0/operations/abc-123\",\n  \"poll_url\": \"/api/v1/operations/abc-123\",\n  \"wait_url\": \"/api/v1/operations/abc-123/wait\"\n}\n```\n\nThe client then does one of:\n- **Poll** — `GET /api/v1/operations/{id}`\n- **Long-poll** — `GET /api/v1/operations/{id}/wait?timeout=30`\n- **Subscribe** — open `WS /api/v1/operations/ws` for real-time events\n\n---\n\n## Filtering, recursion \u0026 pagination\n\n- `?expand=true` (default) → LXD `recursion=1` (full objects, not URLs).\n- `?filter=status eq Running` → passed through to LXD's OData filter.\n- `?limit=20\u0026offset=40` → our own pagination applied on top of the LXD result.\n- `?instance-type=container` (or `virtual-machine`) on instance list.\n- `?project=staging` → scopes the request to a LXD project.\n\n---\n\n## Development\n\n```bash\nmake install      # pip install -r requirements.txt + requirements-dev.txt\nmake migrate      # alembic upgrade head\nmake test         # pytest with coverage\nmake lint         # ruff check + black --check\nmake format       # black + ruff --fix\nmake typecheck    # mypy (non-blocking)\n```\n\nTests use an in-memory SQLite DB and a mocked LXD client — **no real LXD\ndaemon is required**:\n\n```bash\nmake test\n```\n\n---\n\n## Project structure\n\n```\napp/\n  main.py                      # FastAPI app, middleware, lifespan, error handler\n  api/\n    deps.py                    # JWT bearer, RBAC require_role, project param\n    v1/\n      api.py                   # v1_router aggregator\n      routes/                  # auth, instances, snapshots, backups, storage,\n                               # networks, projects, images, operations, system\n  core/\n    config.py                  # pydantic-settings\n    security.py                # bcrypt + JWT + Role hierarchy\n    limiter.py                 # slowapi instance\n  schemas/                     # pydantic v2 request/response models\n  services/\n    lxd_client.py              # raw httpx wrapper of the LXD REST API\n    lxd_operations.py          # async-op ref builder + wait helper\n    exceptions.py              # LXDError hierarchy -\u003e HTTP status\n  db/                          # SQLAlchemy async models, session, crud, seed\n  utils/                       # JSON logging, pagination\nalembic/                       # migrations\ntests/                         # pytest (mocked LXD)\nDockerfile, docker-compose.yml, Makefile, api.http\n```\n\n---\n\n## API reference\n\nInteractive docs are available at `/docs` (Swagger) and `/redoc` once running.\nSee `api.http` for a full request collection and `lxd-api.postman_collection.json`\nfor a Postman import.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falilotfi23%2Flxd-management-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falilotfi23%2Flxd-management-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falilotfi23%2Flxd-management-api/lists"}