nixos/azure: improve documentation

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

@@ -30,6 +30,8 @@
 
 - Support for CUDA 10 has been dropped, as announced in the 24.11 release notes.
 
+- `virtualisation/azure-common.nix`'s filesystem and grub configurations have been moved to `virtualisation/azure-image.nix`. This makes `azure-common.nix` more generic so it could be used for users who generate Azure image using other methods (e.g. nixos-generators and disko). For existing users depending on these configurations, please also import `azure-image.nix`.
+
 - `zammad` has had its support for MySQL removed, since it was never working correctly and is now deprecated upstream. Check the [migration guide](https://docs.zammad.org/en/latest/appendix/migrate-to-postgresql.html) for how to convert your database to PostgreSQL.
 
 - `kanata` was updated to v1.7.0, which introduces several breaking changes.

nixos/modules/virtualisation/azure-common.nix

@@ -26,26 +26,35 @@ in
 
   config = {
     virtualisation.azure.agent.enable = true;
+
+    # Enable cloud-init by default for waagent.
+    # Otherwise waagent would try manage networking using ifupdown,
+    # which is currently not availeble in nixpkgs.
     services.cloud-init.enable = true;
     services.cloud-init.network.enable = true;
     systemd.services.cloud-config.serviceConfig.Restart = "on-failure";
 
+    # Ensure kernel outputs to ttyS0 (Azure Serial Console),
+    # and reboot machine upon fatal boot issues
     boot.kernelParams = [
       "console=ttyS0"
       "earlyprintk=ttyS0"
       "rootdelay=300"
       "panic=1"
       "boot.panic_on_fail"
     ];
+
+    # Load Hyper-V kernel modules
     boot.initrd.kernelModules = [
       "hv_vmbus"
       "hv_netvsc"
       "hv_utils"
       "hv_storvsc"
     ];
-    boot.initrd.availableKernelModules = lib.optionals cfg.acceleratedNetworking mlxDrivers;
 
-    # Accelerated networking
+    # Accelerated networking, configured following:
+    # https://learn.microsoft.com/en-us/azure/virtual-network/accelerated-networking-overview
+    boot.initrd.availableKernelModules = lib.optionals cfg.acceleratedNetworking mlxDrivers;
     systemd.network.networks."99-azure-unmanaged-devices.network" = lib.mkIf cfg.acceleratedNetworking {
       matchConfig.Driver = mlxDrivers;
       linkConfig.Unmanaged = "yes";

nixos/modules/virtualisation/azure-image.nix

@@ -71,12 +71,15 @@ in
   config = {
     system.build.azureImage = import ../../lib/make-disk-image.nix {
       name = "azure-image";
+
+      # Azure expects vhd format with fixed size,
+      # generating raw format and convert with subformat args afterwards
+      format = "raw";
       postVM = ''
         ${pkgs.vmTools.qemu}/bin/qemu-img convert -f raw -o subformat=fixed,force_size -O vpc $diskImage $out/disk.vhd
         rm $diskImage
       '';
       configFile = ./azure-config-user.nix;
-      format = "raw";
 
       bootSize = "${toString cfg.bootSize}M";
       partitionTableType = if (cfg.vmGeneration == "v2") then "efi" else "legacy";
@@ -91,8 +94,13 @@ in
       efiSupport = (cfg.vmGeneration == "v2");
       device = if efiSupport then "nodev" else "/dev/sda";
       efiInstallAsRemovable = efiSupport;
+      # Force grub to run in text mode and output to console
+      # by disabling font and splash image
       font = null;
       splashImage = null;
+      # For Gen 1 VM, configurate grub output to serial_com0.
+      # Not needed for Gen 2 VM wbere serial_com0 does not exist,
+      # and outputing to console is enough to make Azure Serial Console working
       extraConfig = lib.mkIf (!efiSupport) ''
         serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1
         terminal_input --append serial
@@ -103,6 +111,7 @@ in
     fileSystems = {
       "/" = {
         device = "/dev/disk/by-label/${cfg.label}";
+        inherit (cfg) label;
         fsType = "ext4";
         autoResize = true;
       };