From 040cef4c3170219d1e8588d85090abdcb2186721 Mon Sep 17 00:00:00 2001
From: codgician <15964984+codgician@users.noreply.github.com>
Date: Fri, 29 Nov 2024 10:18:18 +0800
Subject: [PATCH] nixos/azure: improve documentation

---
 nixos/doc/manual/release-notes/rl-2505.section.md |  2 ++
 nixos/modules/virtualisation/azure-common.nix     | 13 +++++++++++--
 nixos/modules/virtualisation/azure-image.nix      | 11 ++++++++++-
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/nixos/doc/manual/release-notes/rl-2505.section.md b/nixos/doc/manual/release-notes/rl-2505.section.md
index 83ec8b2de680f5..7626c56b81688c 100644
--- a/nixos/doc/manual/release-notes/rl-2505.section.md
+++ b/nixos/doc/manual/release-notes/rl-2505.section.md
@@ -37,6 +37,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.
diff --git a/nixos/modules/virtualisation/azure-common.nix b/nixos/modules/virtualisation/azure-common.nix
index 205f67a60d962a..b12cf6440bdaf5 100644
--- a/nixos/modules/virtualisation/azure-common.nix
+++ b/nixos/modules/virtualisation/azure-common.nix
@@ -26,10 +26,16 @@ 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"
@@ -37,15 +43,18 @@ in
       "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";
diff --git a/nixos/modules/virtualisation/azure-image.nix b/nixos/modules/virtualisation/azure-image.nix
index 4ae8849d500477..252381d0f198bc 100644
--- a/nixos/modules/virtualisation/azure-image.nix
+++ b/nixos/modules/virtualisation/azure-image.nix
@@ -76,12 +76,15 @@ in
     system.build.azureImage = import ../../lib/make-disk-image.nix {
       name = "azure-image";
       inherit (config.image) baseName;
+
+      # 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/${config.image.fileName}
         rm $diskImage
       '';
       configFile = ./azure-config-user.nix;
-      format = "raw";
 
       bootSize = "${toString cfg.bootSize}M";
       partitionTableType = if (cfg.vmGeneration == "v2") then "efi" else "legacy";
@@ -96,8 +99,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
@@ -108,6 +116,7 @@ in
     fileSystems = {
       "/" = {
         device = "/dev/disk/by-label/${cfg.label}";
+        inherit (cfg) label;
         fsType = "ext4";
         autoResize = true;
       };