nixos-rebuild: init build-image subcommand

nixos/doc/manual/installation/building-images-via-nixos-rebuild-build-image.chapter.md

@@ -0,0 +1,16 @@
+# Building Images with `nixos-rebuild build-image` {#sec-image-nixos-rebuild-build-image}
+
+Nixpkgs contains a variety of modules to build custom images for different virtualization platforms and cloud providers, such as e.g. `amazon-image.nix` and `proxmox-lxc.nix`.
+
+While those can be imported individually, `system.build.images` provides an attribute set mapping variant names to image derivations. Available variants are defined - end extendable - in `image.modules`, an attribute set mapping variant names to a list of NixOS modules.
+
+All of those images can be built via both, their `system.build.image` attribute, and the CLI `nixos-rebuild build-image`. To build i.e. an Amazon image from your existing NixOS configuration:
+
+```ShellSession
+$ nixos-rebuild build-image --image-variant amazon
+$ ls result
+nixos-image-amazon-25.05pre-git-x86_64-linux.vhd  nix-support
+```
+
+To get a list of all variants available, run `nixos-rebuild build-image` without arguments.
+

nixos/doc/manual/installation/building-nixos.chapter.md

@@ -1,7 +1,7 @@
 # Building a NixOS (Live) ISO {#sec-building-image}
 
 Default live installer configurations are available inside `nixos/modules/installer/cd-dvd`.
