Managing Incus with Terraform (the lxc/incus provider)

Read this page in French

Typing CLI commands to create an instance is fine for learning; describing it as Infrastructure as Code is what makes an infrastructure reproducible. The lxc/incus provider, official to the LXC project, manages Incus instances, profiles, networks and pools with Terraform or OpenTofu. This guide writes a first main.tf, applies it to an Incus server, then targets a remote server by token, and lists the available resources. Tested on Incus 7.0 with OpenTofu 1.12 and provider 1.1.1.

What you will learn

• Declare the lxc/incus provider, local or remote.
• Create an instance and a profile with incus_instance and incus_profile.
• Target a remote server through a trust token.
• The available resources and the common traps.

Prerequisites

• Terraform or OpenTofu installed (the commands below use tofu, terraform behaves identically).
• A reachable Incus server: either local through the Unix socket, or remote with the API exposed (core.https_address).
• The Incus basics: see First steps with Incus.

Declaring the provider

The provider is named lxc/incus on the Terraform and OpenTofu registries. On a local server it connects to the Incus Unix socket; no token is needed.

terraform {
  required_providers {
    incus = {
      source  = "lxc/incus"
      version = "~> 1.1"
    }
  }
}

provider "incus" {
  remote {
    name    = "local"
    address = "unix://"
  }
  default_remote = "local"
}

The remote block declares an Incus server. unix:// targets the local daemon; the remote variant with a token comes further down.

Which version you will actually get

This guide was run with provider 1.1.1. The ~> 1.1 constraint accepts any 1.x release, so a fresh init today pulls the current 1.2.0. That is the intended behaviour of the constraint; pin an exact version instead if you need byte-identical runs across machines.

Creating a first instance

You describe a profile (reusable configuration) and an instance that applies it. The image field follows the remote:alias format: here images:debian/13 pulls from the community image server.

resource "incus_profile" "web" {
  name = "tf-web-profile"
  config = {
    "limits.memory" = "512MiB"
  }
}

resource "incus_instance" "web" {
  name     = "tf-web"
  image    = "images:debian/13"
  type     = "container"
  profiles = ["default", incus_profile.web.name]
  config = {
    "boot.autostart" = "true"
    "limits.cpu"     = "1"
  }
}

1. Initialise the directory: tofu init downloads the provider.

   - Installing lxc/incus v1.1.1...
   - Installed lxc/incus v1.1.1 (signed, key ID C638974D64792D67)
   OpenTofu has been successfully initialized!

2. Apply: tofu apply -auto-approve creates the profile then the instance.

   incus_profile.web: Creation complete after 0s [name=tf-web-profile]
   incus_instance.web: Creation complete after 5s [name=tf-web]
   Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

3. Check on the Incus side: the instance runs, with both profiles applied.

   +--------+---------+-----------+----------+
   |  NAME  |  STATE  |   TYPE    | LOCATION |
   +--------+---------+-----------+----------+
   | tf-web | RUNNING | CONTAINER | node1    |
   +--------+---------+-----------+----------+

On a cluster, the instance is placed automatically (here node1) unless you set target = "node2" in the resource. The profiles column of incus config show tf-web confirms default then tf-web-profile.

Targeting a remote server

To drive a remote Incus server, you declare its address and a single-use trust token, generated on the server with incus config trust add.

provider "incus" {
  generate_client_certificates = true
  accept_remote_certificate    = true
  default_remote               = "cluster"

  remote {
    name    = "cluster"
    address = "https://192.168.10.184:8443"
    token   = "eyJjbGllbnRfbmFtZSI6..."
  }
}

The token is single use

The token only authenticates the first connection: Terraform then generates a client certificate that Incus remembers as trusted. On later apply runs the certificate already exists and the token is no longer used. Regenerate it only if you start from a fresh client. It is the same trust mechanism as adding a node to a cluster.

The available resources

The provider covers the essentials of the Incus object model. Every resource accepts a remote field to target one of the declared servers.

Resource	Role
incus_instance	Container or VM (type = "virtual-machine")
incus_profile	Reusable configuration profile
incus_network	Network (bridge, OVN)
incus_storage_pool	Storage pool (dir, ZFS, LVM)
incus_storage_volume	Custom volume
incus_project	Project (compartmentalisation)
incus_image	Image managed or copied into the pool

Glissez pour voir

The traps worth knowing

Three defaults regularly surprise people, and are worth keeping in mind to avoid unexpected apply runs.

• type defaults to container: for a virtual machine you have to spell out type = "virtual-machine".
• An explicit profiles list replaces the default: if you pass a list, the default profile is not added automatically; include it when you need it, as above.
• The image must be reachable from the remote: image = "images:debian/13" assumes the images remote exists on the server side, which it does by default.

Destroying the infrastructure

Like any Terraform setup, the configuration is reversible: tofu destroy removes the instance and the profile it created. That is the point of IaC against manual clicking: the state is described, versioned and disposable.

tofu destroy -auto-approve

Key points

• The lxc/incus provider manages Incus as code with Terraform or OpenTofu.
• Locally it uses the Unix socket (address = "unix://") with no token.
• Remotely: a single-use trust token, then a client certificate that is remembered.
• Trap: type defaults to container; an explicit profiles list does not add default.
• Resources: incus_instance, incus_profile, incus_network, incus_storage_pool, incus_project.

FAQ: common questions about Terraform and Incus

Which Terraform provider should you use for Incus?

The official lxc/incus provider, published on both the Terraform and OpenTofu registries. You declare it in required_providers with the lxc/incus source. It manages instances, profiles, networks, pools and projects, locally over the Unix socket or remotely through a trust token.

How do you create an Incus instance with Terraform?

With the incus_instance resource: you set name, image in the remote:alias format such as images:debian/13, the type container or virtual-machine, and a config map. Running tofu apply creates the instance on the Incus server.

How do you target a remote Incus server with Terraform?

You declare a remote block with the https address and a trust token generated by incus config trust add. The token only authenticates the first connection; Terraform then generates a client certificate that Incus remembers as trusted.

Do you need Terraform or OpenTofu to manage Incus?

Both work identically with the lxc/incus provider, which is published on both registries. The tofu and terraform commands are interchangeable on this configuration. OpenTofu is the community open source alternative to Terraform.

Next steps

• Automating Incus image builds: feed your resources your own images rather than those of the public registry.
• Terraform: a three-tier stack: the same provider, describing a whole private cloud.
• Ansible connection plugin: configure the inside of the instances this provider creates.

×

📖 Voir la documentation →