Build d’un ISO NixOS et d’une AMI EC2 sur mesure : tutoriel

📍 Guide principal : NixOS pour développeurs et serveurs : reproductibilité totale en 2026
Ce tutoriel suppose un flake fonctionnel et la familiarité avec les nixosConfigurations (cf. nixos-rebuild remote).

La voie officielle 25.11 : nixos-rebuild build-image

Depuis NixOS 25.11, la commande nixos-rebuild build-image intégrée à nixpkgs construit des images dans plusieurs variantes officielles, sans dépendance externe. La syntaxe minimale :

# Lister les variants disponibles
nixos-rebuild build-image --flake .#vps01

# Construire une image AMI Amazon
nixos-rebuild build-image --flake .#vps01 --image-variant amazon

# Construire pour Linode, GCE, etc. selon les variantes définies
nixos-rebuild build-image --flake .#vps01 --image-variant linode

Les variantes disponibles sont définies (et extensibles) dans image.modules de votre configuration NixOS. Pour les ISOs bootables, le manuel renvoie toujours vers le module installation-cd-minimal.nix + nix-build -A config.system.build.isoImage ; pour les images disque génériques, le module image.repart avec systemd-repart fait le travail.

L’approche historique : nixos-generators (toujours fonctionnel)

Pourquoi générer ses propres images plutôt qu’utiliser celles du fournisseur

Quand vous provisionnez une VM chez AWS, GCP, Hetzner ou DigitalOcean, le fournisseur propose des images NixOS officielles ou communautaires. Elles font le job pour démarrer, mais elles ont deux limites. Premièrement, elles évoluent au rythme du fournisseur, pas au vôtre — vous ne maîtrisez pas quels paquets, quelle version du kernel, quelle config systemd elles embarquent. Deuxièmement, vous devez quand même faire un nixos-rebuild derrière pour appliquer votre configuration, ce qui rallonge le boot initial de plusieurs minutes.

L’approche reproductible : générer vos propres images directement à partir de votre flake. L’image embarque déjà votre config, vos paquets, vos services, vos clés SSH. Au boot, la VM tourne directement votre génération NixOS, prête à servir en quelques secondes. Le pattern marche pour les ISO bootables (clés USB de récupération, installeurs custom), pour les AMI EC2, pour les images GCP, pour les qcow2 KVM, pour les images de containers.

Ce tutoriel utilise nixos-generators, l’outil communautaire qui standardise la génération d’images dans une douzaine de formats. Vous obtiendrez à la fin un ISO bootable et une AMI déployable sur AWS.

Prérequis

• Un flake fonctionnel avec une nixosConfigurations que vous savez déployer.
• Au moins 5 Go d’espace disque libre pour les builds d’images.
• Un compte AWS avec accès à aws ec2 register-image si vous voulez la partie AMI (optionnel pour ce tutoriel).

Étape 1 — Ajouter nixos-generators au flake

Le projet nix-community/nixos-generators expose une fonction nixosGenerate qui prend votre configuration et un format cible, et produit l’image. Modifiez votre flake.nix :

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
    nixos-generators = {
      url = "github:nix-community/nixos-generators";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, nixos-generators }: {
    packages.x86_64-linux = {
      iso = nixos-generators.nixosGenerate {
        system = "x86_64-linux";
        format = "iso";
        modules = [ ./hosts/installer.nix ];
      };

      amazon = nixos-generators.nixosGenerate {
        system = "x86_64-linux";
        format = "amazon";
        modules = [ ./hosts/cloud.nix ];
      };

      qcow = nixos-generators.nixosGenerate {
        system = "x86_64-linux";
        format = "qcow";
        modules = [ ./hosts/cloud.nix ];
      };
    };
  };
}

Vous exposez désormais trois packages : un ISO bootable, une AMI Amazon, et une image qcow2 pour KVM/libvirt. Tous partent du même flake, donc tous embarquent la version exacte de NixOS pinnée.

Étape 2 — La configuration commune pour les images cloud

Créez hosts/cloud.nix avec la config qui s’applique à toutes les VMs cloud :

