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 ; la variante distante par token est décrite plus bas.

La version que vous obtiendrez vraiment

Ce guide a été exécuté avec le provider 1.1.1. La contrainte ~> 1.1 accepte toute version 1.x : un init lancé aujourd'hui récupère la 1.2.0 actuelle. C'est le comportement voulu de la contrainte ; épinglez une version exacte si vous avez besoin d'exécutions identiques d'une machine à l'autre.

Créer une première instance

On décrit un profil, c'est-à-dire une configuration réutilisable, et une instance qui l'applique. Le champ image suit le format remote:alias : 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"
  }
}

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!

2. 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.

3. 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 sur node1, sauf si vous fixez target = "node2" dans la ressource. La colonne profiles de incus config show tf-web confirme l'ordre d'application : 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 par 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..."
  }
}

Le token est à usage unique

Le token n'authentifie que la première connexion : Terraform génère alors un certificat client qu'Incus mémorise comme approuvé. Aux apply suivants, le certificat existe déjà et le token n'est plus utilisé. Ne le régénérez que si vous repartez d'un client vierge. C'est le mécanisme de confiance décrit pour ajouter un nœud au cluster.

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

Glissez pour voir

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 infrastructure 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 ?

Comment créer une instance Incus avec Terraform ?

Comment cibler un serveur Incus distant avec Terraform ?

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

×

📖 Voir la documentation →