From 094740a2c798fddc488840ad9a0a9a60161a0c4a Mon Sep 17 00:00:00 2001 From: Adrian Vladu Date: Fri, 5 Apr 2024 16:19:38 +0300 Subject: [PATCH] docs: hyper-v: add documentation * added basic installation requirements * added powershell script to create a Gen 1 and Gen 2 VM * added powershell script to create and use a configdrive * added a butane config with advanced features like auto-login, password set and TPM cryptenroll Signed-off-by: Adrian Vladu --- content/docs/latest/_index.md | 2 + content/docs/latest/installing/vms/hyper-v.md | 160 ++++++++++++++++++ 2 files changed, 162 insertions(+) create mode 100644 content/docs/latest/installing/vms/hyper-v.md diff --git a/content/docs/latest/_index.md b/content/docs/latest/_index.md index 3480b627..b59b84bc 100644 --- a/content/docs/latest/_index.md +++ b/content/docs/latest/_index.md @@ -39,6 +39,7 @@ purposes. You can use any of the following options. * [libVirt][libvirt] * [VirtualBox][virtualbox] (not officially supported) * [Vagrant][vagrant] (not officially supported) + * [Hyper-V][hyper-v] (not officially supported) #### Bare Metal You can install Flatcar on bare metal machines in different ways: using ISO @@ -191,6 +192,7 @@ Flatcar tutorial to deep dive into some Flatcar fundamental concepts. [libvirt]: installing/vms/libvirt [virtualbox]: installing/vms/virtualbox [vagrant]: installing/vms/vagrant +[hyper-v]: installing/vms/hyper-v [vmware]: installing/cloud/vmware [cluster-architectures]: setup/clusters/architectures [update-strategies]: setup/releases/update-strategies diff --git a/content/docs/latest/installing/vms/hyper-v.md b/content/docs/latest/installing/vms/hyper-v.md new file mode 100644 index 00000000..4080b6c3 --- /dev/null +++ b/content/docs/latest/installing/vms/hyper-v.md @@ -0,0 +1,160 @@ +--- +title: Running Flatcar Container Linux on Hyper-V +linktitle: Running on Hyper-V +weight: 30 +--- + +_While we always welcome community contributions and fixes, please note that Hyper-V is not an officially supported platform at this time because the release tests don't run for it. (See the [platform overview](/#installing-flatcar).)_ + +These instructions will walk you through running Flatcar Container Linux on Hyper-V. + +## Choose a channel + +Flatcar Container Linux is designed to be updated automatically with different schedules per channel. You can [disable this feature][update-strategies], although we don't recommend it. Read the [release notes][release-notes] for specific features and bug fixes. + +Hyper-V images are created only for AMD64 and come in two disk formats, VHD for Hyper-V VM Generation 1 and VHDX for both Hyper-V Generation 1 and 2 VMs. + +Note: Hyper-V Generation 2 virtual machines need to have secure boot disabled, as the VHDX images are not signed. + +How to download a VHDX image file: + +```powershell +# VHDX image is available for download from the current Alpha onwards +curl.exe --progress-bar -LO "https://bincache.flatcar-linux.net/images/amd64/3937.0.0+nightly-20240411-2100/flatcar_production_hyperv_vhdx_image.vhdx.zip" +Expand-Archive flatcar_production_hyperv_vhdx_image.vhdx.zip . +``` + +## Deploying a new virtual machine on Hyper-V using Ignition with autologin and TPM LUKS2 root partition encryption + +```powershell +$vmName = "my_flatcar_01" +$vmDisk = "flatcar_production_hyperv_vhdx_image.vhdx" + +New-VM -Name $vmName -MemoryStartupBytes 2GB ` + -BootDevice VHD -SwitchName "Default Switch" -VHDPath $vmDisk -Generation 2 +Set-VMFirmware -EnableSecureBoot "Off" -VMName $vmName + +# The core user password is set to foo + +$ignitionMetadata = @' +variant: flatcar +version: 1.0.0 +kernel_arguments: + should_exist: + - flatcar.autologin +passwd: + users: + - name: core + password_hash: $6$sn3ZSJJJln5JkAZb$VDTKzLpCyjlEe7Kh0DKjOnEawkkOoi0tOKVbcCv0FIWSf3u9Y1p1I5YdJJ5L8uDmmMvO2CBlmJZNdxFuekjjE1 +storage: + luks: + - name: rootencrypted + wipe_volume: true + device: "/dev/disk/by-partlabel/ROOT" + filesystems: + - device: /dev/mapper/rootencrypted + format: ext4 + label: ROOT +systemd: + units: + - name: cryptenroll-helper.service + enabled: true + contents: | + [Unit] + ConditionFirstBoot=true + OnFailure=emergency.target + OnFailureJobMode=isolate + [Service] + Type=oneshot + RemainAfterExit=yes + ExecStart=systemd-cryptenroll --tpm2-device=auto --unlock-key-file=/etc/luks/rootencrypted --wipe-slot=0 --tpm2-pcrs= /dev/disk/by-partlabel/ROOT + ExecStart=rm /etc/luks/rootencrypted + [Install] + WantedBy=multi-user.target +'@ +echo $ignitionMetadata > ignition.yaml + +# download the butane binary to create the raw ignition metadata +# https://github.com/coreos/butane/releases +curl.exe -sLO "https://github.com/coreos/butane/releases/download/v0.20.0/butane-x86_64-pc-windows-gnu.exe" + +# transform the Ignition metadata from Butane format to Ignition raw +.\butane-x86_64-pc-windows-gnu.exe ".\ignition.yaml" -o ".\ignition.json" + +# download the tool kvpctl to set the Ignition metadata from +# https://github.com/containers/libhvee/releases +# See: https://docs.fedoraproject.org/en-US/fedora-coreos/provisioning-hyperv/ +curl.exe -sLO "https://github.com/containers/libhvee/releases/download/v0.7.1/kvpctl-amd64.exe.zip" +Expand-Archive kvpctl-amd64.exe.zip . +.\kvpctl-amd64.exe "$vmName" add-ign ignition.json + +Set-VMKeyProtector -VMName $vmName -NewLocalKeyProtector +Enable-VMTPM -VMName $vmName + +Start-VM -Name $vmName +``` + +A more complete TPM2 example can be found at [security-luks][security-luks]. + +At boot time, the Flatcar Container Linux will detect that the volume size has changed and will resize the filesystem accordingly. + +Currently, there is no support for the Hyper-V guest to hypervisor communication, useful for virtual machine IP retrieval. + +## Creating a config-drive for first boot configuration (Ignition alternative) + +While Ignition is not supported on a config-drive, you can provide a Cloud-config following the coreos-cloudinit subset. + +The cloud-config can be specified by attaching a [config-drive](https://github.com/flatcar/coreos-cloudinit/blob/master/Documentation/config-drive.md) with the label `config-2`. This is commonly done through whatever interface allows for attaching CD-ROMs or new drives. + +Note that the config-drive standard was originally an OpenStack feature, which is why you'll see strings containing `openstack`. This filepath needs to be retained, although Flatcar Container Linux supports config-drive on all platforms. + +For more information on customization that can be done with cloud-config, head on over to the [cloud-config guide](https://github.com/flatcar/coreos-cloudinit/blob/master/Documentation/cloud-config.md). + +You need a config-drive to configure at least one SSH key to access the virtual machine. If you are in hurry, you can create a basic config-drive on Windows with following steps: + +```powershell +#ps1 +# mkisofs can be downloaded from https://github.com/cloudbase/cloudbase-init-test-resources/tree/master/bin +curl.exe -sLO "https://github.com/cloudbase/cloudbase-init-test-resources/blob/master/bin/mkisofs.exe" + +# create an Openstack config drive folder structure +mkdir config-drive-metadata/openstack/latest +echo '{"hostname": "my_flatcar_01.local", "name": "my_flatcar_01", "public_keys": {"userkey": "INSERT_HERE_PUBLIC_SSH_KEY"}' > config-drive-metadata/openstack/latest/meta_data.json + +# create the config drive +& "mkisofs.exe" -o "config-drive.iso" -ignore-error -ldots -allow-lowercase -allow-multidot -l -publisher "cbsl" -quiet -J -r -V "config-2" "config-drive-metadata" +``` + +An ISO file named `config-drive.iso` will be created that will configure a virtual machine to accept your SSH key and set its name to my_flatcar_01. + +## Deploying a new virtual machine on Hyper-V using config drive + +```powershell +$vmName = "my_flatcar_01" +$vmDisk = "flatcar_production_hyperv_vhdx_image.vhdx" + +# For Generation 1 VM +New-VM -Name $vmName -MemoryStartupBytes 2GB ` + -BootDevice VHD -SwitchName "Default Switch" -VHDPath $vmDisk -Generation 1 + +# For Generation 2 VM +New-VM -Name $vmName -MemoryStartupBytes 2GB ` + -BootDevice VHD -SwitchName "Default Switch" -VHDPath $vmDisk -Generation 2 +# Generation 2 VM needs to have secure boot disabled, as the images are not signed +Set-VMFirmware -EnableSecureBoot "Off" -VMName $vmName + +# Now, add the config-drive file as DvdDrive +Add-VMDvdDrive -VMName $vmName -Path "config-drive.iso" + +Start-VM -Name $vmName +``` + +## Using Flatcar Container Linux + +Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. + +[update-strategies]: ../../setup/releases/update-strategies +[security-luks]: ../../setup/security/luks +[release-notes]: https://flatcar-linux.org/releases +[quickstart]: ../ +[doc-index]: ../../