Add documentation for Microsoft Hyper-V

Add instructions on how to boot Fedora CoreOS using the Microsoft Hyper-V
hypervisor.  The instructions cover a basic how-to for setting up the VM
as well as specific information needed for Ignition to work properly.

See: coreos/fedora-coreos-tracker#1424

Co-authored-by: Nikolas Grottendieck <[email protected]>
Co-authored-by: Benjamin Gilbert <[email protected]>

modules/ROOT/nav.adoc

@@ -9,6 +9,7 @@
 ** xref:provisioning-digitalocean.adoc[Booting on DigitalOcean]
 ** xref:provisioning-exoscale.adoc[Booting on Exoscale]
 ** xref:provisioning-gcp.adoc[Booting on GCP]
+** xref:provisioning-hyperv.adoc[Booting on Hyper-V]
 ** xref:provisioning-ibmcloud.adoc[Booting on IBM Cloud]
 ** xref:provisioning-kubevirt.adoc[Booting on KubeVirt]
 ** xref:provisioning-libvirt.adoc[Booting on libvirt]

modules/ROOT/pages/provisioning-hyperv.adoc

@@ -0,0 +1,106 @@
+= Provisioning Fedora CoreOS on Microsoft Hyper-V
+
+This guide shows how to provision new Fedora CoreOS (FCOS) nodes on Microsoft's Hyper-V.
+
+== Prerequisites
+
+You must have an Ignition configuration file containing your customizations. If you do not have one, see xref:producing-ign.adoc[Producing an Ignition File].
+
+You will also need a small utility from https://github.com/containers/libhvee[libhvee] called `kvpctl`. It attaches your Ignition config to your virtual machine. Precompiled binaries can be found on the project's https://github.com/containers/libhvee/releases[releases page].
+
+=== Downloading the disk image
+
+Hyper-V disk images can be manually downloaded from the https://fedoraproject.org/coreos/download/[download page]. Be sure to decompress the image after downloading.
+
+== Booting a new VM on Microsoft Hyper-V
+
+=== Creating a virtual machine
+
+There are numerous ways to create a virtual machine in Hyper-V. This approach uses the Hyper-V Manager and its New Virtual Machine wizard. Once you have Hyper-V Manager running, right-click on _New_ as seen in the following image.
+
+image::new_hyperv.png[Hyper-V Manager]
+
+This will launch the _New Virtual Machine Wizard_. You can follow the guided wizard but take note of the following two exceptions.
+
+==== Configuring networking
+
+When asked about the networking in the _New Virtual Machine Wizard_, be sure set up networking or your virtual machine will not be able to communicate with anything. It is sufficient to select the _Default_ Networking option.
+
+==== Configuring the Fedora CoreOS image as the disk
+
+You need to assign the disk image you downloaded earlier as the virtual machine's primary disk. This is not the default setting. You must click _Use an existing virtual disk_ and then specify the location of the image you downloaded earlier. See the image below for an example.
+
+image::hyperv-disk.png[Hyper-V Virtual Machine Disk Wizard]
+
+=== Setting the Ignition config
+
+Once your virtual machine is defined, do not start it. Be sure to complete the following section before starting your virtual machine. When first booting Fedora CoreOS, you need to have an Ignition config which is used to set up and configure the operating system.
+
+For the Hyper-V platform, Ignition will read its configuration file from the Hyper-V hypervisor in parts and then reassemble it. Before this can occur, you can use `kvpctl` and its _add-ign_ subcommand to split your Ignition file and assign it to the virtual machine. The syntax for the command is as follows:
+
+[source, powershell]
+----
+.\kvpctl.exe <name_of_vm> add-ign <path_to_ign_file> <ignition_config_prefix>
+----
+
+When Ignition is run on first boot, it will look for a pre-defined key name and reassemble the Ignition config. The pre-defined key name is *ignition.config.*. Be sure to note the trailing `.` on the prefix key name.
+
+For example:
+
+[source, powershell]
+----
+.\kvpctl.exe podman-machine-default add-ign C:\Users\joe\myvm.ign ignition.config.
+added key: ignition.config.0
+added key: ignition.config.1
+added key: ignition.config.2
+added key: ignition.config.3
+added key: ignition.config.4
+added key: ignition.config.5
+added key: ignition.config.6
+----
+
+
+=== Starting the VM
+
+Before starting the VM, be certain you have completed the step xref:_setting_the_ignition_config[Setting the Ignition config].
+
+There are several ways to start a virtual machine depending on the context of the Hyper-V Manager graphical interface. To start a virtual machine, for example, you can right-click on the virtual machine and select _Start_.
+
+=== Viewing the key-value pairs assigned to your virtual machine
+
+You can view the key-value pairs that are assigned to your machine with `kvpctl` and its _get_ subcommand. You may only get key-value pairs when the virtual machine is running.
+
+[source, powershell]
+----
+.\kvpctl.exe <name_of_vm> get
+----
+
+For example:
+
+[source, console]
+----
+> .\kvpctl.exe myvm get
+ignition.config.3 = th":"/etc/containers/registries.conf..."
+ignition.config.4 = ,"contents":{"source":"data:,makeste..."
+ignition.config.5 = nabled":false,"mask":true,"name":"do..."
+ignition.config.6 = service\n\n[Service]\nExecStart=/usr..."
+ignition.config.0 = {"ignition":{"config":{"replace":{"v..."
+ignition.config.1 = default.target.wants","user":{"name"..."
+ignition.config.2 = "user":{"name":"root"},"contents":{"..."
+----
+
+=== Removing the Ignition config
+
+When removing your virtual machine, you should also remove the keys you added for your virtual machine. This can also be done with the `kvpctl` utility. You can remove keys while the virtual is running or stopped.
+
+[source, powershell]
+----
+.\kvpctl.exe <name_of_vm> rm [ignition_key_names]
+----
+
+For example:
+
+[source, powershell]
+----
+.\kvpctl.exe podman-machine-default rm ignition.config.0 ignition.config.1 ignition.config.2 ignition.config.3 ignition.config.4 ignition.config.5 ignition.config.6
+----