{ config, pkgs, lib, modulesPath, ... }:
{
  networking.hostName = lib.mkDefault "cloud-vm";
  networking.firewall.enable = true;
  networking.firewall.allowedTCPPorts = [ 22 ];

  services.openssh = {
    enable = true;
    settings.PasswordAuthentication = false;
  };

  users.users.deploy = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
    openssh.authorizedKeys.keys = [
      "ssh-ed25519 AAAAC3Nz... alice@laptop"
    ];
  };
  security.sudo.wheelNeedsPassword = false;

  nix.settings.experimental-features = [ "nix-command" "flakes" ];

  environment.systemPackages = with pkgs; [ vim git htop curl ];

  system.stateVersion = "25.11";
}

Au boot, la VM aura SSH activé, votre clé déjà déposée, et l’utilisateur deploy avec sudo sans mot de passe. Vous pouvez vous connecter immédiatement et lancer nixos-rebuild --target-host pour les ajustements ultérieurs.

Étape 3 — La configuration de l’installeur ISO

Créez hosts/installer.nix pour l’image bootable de récupération ou d’installation :

{ config, pkgs, lib, modulesPath, ... }:
{
  imports = [
    "${modulesPath}/installer/cd-dvd/installation-cd-minimal.nix"
  ];

  isoImage.isoName = lib.mkForce "nixos-custom-25.11.iso";

  networking.networkmanager.enable = true;
  services.openssh = {
    enable = true;
    settings.PermitRootLogin = "yes";
  };

  users.users.root.openssh.authorizedKeys.keys = [
    "ssh-ed25519 AAAAC3Nz... alice@laptop"
  ];

  environment.systemPackages = with pkgs; [
    vim git tmux htop ripgrep fd
    parted gptfdisk cryptsetup
  ];
}

L’import du module installation-cd-minimal.nix (fourni par nixpkgs) est la base d’un ISO d’installation. On surcharge le nom de l’ISO, on ajoute SSH avec votre clé pour pouvoir piloter l’installation à distance, et on inclut quelques outils utiles. C’est l’image que vous flasherez sur une clé USB pour installer NixOS sur une nouvelle machine ou pour faire de la récupération sur une machine cassée.

Étape 4 — Construire l’ISO

Lancez le build :

nix build .#iso

Le build prend 10 à 30 minutes selon votre connexion (téléchargement des paquets) et votre CPU (compilation des éventuels paquets custom). À la fin, un lien symbolique result/ apparaît à la racine ; le fichier ISO est sous result/iso/nixos-custom-25.11.iso.

ls -lh result/iso/
sha256sum result/iso/nixos-custom-25.11.iso

Le SHA256 vous servira à vérifier l’intégrité après transfert. Pour flasher sur une clé USB :

sudo dd if=result/iso/nixos-custom-25.11.iso of=/dev/sdX bs=4M conv=fsync status=progress

Vérifiez le device avec lsblk avant — /dev/sdX doit pointer sur la clé USB, pas sur un disque interne.

Étape 5 — Construire et tester l’image qcow KVM

Pour tester en local sans matériel dédié :

nix build .#qcow
ls -lh result/nixos.qcow2

Lancez la VM via QEMU :

qemu-system-x86_64 \
  -enable-kvm -m 2048 -smp 2 \
  -drive file=result/nixos.qcow2,format=qcow2 \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0

La VM boote dans une fenêtre QEMU. Le port 22 de la VM est mappé sur 2222 de votre hôte ; ssh -p 2222 deploy@localhost vous connecte à la VM avec votre clé SSH. C’est un excellent moyen de tester votre config sans risquer un serveur de production.

Étape 6 — Construire l’AMI Amazon EC2

Le build de l’AMI suit la même mécanique :

nix build .#amazon
ls -lh result/

La sortie contient un fichier .vhd (ou .raw selon les options) prêt à être uploadé sur S3 puis enregistré comme AMI. La procédure exacte d’enregistrement utilise l’AWS CLI :

aws s3 cp result/nixos-amazon-image.vhd s3://mon-bucket/
aws ec2 import-snapshot \
  --description "NixOS 25.11 custom" \
  --disk-container "Format=VHD,UserBucket={S3Bucket=mon-bucket,S3Key=nixos-amazon-image.vhd}"

# Récupérer l'ImportTaskId, attendre completion, puis :
aws ec2 register-image \
  --name "nixos-25.11-custom" \
  --architecture x86_64 \
  --root-device-name /dev/xvda \
  --virtualization-type hvm \
  --ena-support \
  --block-device-mappings '[{"DeviceName":"/dev/xvda","Ebs":{"SnapshotId":"snap-xxxxxxxx"}}]'