-For building other system images, [nixos-generators] is a good place to start looking at.
+For building other system images, see [Building Images with `nixos-rebuild build-image`](#sec-image-nixos-rebuild-build-image).
 
 You have two options:
 
@@ -14,8 +14,6 @@ on which they immediately depend in order to work correctly.
 However, if you are confident, you can opt to override those
 enforced values with `mkForce`.
 
-[nixos-generators]: https://github.com/nix-community/nixos-generators
-
 ## Practical Instructions {#sec-building-image-instructions}
 
 To build an ISO image for the channel `nixos-unstable`:
@@ -30,7 +28,7 @@ $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd
 To check the content of an ISO image, mount it like so:
 
 ```ShellSession
-# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso
+# mount -o loop -t iso9660 ./result/iso/nixos-image-25.05pre-git-x86_64-linux.iso /mnt/iso
 ```
 
 ## Additional drivers or firmware {#sec-building-image-drivers}

nixos/doc/manual/installation/installation.md

@@ -8,5 +8,6 @@ installing.chapter.md
 changing-config.chapter.md
 upgrading.chapter.md
 building-nixos.chapter.md
+building-images-via-nixos-rebuild-build-image.chapter.md
 building-images-via-systemd-repart.chapter.md
 ```

nixos/doc/manual/redirects.json

@@ -167,6 +167,9 @@
   "sec-building-image-tech-notes": [
     "index.html#sec-building-image-tech-notes"
   ],
+  "sec-image-nixos-rebuild-build-image": [
+    "index.html#sec-image-nixos-rebuild-build-image"
+  ],
   "sec-image-repart": [
     "index.html#sec-image-repart"
   ],

nixos/doc/manual/release-notes/rl-2505.section.md

@@ -8,6 +8,10 @@
 
 - `nixos-rebuild-ng`, a full rewrite of `nixos-rebuild` in Python, is available for testing. You can enable it by setting [system.rebuild.enableNg](options.html#opt-system.rebuild.enableNg) in your configuration (this will replace the old `nixos-rebuild`), or by adding `nixos-rebuild-ng` to your `environment.systemPackages` (in this case, it will live side-by-side with `nixos-rebuild` as `nixos-rebuild-ng`). It is expected that the next major version of NixOS (25.11) will enable `system.rebuild.enableNg` by default.
 
+- A `nixos-rebuild build-image` sub-command has been added.
+
+  It allows users to build platform-specific (disk) images from their NixOS configurations. `nixos-rebuild build-image` works similar to the popular [nix-community/nixos-generators](https://github.com/nix-community/nixos-generators) project. See new [section on image building in the nixpkgs manual](https://nixos.org/manual/nixpkgs/unstable/#sec-image-nixos-rebuild-build-image).
+
 <!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
 
 ## New Modules {#sec-release-25.05-new-modules}
@@ -132,6 +136,32 @@
 
 - `python3Packages.opentracing` has been removed due to being unmaintained upstream. [OpenTelemetry](https://opentelemetry.io/) is the recommended replacement.
 
+- Default file names of images generated by several builders in `system.build` have been changed as outlined in the table below.
+
+  Names are now known at evaluation time and customizable via the new options `image.baseName`, `image.extension`, `image.fileName` and `image.filePath` with the latter returning a path relative to the derivations out path (e.g. `iso/${image.fileName` for iso images).
+
+  | `system.build` Option    | Old Filename                                               | New Filename                                                    |
+  |--------------------------+------------------------------------------------------------+-----------------------------------------------------------------|
+  | amazonImage              | nixos-amazon-image-25.05pre-git-x86_64-linux.vhd           | nixos-image-amazon-25.05pre-git-x86_64-linux.vhd                |
+  | azureImage               | disk.vhd                                                   | nixos-image-azure-25.05pre-git-x86_64-linux.vhd                 |
+  | digitalOceanImage        | nixos.qcow2.gz                                             | nixos-image-digital-ocean-25.05pre-git-x86_64-linux.qcow2.gz    |
+  | googleComputeImage       | nixos-image-25.05pre-git-x86_64-linux.raw.tar.gz           | nixos-image-google-compute-25.05pre-git-x86_64-linux.raw.tar.gz |
+  | hypervImage              | nixos-25.05pre-git-x86_64-linux.vhdx                       | nixos-image-hyperv-25.05pre-git-x86_64-linux.vhdx               |
+  | isoImage (installer)     | nixos-25.05pre-git-x86_64-linux.iso                        | nixos-image-25.05pre-git-x86_64-linux.iso                       |
+  | isoImage                 | nixos.iso                                                  | nixos-image-25.05pre-git-x86_64-linux.iso                       |
+  | kubevirtImage            | nixos.qcow2                                                | nixos-image-kubevirt-25.05pre-git-x86_64-linux.qcow2            |
+  | linodeImage              | nixos-image-25.05pre-git-x86_64-linux.img.gz               | nixos-image-linode-25.05pre-git-x86_64-linux.img.gz             |
+  | metadata (lxc-container) | nixos-system-x86_64-linux.tar.xz                           | nixos-image-lxc-metadata-25.05pre-git-x86_64-linux.tar.xz       |
+  | OCIImage                 | nixos.qcow2                                                | nixos-image-oci-25.05pre-git-x86_64-linux.qcow2                 |
+  | openstackImage (zfs)     | nixos-openstack-image-25.05pre-git-x86_64-linux.root.qcow2 | nixos-image-openstack-zfs-25.05pre-git-x86_64-linux.root.qcow2  |
+  | openstackImage           | nixos.qcow2                                                | nixos-image-openstack-25.05pre-git-x86_64-linux.qcow2           |
+  | sdImage                  | nixos-sd-image-25.05pre-git-x86_64-linux.img.zst           | nixos-image-sd-card-25.05pre-git-x86_64-linux.img.zst           |
+  | tarball (lxc-container)  | nixos-system-x86_64-linux.tar.xz                           | nixos-image-lxc-25.05pre-git-x86_64-linux.tar.xz                |
+  | tarball (proxmox-lxc)    | nixos-system-x86_64-linux.tar.xz                           | nixos-image-lxc-proxmox-25.05pre-git-x86_64-linux.tar.xz        |
+  | vagrantVirtualbox        | nixos-25.05pre-git-x86_64-linux.ova                        | nixos-image-virtualbox-25.05pre-git-x86_64-linux.ova            |
+  | virtualBoxOVA            | virtualbox-vagrant.box                                     | nixos-image-vagrant-virtualbox-25.05pre-git-x86_64-linux.ova    |
+  | vmwareImage              | nixos-25.05pre-git-x86_64-linux.vmdk                       | nixos-image-vmware-25.05pre-git-x86_64-linux.vmdk               |
+
 - the notmuch vim plugin now lives in a separate output of the `notmuch`
   package. Installing `notmuch` will not bring the notmuch vim package anymore,
   add `vimPlugins.notmuch-vim` to your (Neo)vim configuration if you want the

nixos/maintainers/scripts/ec2/README.md

@@ -18,10 +18,10 @@ nix run nixpkgs#upload-ami -- --image-info ./result/nix-support/image-info.json
 
 ## How to build your own NixOS config into an AMI
 
-I suggest looking at https://github.com/nix-community/nixos-generators for a user-friendly interface.
+Use `nixos-rebuild build-image` as follows:
 
 ```bash
-nixos-generate -c ./my-config.nix -f amazon
+NIXOS_CONFIG="$(pwd)/my-config.nix" nixos-rebuild build-image --image-variant amazon
 
 export AWS_REGION=us-west-2
 export AWS_PROFILE=my-profile

pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8

@@ -10,7 +10,7 @@
 .Sh SYNOPSIS
 .Nm
 .Bro
-.Cm switch | boot | test | build | dry-build | dry-activate | edit | repl | build-vm | build-vm-with-bootloader | list-generations Op Fl -json
+.Cm switch | boot | test | build | dry-build | dry-activate | edit | repl | build-vm | build-vm-with-bootloader | build-image | list-generations Op Fl -json
 .Brc
 .br
 .Op Fl -upgrade | -upgrade-all
@@ -34,6 +34,8 @@
 .Op Fl -profile-name | p Ar name
 .Op Fl -specialisation | c Ar name
 .br
+.Op Fl -image-variant Ar variant
+.br
 .Op Fl -build-host Va host
 .Op Fl -target-host Va host
 .Op Fl -use-remote-sudo
@@ -226,6 +228,16 @@ containing a
 .Pa /boot
 partition.
 .
+.It Cm build-image
+Build a disk-image variant, pre-configured for the given platform/provider.
+Select a variant with the
+.Fl --image-variant
+option or run without any options to get a list of available variants.
+
+.Bd -literal -offset indent
+$ nixos-rebuild build-image --image-variant proxmox
+.Ed
+.
 .It Cm list-generations Op Fl -json
 List the available generations in a similar manner to the boot loader
 menu. It shows the generation number, build date and time, NixOS version,
@@ -323,6 +335,12 @@ The new configuration will appear in the GRUB 2 submenu
 Activates given specialisation; when not specified, switching and testing
 will activate the base, unspecialised system.
 .
+.It Fl -image-variant Ar variant
+Selects an image variant to build from
+the
+.Va config.system.build.images
+attribute of the given configuration. A list of variants is printed if this option remains unset.
+.
 .It Fl -build-host Ar host
 Instead of building the new configuration locally, use the specified host
 to perform the build. The host needs to be accessible with

pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.sh

@@ -29,6 +29,7 @@ upgrade=
 upgrade_all=
 profile=/nix/var/nix/profiles/system
 specialisation=
+imageVariant=
 buildHost=
 targetHost=
 remoteSudo=
@@ -52,7 +53,7 @@ while [ "$#" -gt 0 ]; do
       --help)
         showSyntax
         ;;
-      switch|boot|test|build|edit|repl|dry-build|dry-run|dry-activate|build-vm|build-vm-with-bootloader|list-generations)
+      switch|boot|test|build|edit|repl|dry-build|dry-run|dry-activate|build-vm|build-vm-with-bootloader|build-image|list-generations)
         if [ "$i" = dry-run ]; then i=dry-build; fi
         if [ "$i" = list-generations ]; then
             buildNix=
