Incus Architecture
Incus follows a client-server architecture where a single daemon (incusd) manages all instances, storage, and networking.
The command-line client communicates with the daemon via a RESTful API over HTTPS or Unix sockets.
System Architecture
Incus Component Architecture
Storage Architecture
Storage Backend Options
Core Components
1. Incus Daemon (incusd)
The central management daemon that handles all operations. It runs as a system service and manages instances, storage pools, networks, and cluster operations.
- RESTful API: Exposes all functionality via HTTPS endpoints
- Authentication: TLS client certificates, token-based, or Unix socket
- Database: SQLite for local operations, distributed database for clusters
- Event System: WebSocket-based event streaming for real-time updates
2. LXC Integration
Incus uses LXC (Linux Containers) for system container functionality, providing OS-level virtualization.
- Namespaces: Process, network, mount, IPC, UTS, user isolation
- Cgroups: Resource limits (CPU, memory, I/O)
- AppArmor/SELinux: Mandatory access control for security
- Seccomp: System call filtering
3. QEMU/KVM Integration
Full hardware virtualization for running VMs with complete isolation and support for any operating system.
- KVM: Kernel-based virtual machine acceleration
- virtio: Paravirtualized drivers for performance
- UEFI/BIOS: Support for modern and legacy boot
- GPU Passthrough: Direct hardware access for graphics
Networking Architecture
| Network Type | Description | Use Case |
|---|---|---|
| Bridge | Linux bridge connecting instances | Standard networking, L2 connectivity |
| Managed | Incus-managed bridge with DHCP/DNS | Easy setup, automatic IP assignment |
| Physical | Direct attachment to host NIC | Direct network access, high performance |
| SR-IOV | Single root I/O virtualization | Near-native network performance for VMs |
| Overlay (VXLAN) | Tunneled L2 over L3 | Multi-host networking, cloud-style |
| OVN | Open Virtual Network integration | Advanced SDN, multi-cluster |
Security Model
Multi-Layer Security
- Containers: Unprivileged by default, user namespace mapping, AppArmor profiles, seccomp filters
- VMs: Hardware-level isolation, complete kernel separation, secure boot support
- API Access: TLS encryption, certificate authentication, RBAC for projects
- Network Isolation: Per-instance firewalls, network ACLs, VLAN separation
- Storage: Encrypted volumes, per-instance quotas, snapshot protection
Resource Management
Incus provides fine-grained resource control through cgroups for both containers and VMs:
- CPU Limits: Number of cores, CPU pinning, priority scheduling
- Memory Limits: Hard limits, soft limits, swap control
- Disk I/O: Read/write limits, IOPS throttling, priority
- Network: Bandwidth limits, ingress/egress control
- Process Limits: Maximum processes per instance
Image Management
Image Server & Distribution
Incus uses an image-based workflow where instances are created from pre-built or custom images.
- Remote Image Servers: Public servers with thousands of distributions
- Local Cache: Downloaded images cached locally for fast deployment
- Image Formats: Unified format for both containers and VMs
- Custom Images: Create from running instances, import external images
- Image Aliases: Human-readable names for image versions
- Auto-Update: Automatic updates for cached images
Understanding Incus architecture helps in planning deployments, troubleshooting issues, and optimizing performance for your specific use cases.