L’AMI est désormais visible dans la console EC2 et utilisable pour lancer des instances. Beaucoup d’opérateurs scriptent toute cette séquence avec un nix run qui appelle l’AWS CLI ; le projet NixOS/amis en montre des exemples.

Étape 7 — Les autres formats supportés

nixos-generators expose plus d’une dizaine de formats. Quelques-uns particulièrement utiles :

• iso — image ISO bootable (USB, DVD).
• install-iso — variante d’ISO avec l’installeur graphique.
• amazon — AMI EC2.
• azure — image Azure VHD.
• do — image DigitalOcean.
• gce — image Google Compute Engine.
• hyperv — VHDX pour Hyper-V.
• kubevirt — image pour KubeVirt.
• proxmox — image VMA pour Proxmox.
• qcow — qcow2 pour KVM/libvirt.
• raw — image disque brute, à dd directement.
• raw-efi — variante avec ESP UEFI prête.
• vmware — VMDK pour VMware.
• docker — image OCI/Docker.

Pour chacun, remplacez format = "..." dans nixosGenerate. La même configuration NixOS produit la même machine sur tous les supports — c’est exactement la promesse multi-cible du modèle.

Étape 8 — CI : générer les images automatiquement

Pour publier des images à chaque release, branchez la commande au workflow CI vu dans le tutoriel CI Nix avec flakes et GitHub Actions :

jobs:
  build-images:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cachix/install-nix-action@v31
      - run: nix build .#iso .#qcow .#amazon
      - uses: actions/upload-artifact@v4
        with:
          name: nixos-images
          path: result*

Chaque push sur main produit les trois images, attachées comme artefacts du run. Pour automatiser le déploiement en S3 ou dans la registry de votre fournisseur, ajoutez une étape aws s3 cp ou équivalent. Combiné avec un tag git, vous obtenez une release automatique d’images NixOS taguées par version, prête à être consommée par votre orchestrateur (Terraform, ArgoCD).

Erreurs fréquentes

Le pattern golden image vs configuration au boot

Deux philosophies coexistent. Golden image : l’image embarque la config complète et finale. Au boot, la VM est immédiatement prête. Avantage : démarrage rapide, pas de dépendance externe. Inconvénient : pour mettre à jour, il faut générer une nouvelle image et reprovisionner la VM. Image minimale + rebuild : l’image embarque juste le nécessaire pour booter et accepter SSH. Vous appliquez la vraie config via nixos-rebuild --target-host après le premier boot. Avantage : updates triviaux. Inconvénient : démarrage plus lent, dépend du réseau et du dépôt git.

Pour des serveurs longue durée (bases de données, monitoring), la golden image est souvent surdimensionnée. Pour des workloads éphémères (workers de batch, runners CI), elle est l’idéal — vous spinnez 50 instances en parallèle, toutes identiques, sans aucune coordination.

Cas d’usage : un installeur NixOS personnalisé pour vos clients ou pour vos labos

Beaucoup de DSI internes veulent un installeur custom : leur fond d’écran, leurs outils internes pré-installés, leurs clés SSH d’admin déjà déposées, leurs scripts de partitionnement maison. Avec install-iso, vous générez en quelques minutes un ISO personnalisé qui démarre sur l’installeur graphique Calamares avec votre branding. Pour un labo de formation, l’ISO embarque les outils pédagogiques et un compte étudiant prêt à l’emploi. Le pattern remplace efficacement les outils plus lourds comme MDT côté Microsoft ou Cobbler côté CentOS.

Suite logique

Cette série couvre désormais le cycle complet : installation, flakes, environnement utilisateur, dev-shells, déploiement distant, secrets, CI, et génération d’images. Le guide principal NixOS reste le point de référence pour situer chaque brique. Pour aller plus loin, explorez colmena ou deploy-rs pour la gestion de flotte, nix-darwin pour appliquer le modèle à macOS, et les RFCs publiques sur github.com/NixOS/rfcs pour suivre l’évolution du langage.

Références officielles

• nix-community/nixos-generators — outil et liste complète des formats.
• Manuel NixOS — Building images.
• Modules d’installeur dans nixpkgs — les imports disponibles.
• Wiki — NixOS Generators — exemples avancés.