# canonical/lxd architecture

> Architecture diagram of the GitHub repository canonical/lxd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/canonical/lxd
- Repository: https://github.com/canonical/lxd

## Overview

LXD manages Linux containers and virtual machines through a REST API, with the `lxc` CLI and Go client SDK as user-facing access paths. A representative workflow is a user issuing a storage-volume command, the client sending an API request, and the daemon coordinating storage operations and cluster metadata. The tree and excerpts also show distinct image, network, identity, and instance subsystems. Several links are dashed where the available excerpts and index do not establish the runtime call path; unsampled source was not inspected.

Main entry points: [`lxd/api_1.0.go`](https://github.com/canonical/lxd/blob/main/lxd/api_1.0.go) (REST API), [`lxd/storage/storage.go`](https://github.com/canonical/lxd/blob/main/lxd/storage/storage.go) (Storage backends), [`lxd/storage_volumes.go`](https://github.com/canonical/lxd/blob/main/lxd/storage_volumes.go) (Storage volumes), [`client/lxd_storage_volumes.go`](https://github.com/canonical/lxd/blob/main/client/lxd_storage_volumes.go) (Go client SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access"]
  node_cli["lxc CLI<br/>[storage_volume.go]"]
  node_sdk["Go client SDK"]
end

subgraph group_control["Control plane"]
  node_rest["REST API<br/>[api_1.0.go]"]
  node_cluster["Cluster coordination<br/>[gateway.go]"]
  node_auth["Identity and authorization<br/>[authorization.go]"]
  node_operations["Async operations<br/>[operations.go]"]
  node_events["Events and lifecycle<br/>[events.go]"]
end

subgraph group_workloads["Workloads"]
  node_instances["Instance management<br/>[instances_post.go]"]
  node_instance_drivers["Container and VM drivers<br/>[driver_common.go]"]
  node_images["Image management<br/>[images.go]"]
  node_network["Networking<br/>[networks.go]"]
  node_agent["Instance agent<br/>[server.go]"]
end

subgraph group_storage["Storage"]
  node_pool_api["Storage pools<br/>[storage_pools.go]"]
  node_volume_api["Storage volumes<br/>[storage_volumes.go]"]
  node_snapshots["Volume snapshots"]
  node_buckets["Storage buckets<br/>[storage_buckets.go]"]
  node_storage_engine["Storage backends<br/>[storage.go]"]
  node_storage_drivers["Storage drivers"]
  node_db_volumes[("Volume metadata<br/>[storage_volumes.go]")]
  node_db_pools[("Pool metadata<br/>[storage_pools.go]")]
  node_db_buckets[("Bucket metadata<br/>[storage_buckets.go]")]
end

node_user(("Operator"))

node_user -.->|"runs commands"| node_cli
node_user -->|"integrates with"| node_sdk
node_cli -->|"calls client"| node_sdk
node_sdk -.->|"sends requests"| node_rest
node_rest -.->|"authorizes requests"| node_auth
node_rest -.->|"forwards requests"| node_cluster
node_rest -->|"starts operations"| node_operations
node_rest -.->|"emits lifecycle"| node_events
node_rest -.->|"routes workload requests"| node_instances
node_instances -.->|"manages instances"| node_instance_drivers
node_rest -.->|"routes image requests"| node_images
node_rest -.->|"routes network requests"| node_network
node_rest -.->|"routes pool requests"| node_pool_api
node_rest -.->|"routes volume requests"| node_volume_api
node_volume_api -->|"reads and writes"| node_db_volumes
node_volume_api -->|"uses pool operations"| node_storage_engine
node_storage_engine -.->|"selects backend"| node_storage_drivers
node_volume_api -->|"runs volume tasks"| node_operations
node_rest -.->|"routes snapshot requests"| node_snapshots
node_snapshots -->|"creates and deletes"| node_storage_engine
node_rest -.->|"routes bucket requests"| node_buckets
node_buckets -->|"reads and writes"| node_db_buckets
node_buckets -.->|"uses pool operations"| node_storage_engine
node_pool_api -->|"reads and writes"| node_db_pools
node_pool_api -->|"manages backends"| node_storage_engine
node_agent -->|"uses storage client"| node_sdk

click node_cli "https://github.com/canonical/lxd/blob/main/lxc/storage_volume.go"
click node_sdk "https://github.com/canonical/lxd/blob/main/client/lxd_storage_volumes.go"
click node_rest "https://github.com/canonical/lxd/blob/main/lxd/api_1.0.go"
click node_cluster "https://github.com/canonical/lxd/blob/main/lxd/cluster/gateway.go"
click node_auth "https://github.com/canonical/lxd/blob/main/lxd/auth/drivers/authorization.go"
click node_operations "https://github.com/canonical/lxd/blob/main/lxd/operations/operations.go"
click node_events "https://github.com/canonical/lxd/blob/main/lxd/events/events.go"
click node_instances "https://github.com/canonical/lxd/blob/main/lxd/instances_post.go"
click node_instance_drivers "https://github.com/canonical/lxd/blob/main/lxd/instance/drivers/driver_common.go"
click node_images "https://github.com/canonical/lxd/blob/main/lxd/images.go"
click node_network "https://github.com/canonical/lxd/blob/main/lxd/networks.go"
click node_pool_api "https://github.com/canonical/lxd/blob/main/lxd/storage_pools.go"
click node_volume_api "https://github.com/canonical/lxd/blob/main/lxd/storage_volumes.go"
click node_snapshots "https://github.com/canonical/lxd/blob/main/lxd/storage_volumes_snapshot.go"
click node_buckets "https://github.com/canonical/lxd/blob/main/lxd/storage_buckets.go"
click node_storage_engine "https://github.com/canonical/lxd/blob/main/lxd/storage/storage.go"
click node_storage_drivers "https://github.com/canonical/lxd/tree/main/lxd/storage/drivers"
click node_db_volumes "https://github.com/canonical/lxd/blob/main/lxd/db/storage_volumes.go"
click node_db_pools "https://github.com/canonical/lxd/blob/main/lxd/db/storage_pools.go"
click node_db_buckets "https://github.com/canonical/lxd/blob/main/lxd/db/storage_buckets.go"
click node_agent "https://github.com/canonical/lxd/blob/main/lxd-agent/server.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_sdk toneBlue
class node_rest,node_cluster,node_auth,node_operations,node_events toneAmber
class node_instances,node_instance_drivers,node_images,node_network,node_agent toneMint
class node_pool_api,node_volume_api,node_snapshots,node_buckets,node_storage_engine,node_storage_drivers,node_db_volumes,node_db_pools,node_db_buckets toneRose
class node_user toneIndigo
```

## Components

### Access

- [lxc CLI](https://github.com/canonical/lxd/blob/main/lxc/storage_volume.go): `lxc/storage_volume.go`
- [Go client SDK](https://github.com/canonical/lxd/blob/main/client/lxd_storage_volumes.go): `client/lxd_storage_volumes.go`

### Control plane

- [REST API](https://github.com/canonical/lxd/blob/main/lxd/api_1.0.go): `lxd/api_1.0.go`
- [Cluster coordination](https://github.com/canonical/lxd/blob/main/lxd/cluster/gateway.go): `lxd/cluster/gateway.go`
- [Identity and authorization](https://github.com/canonical/lxd/blob/main/lxd/auth/drivers/authorization.go): `lxd/auth/drivers/authorization.go`
- [Async operations](https://github.com/canonical/lxd/blob/main/lxd/operations/operations.go): `lxd/operations/operations.go`
- [Events and lifecycle](https://github.com/canonical/lxd/blob/main/lxd/events/events.go): `lxd/events/events.go`

### Workloads

- [Instance management](https://github.com/canonical/lxd/blob/main/lxd/instances_post.go): `lxd/instances_post.go`
- [Container and VM drivers](https://github.com/canonical/lxd/blob/main/lxd/instance/drivers/driver_common.go): `lxd/instance/drivers/driver_common.go`
- [Image management](https://github.com/canonical/lxd/blob/main/lxd/images.go): `lxd/images.go`
- [Networking](https://github.com/canonical/lxd/blob/main/lxd/networks.go): `lxd/networks.go`
- [Instance agent](https://github.com/canonical/lxd/blob/main/lxd-agent/server.go): `lxd-agent/server.go`

### Storage

- [Storage pools](https://github.com/canonical/lxd/blob/main/lxd/storage_pools.go): `lxd/storage_pools.go`
- [Storage volumes](https://github.com/canonical/lxd/blob/main/lxd/storage_volumes.go): `lxd/storage_volumes.go`
- [Volume snapshots](https://github.com/canonical/lxd/blob/main/lxd/storage_volumes_snapshot.go): `lxd/storage_volumes_snapshot.go`
- [Storage buckets](https://github.com/canonical/lxd/blob/main/lxd/storage_buckets.go): `lxd/storage_buckets.go`
- [Storage backends](https://github.com/canonical/lxd/blob/main/lxd/storage/storage.go): `lxd/storage/storage.go`
- [Storage drivers](https://github.com/canonical/lxd/tree/main/lxd/storage/drivers): `lxd/storage/drivers`
- [Volume metadata](https://github.com/canonical/lxd/blob/main/lxd/db/storage_volumes.go): `lxd/db/storage_volumes.go`
- [Pool metadata](https://github.com/canonical/lxd/blob/main/lxd/db/storage_pools.go): `lxd/db/storage_pools.go`
- [Bucket metadata](https://github.com/canonical/lxd/blob/main/lxd/db/storage_buckets.go): `lxd/db/storage_buckets.go`

### Other components

- **Operator**

## Connections

- Operator → lxc CLI: runs commands
- Operator → Go client SDK: integrates with (evidence: `README.md`)
- lxc CLI → Go client SDK: calls client (evidence: `lxc/storage_volume.go`)
- Go client SDK → REST API: sends requests
- REST API → Identity and authorization: authorizes requests
- REST API → Cluster coordination: forwards requests
- REST API → Async operations: starts operations
- REST API → Events and lifecycle: emits lifecycle
- REST API → Instance management: routes workload requests
- Instance management → Container and VM drivers: manages instances
- REST API → Image management: routes image requests
- REST API → Networking: routes network requests
- REST API → Storage pools: routes pool requests
- REST API → Storage volumes: routes volume requests
- Storage volumes → Volume metadata: reads and writes (evidence: `lxd/storage_volumes.go`)
- Storage volumes → Storage backends: uses pool operations (evidence: `lxd/storage_volumes.go`)
- Storage backends → Storage drivers: selects backend
- Storage volumes → Async operations: runs volume tasks (evidence: `lxd/storage_volumes.go`)
- REST API → Volume snapshots: routes snapshot requests
- Volume snapshots → Storage backends: creates and deletes (evidence: `lxd/storage_volumes_snapshot.go`)
- REST API → Storage buckets: routes bucket requests
- Storage buckets → Bucket metadata: reads and writes (evidence: `lxd/storage_buckets.go`)
- Storage buckets → Storage backends: uses pool operations
- Storage pools → Pool metadata: reads and writes (evidence: `lxd/storage_pools.go`)
- Storage pools → Storage backends: manages backends (evidence: `lxd/storage_pools.go`)
- Instance agent → Go client SDK: uses storage client