@@ -153,6 +154,14 @@ while [ "$#" -gt 0 ]; do
         specialisation="$1"
         shift 1
         ;;
+      --image-variant)
+        if [ -z "$1" ]; then
+            log "$0: ‘--image-variant’ requires an argument"
+            exit 1
+        fi
+        imageVariant="$1"
+        shift 1
+        ;;
       --build-host)
         buildHost="$1"
         shift 1
@@ -819,6 +828,43 @@ if [ -z "$rollback" ]; then
         else
             pathToConfig="$(nixFlakeBuild "$flake#$flakeAttr.config.system.build.vmWithBootLoader" "${extraBuildFlags[@]}" "${lockFlags[@]}")"
         fi
+    elif [ "$action" = build-image ]; then
+        if [[ -z $buildingAttribute ]]; then
+            variants="$(
+                runCmd nix-instantiate --eval --strict --json --expr \
+                "let
+                    value = import \"$(realpath $buildFile)\";
+                    set = if builtins.isFunction value then value {} else value;
+                in builtins.mapAttrs (n: v: v.passthru.filePath) set.${attr:+$attr.}config.system.build.images" \
+                "${extraBuildFlags[@]}"
+            )"
+        elif [[ -z $flake ]]; then
+            variants="$(
+                runCmd nix-instantiate --eval --strict --json --expr \
+                "with import <nixpkgs/nixos> {}; builtins.mapAttrs (n: v: v.passthru.filePath) config.system.build.images" \
+                "${extraBuildFlags[@]}"
+            )"
+        else
+            variants="$(
+                runCmd nix "${flakeFlags[@]}" eval --json \
+                "$flake#$flakeAttr.config.system.build.images" \
+                --apply "builtins.mapAttrs (n: v: v.passthru.filePath)" "${evalArgs[@]}" "${extraBuildFlags[@]}"
+            )"
+        fi
+        if ! echo "$variants" | jq -e --arg variant "$imageVariant" "keys | any(. == \$variant)" > /dev/null; then
+            echo -e "Please specify one of the following supported image variants via --image-variant:\n" >&2
+            echo "$variants" | jq -r '. | keys | join ("\n")'
+            exit 1
+        fi
+        imageName="$(echo "$variants" | jq -r --arg variant "$imageVariant" ".[\$variant]")"
+
+        if [[ -z $buildingAttribute ]]; then
+            pathToConfig="$(nixBuild $buildFile -A "${attr:+$attr.}config.system.build.images.${imageVariant}" "${extraBuildFlags[@]}")"
+        elif [[ -z $flake ]]; then
+            pathToConfig="$(nixBuild '<nixpkgs/nixos>' -A config.system.build.images.${imageVariant} -k "${extraBuildFlags[@]}")"
+        else
+            pathToConfig="$(nixFlakeBuild "$flake#$flakeAttr.config.system.build.images.${imageVariant}" "${extraBuildFlags[@]}" "${lockFlags[@]}")"
+        fi
     else
         showSyntax
     fi
@@ -913,3 +959,8 @@ if [[ "$action" = build-vm || "$action" = build-vm-with-bootloader ]]; then
 Done.  The virtual machine can be started by running $(echo "${pathToConfig}/bin/"run-*-vm)
 EOF
 fi
+
+if [[ "$action" = build-image ]]; then
+    echo -n "Done.  The disk image can be found in " >&2
+    echo "${pathToConfig}/${imageName}"
+fi