Gérer Incus avec Terraform (provider lxc/incus)

Cliquer dans la CLI pour créer une instance, c'est bien pour apprendre ; le décrire en Infrastructure as Code, c'est ce qui rend une infra reproductible. Le provider lxc/incus (officiel du projet LXC) permet de gérer instances, profils, réseaux et pools Incus avec Terraform ou OpenTofu. Ce guide écrit un premier main.tf, applique la configuration sur un serveur Incus, cible ensuite un serveur distant par token, et liste les ressources disponibles. Testé sur Incus 7.0 avec OpenTofu 1.12 et le provider 1.1.

Ce que vous allez apprendre

Déclarer le provider lxc/incus (local ou distant).
Créer une instance et un profil en incus_instance / incus_profile.
Cibler un serveur distant par token de confiance.
Les ressources disponibles et les pièges courants.

Prérequis

Terraform ou OpenTofu installé (les commandes ci-dessous utilisent tofu, terraform est identique).
Un serveur Incus accessible : soit en local (socket Unix), soit distant avec l'API exposée (core.https_address).
Les bases d'Incus : voir Premiers pas avec Incus.

Déclarer le provider

Le provider s'appelle lxc/incus sur les registres Terraform et OpenTofu. Sur un serveur local, il se connecte au socket Unix d'Incus ; aucun token n'est nécessaire.

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

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

Le bloc remote déclare un serveur Incus. unix:// cible le démon local ; on verra plus bas la variante distante par token.

Créer une première instance

On décrit un profil (configuration réutilisable) et une instance qui l'applique. Le champ image suit le format remote:alias : ici images:debian/13 tire depuis le serveur d'images communautaire.

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"
  }
}

Initialiser le répertoire : tofu init télécharge le provider.

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

Appliquer : tofu apply -auto-approve crée le profil puis l'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.

Vérifier côté Incus : l'instance tourne, avec les deux profils appliqués.

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

Sur un cluster, l'instance est placée automatiquement (ici node1) sauf si vous fixez target = "node2" dans la ressource. La colonne profiles de incus config show tf-web confirme bien default puis tf-web-profile.

Cibler un serveur distant

Pour piloter un serveur Incus distant, on déclare son adresse et un token de confiance à usage unique, généré côté serveur avec 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..."
  }
}

Les ressources disponibles

Le provider couvre l'essentiel de l'objet Incus. Chaque ressource accepte un champ remote pour cibler un serveur précis parmi ceux déclarés.

Ressource	Rôle
`incus_instance`	Conteneur ou VM (`type = "virtual-machine"`)
`incus_profile`	Profil de configuration réutilisable
`incus_network`	Réseau (bridge, OVN)
`incus_storage_pool`	Pool de stockage (dir, ZFS, LVM)
`incus_storage_volume`	Volume personnalisé
`incus_project`	Projet (cloisonnement)
`incus_image`	Image gérée/copiée dans le pool

Les pièges à connaître

Trois comportements par défaut surprennent souvent, à garder en tête pour éviter des apply inattendus.

type vaut container par défaut : pour une machine virtuelle, il faut expliciter type = "virtual-machine".
La liste profiles remplace le défaut : si vous passez une liste explicite, le profil default n'est pas ajouté automatiquement ; incluez-le si vous en avez besoin (comme ci-dessus).
L'image doit être accessible depuis le remote : image = "images:debian/13" suppose que le remote images existe côté serveur (c'est le cas par défaut).

Détruire l'infrastructure

Comme toute infra Terraform, la configuration est réversible : tofu destroy supprime l'instance et le profil créés. C'est l'intérêt de l'IaC face au clic manuel : l'état est décrit, versionné et jetable.

tofu destroy -auto-approve

À retenir

Le provider lxc/incus gère Incus en IaC avec Terraform ou OpenTofu.
En local, il utilise le socket Unix (address = "unix://") sans token.
À distance : un token de confiance à usage unique, puis un certificat client mémorisé.
Piège : type vaut container par défaut ; profiles explicite n'ajoute pas default.
Ressources : incus_instance, incus_profile, incus_network, incus_storage_pool, incus_project.

FAQ : questions fréquentes sur Terraform et Incus

Quel provider Terraform utiliser pour Incus ?

Le provider officiel lxc/incus, publié sur les registres Terraform et OpenTofu. On le déclare dans required_providers avec la source lxc/incus. Il gère instances, profils, réseaux, pools et projets, en local via le socket Unix ou à distance par token.

Le provider lxc/incus

Le provider officiel du projet LXC est lxc/incus, disponible sur les registres Terraform et OpenTofu.

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

Il gère incus_instance, incus_profile, incus_network, incus_storage_pool et incus_project. En local il utilise le socket Unix (address = "unix://"), à distance un token de confiance.

Comment créer une instance Incus avec Terraform ?

Avec la ressource incus_instance : on précise name, image au format remote:alias comme images:debian/13, le type container ou virtual-machine, et une map config. La commande tofu apply crée l'instance sur le serveur Incus.

La ressource incus_instance

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

Le champ image suit le format remote:alias. Le type vaut container par défaut ; pour une VM, mettre type = "virtual-machine". Un tofu apply crée l'instance :

incus_instance.web: Creation complete after 5s [name=tf-web]
Apply complete! Resources: 1 added.

Comment cibler un serveur Incus distant avec Terraform ?

On déclare un bloc remote avec l'adresse https et un token de confiance généré par incus config trust add. Le token n'authentifie que la première connexion ; Terraform génère ensuite un certificat client qu'Incus mémorise comme approuvé.

Bloc remote et token

provider "incus" {
  accept_remote_certificate = true
  default_remote            = "cluster"
  remote {
    name    = "cluster"
    address = "https://192.168.10.184:8443"
    token   = "eyJjbGllbnRfbmFtZSI6..."
  }
}

Le token (généré par incus config trust add) n'authentifie que la première connexion : Terraform génère un certificat client qu'Incus mémorise. Aux apply suivants, le token n'est plus utilisé.

Faut-il Terraform ou OpenTofu pour gérer Incus ?

Les deux fonctionnent à l'identique avec le provider lxc/incus, publié sur les deux registres. Les commandes tofu et terraform sont interchangeables sur cette configuration. OpenTofu est l'alternative open source communautaire à Terraform.

Prochaines étapes

Gérer Incus avec Ansible Connection plugin et provisioning.

Cluster Incus Répartir les instances sur plusieurs nœuds.

Profils et projets Industrialiser la configuration.