Kubernetes Cluster API Provider Incus

Kubernetes-native declarative infrastructure for Incus, Canonical LXD and Canonical MicroCloud.

What is the Cluster API Provider Incus

Cluster API is a Kubernetes sub-project focused on providing declarative APIs and tooling to simplify provisioning, upgrading, and operating multiple Kubernetes clusters.

cluster-api-provider-incus (CAPN) is an Infrastructure Provider for Cluster API, which enables deploying clusters on infrastructure operated by Incus, Canonical LXD and Canonical MicroCloud.

The provider can be used in single-node development environments for evaluation and testing, but also work with multi-node clusters to deploy and manage production Kubernetes clusters.

Documentation

Please refer to our book for in-depth documentation.

Quick Start

See Quick Start to launch a cluster on a single-node development environment.

Features

• Supports Incus, Canonical LXD and Canonical MicroCloud.
• Support for kube-vip (production), OVN network load balancers or simple haproxy containers (development) for the cluster load balancer.
• Default simplestreams server with pre-built kubeadm images.
• Supports virtual machines or LXC containers for the cluster machines. Automatically manages the profile for Kubernetes to work in LXC containers.
• Can be used for local development similar to CAPD for quickly iterating on custom bootstrap and control-plane providers, e.g. K3s, Canonical Kubernetes, etc.

ClusterAPI Support

ClusterAPI v1.11 (August 2025) introduced a new v1beta2 API contract. cluster-api-provider-incus supports it starting from version v0.9.0.

Support commitments for CAPN versions are:

• v0.8.x series will not receive any further updates, bug and/or security fixes.
• Development and new features are added to the latest version of cluster-api-provider-incus only, and will not be backported to older versions.
• v0.8.x is marked as supporting only up to Incus<7.0.0, because of the removal of cgroupv1 support in Incus v7.0.0.

Upgrade notes for v0.8.0/v1beta1 -> v0.9.0/v1beta2

• After updating to v0.9.0, the v1alpha2 CRDs are updated to follow the v1beta2 API contract.
• All status fields will initially be empty, as previous fields have been moved. After cluster-api-provider-incus controller starts, it will reconcile all LXCMachine and LXCCluster resources to set status.initialization fields and conditions.
• All ClusterAPI controllers must be restarted after upgrading to v0.9.0, to ensure they are not using cached v1beta1 CRDs

Project Roadmap

v0.10.0

Rough steps for version v0.10.0:

• Use kini for quick start guide.
• Load balancer IPAM (CAPN automatically claims/releases load balancer IP addresses from the network).
• Improve generated API reference documentation.
• Add cluster-templates for 3rd party providers, e.g. Canonical Kubernetes.
• Write documentation with common troubleshooting steps.
• Write documentation with common cluster deployment scenarios.

v0.9.0

• Add kini command line tool, re-using building blocks from kind.
• Use kini for e2e tests.
• Build images for v1.34.0, based on Ubuntu 24.04 and Debian 13.
• Private initial alpha testing.
• Cloud provider node patch to link Machines with workload cluster Nodes.
• Test with both Incus and Canonical LXD.
• Start cluster-api-provider-incus book with quick start guide, cluster templates, API reference.
• Publish v0.1.0 release to get initial user feedback.
• Add e2e tests using the cluster-api testing framework.
• Add PR blocking CI pipelines.
• Publish v0.2.0 release with v1alpha2 APIs.
• Add e2e tests for cluster upgrades.
• Explore clusters with ClusterTopology=true (clusterclass), also allows us to run all existing ClusterAPI e2e tests like Autoscaler, etc.
• Write developer guide.
• Support unprivileged containers.
• Support configurable machine placement for production clusters.
• Extend e2e suite with tests for all cluster-template types (kvm, unprivileged containers, kube-vip, ovn)
• Add self-hosted e2e test.
• Implement kind instance types (using OCI containers with the kindest/node images from the kind project).
• Gather initial user feedback.

$Future

• Migrate to for ClusterAPI v1beta2 contract.
• Add to default list of providers supported by ClusterAPI.
• Improve API validations and possibly API conformance tests.
• Add CI to build kubeadm images for the default simplestreams server. Pushing will remain manual for now.
• Decide on project OWNERSHIP and testing infrastructure (part of LXC org).
• Refactor internal/incus package and improve consistency and log levels across the code.
• Split cloud provider node patch to external cloud-provider-incus project.

Getting involved and contributing

The cluster-api-provider-incus project would love your suggestions, contributions and help! The maintainers can be contacted at any time to learn mode about how to get involved.

Remember that there are numerous effective ways to contribute to the project: raise a pull request to fix a bug, improve test coverage, improve existing documentation or even participate in GitHub issues. We want your help!

Please refer to the developer guide in order to get started with setting up a local environment for development and testing.