Skip to content

Commit

Permalink
platforms.adoc: add VirtualBox documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@prestist
prestist committed Apr 1, 2022
1 parent 652ed8a commit 0bfd176
Show file tree
Hide file tree
Showing 2 changed files with 37 additions and 132 deletions.
1 change: 1 addition & 0 deletions modules/ROOT/pages/platforms.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ The currently supported platforms and their identifiers are listed below.
* Nutanix (`nutanix`): Hypervisor.
* OpenStack (cloud platform): `openstack`): Cloud platform. See xref:provisioning-openstack.adoc[Booting on OpenStack].
* QEMU (`qemu`): Hypervisor. See xref:provisioning-libvirt.adoc[Booting on libvirt]
* VirtualBox ('virtualbox'): Hypervisor. See xref:provisioning-virtualbox.adoc[Booting on VirtualBox].
* VMware ESXi (`vmware`): Hypervisor. See xref:provisioning-vmware.adoc[Booting on VMware]. Note that only https://kb.vmware.com/s/article/1003746[hardware version] 13 or later, vSphere ESXi hosts version 6.5 or later and vCenter host version 6.5 or later are supported.
* Vultr (`vultr`): Cloud platform. See xref:provisioning-vultr.adoc[Booting on Vultr].

Expand Down
168 changes: 36 additions & 132 deletions modules/ROOT/pages/provisioning-virtualbox.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,180 +4,84 @@ This guide shows how to provision new Fedora CoreOS (FCOS) nodes on the VirtualB

== Prerequisites

Before provisioning an FCOS machine, you must have an Ignition configuration file containing your customizations and host it somewhere (e.g. using `python3 -m http.server`, we will assume this option is used in the following examples). If you do not already have an Ignition file, see xref:producing-ign.adoc[Producing an Ignition File].
Before importing an FCOS machine, 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].

== Setting up a new VM
=== Downloading the OVA

You can set up a VirtualBox virtual machine through the GUI or via the https://www.virtualbox.org/manual/UserManual.html#vboxmanage[`vboxmanage` CLI]. Below is a shell script that does most of what the graphical wizard will do. Note that it is tailored to the installation from live ISO or raw disk image as outlined in the following sections.

NOTE: Please be aware that for now there is no dedicated Fedora CoreOS image available for VirtualBox and the installation instructions provided are essentially xref:bare-metal.adoc[bare metal instructions]. A dedicated image may be provided at a later time. Please check the GitHub issues https://github.com/coreos/fedora-coreos-tracker/issues/73[#73] and https://github.com/coreos/fedora-coreos-tracker/issues/144[#144] for more details.

We will rely on the VirtualBox-provided NAT gateway to access the hosts' loopback interface on `10.0.2.2`. Check the https://www.virtualbox.org/manual/UserManual.html#network_nat[VirtualBox User Manual] for more details.
Fedora CoreOS is designed to be updated automatically, with different schedules per stream.
Once you have picked the relevant stream, you can download the latest OVA:

[source, bash]
----
VM_NAME='fcos-node01'
VM_DISK=$(realpath ~/VirtualBox\ VMs/${VM_NAME})/${VM_NAME}.vdi
vboxmanage createvm --name "${VM_NAME}" --ostype Fedora_64 --register
# Set hardware settings for the VM, including recommended graphics controller
vboxmanage modifyvm "${VM_NAME}" --memory 4096 --cpus 2 --vram 20 --graphicscontroller vmsvga --rtcuseutc on
# Add a storage controller for hard disks
vboxmanage storagectl "${VM_NAME}" --name SATA --add sata --controller IntelAhci --portcount 30 --bootable on
----

WARNING: VirtualBox and by extension `vboxmanage` always expect absolute file paths when specifying locations.
STREAM="stable"
Make sure to create a port forwarding rule that allows access to the guest's SSH Port with the https://www.virtualbox.org/manual/UserManual.html#networkingmodes[default NAT setting] using e.g. `localhost:2222` as target address:
[source, bash]
----
vboxmanage modifyvm "${VM_NAME}" --natpf1 "guestssh,tcp,,2222,,22"
mkdir ova-templates
coreos-installer download -s "${STREAM}" -p virtualbox -f ova -C ./ova-templates/
----

The virtual machine is now ready and FCOS can be installed.
Alternatively, OVA images can be manually downloaded from the https://getfedora.org/coreos/download/[download page].

== Installing from live ISO
== Booting a new VM on VirtualBox

To install FCOS into a VirtualBox virtual machine using the live ISO, follow these steps:
This section shows how to use VirtualBox to configure and run VMs from thee CLI. Alternatively the graphical UI can be used as well.

- Download the latest ISO image from the https://getfedora.org/coreos/download?tab=metal_virtualized&stream=stable[download page] or with podman (see https://coreos.github.io/coreos-installer/cmd/download/[documentation] for options):
[source, bash]
----
podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \
quay.io/coreos/coreos-installer:release download -f iso
----
=== Importing the OVA

- Create a sufficiently large disk and attach it to the previously created VM:
You can set up a VirtualBox virtual machine through the GUI or via the https://www.virtualbox.org/manual/UserManual.html#vboxmanage[`vboxmanage` CLI]. Below is a VBoxManage CMD that imports the downloaded OVA. .
[source, bash]
----
vboxmanage createmedium --filename "${VM_DISK}" --size 10240 --format VDI
vboxmanage storageattach "${VM_NAME}" --storagectl SATA --type hdd --port 0 --device 0 --medium "${VM_DISK}"
VBoxManage import /path/to/file.ova
----

[NOTE]
====
*Fedora CoreOS requires the root filesystem to be at least 8 GiB.* For practical reasons, disk images for some platforms ship with a smaller root filesystem, which by default automatically expands to fill all available disk space. If you add additional partitions after the root filesystem, you must make sure to explicitly resize the root partition as shown so that it is at least 8 GiB.
Currently, if the root filesystem is smaller than 8 GiB, a warning is emitted on login. Starting from June 2021, if the root filesystem is smaller than 8 GiB and is followed by another partition, Fedora CoreOS will refuse to boot. For more details, see https://github.com/coreos/fedora-coreos-tracker/issues/586[this bug].
====

- Attach a DVD drive and the live ISO to the VM:

[source,bash,subs="attributes"]
----
FCOS_DISK=$(realpath ~/Downloads/fedora-coreos-{stable-version}-live.x86_64.iso)
vboxmanage storagectl "$\{VM_NAME}" --name IDE --add ide --controller PIIX4 --hostiocache on --portcount 2 --bootable on
vboxmanage storageattach "$\{VM_NAME}" --storagectl IDE --type dvddrive --port 1 --device 0 --medium "$\{FCOS_DISK}"
----

You can now boot the target system you have configured. The ISO is capable of bringing up a fully functioning FCOS system purely from memory (i.e. without using any disk storage). Once booted, you will have access to a bash command prompt.

You can now run `coreos-installer` inside the VM:
Once imported the network adapter is set to NAT. You should switch to bridged.
First determine which adapter on your host you would like to use.
You can list out our adapters by the following CMD:
[source, bash]
----
sudo coreos-installer install /dev/sda \
--insecure-ignition --ignition-url http://10.0.2.2:8000/example.ign
ip a
----

TIP: Check out `coreos-installer install --help` for more options on how to install Fedora CoreOS.

Once the installation is complete, you have to remove the live ISO after shutting down (`sudo shutdown -h now`) the VM. Once the ISO is removed, you can start the VM anew. The actual first boot process begins now. It is at this time that Ignition ingests the configuration file and provisions the system as specified.

Select the appropriate adapter to use, and run the following CMD (replacing the vmname and adaptername respectively):
[source, bash]
----
vboxmanage storageattach "${VM_NAME}" --storagectl IDE --type dvddrive --port 1 --device 0 --medium emptydrive
vboxmanage startvm "${VM_NAME}" --type headless
# Once the VM is available, you can log in:
ssh core@localhost -p 2222
vboxmanage modifyvm vmname ==nic1 bridged ==bridgeadapter1 adaptername
----
== Installing from raw bare metal image

WARNING: The steps below are provided for advanced users, may unexpectedly break in various places with newer Fedora CoreOS images, and require a Unix environment to work. If you encounter issues consider using the xref:_installing_from_live_iso[live ISO instructions] instead.

To install FCOS into a VirtualBox virtual machine using the raw disk image, follow these steps:

- Download the latest raw image from the https://getfedora.org/coreos/download?tab=metal_virtualized&stream=stable[download page] or with podman (see https://coreos.github.io/coreos-installer/cmd/download/[documentation] for options):
Alternatively, if you want to use NAT then create a port forwarding rule that allows access to the guest's SSH Port with the https://www.virtualbox.org/manual/UserManual.html#networkingmodes[default NAT setting] using e.g. `localhost:2222` as target address:
Then run the following CMD.
[source, bash]
----
podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \
quay.io/coreos/coreos-installer:release download -f raw
----

Before the installation can begin you have to convert the raw disk image to a VirtualBox compatible one:
[source,bash,subs="attributes"]
----
FCOS_DISK=$(realpath ~/Downloads/fedora-coreos-{stable-version}-metal.x86_64.raw.xz)
UNPACKED_DISK=$(realpath ~/Downloads/fedora-coreos-{stable-version}-metal.x86_64.raw)
# Unpack the raw disk image
unxz "$\{FCOS_DISK}"
vboxmanage modifyvm "${VM_NAME}" --natpf1 "guestssh,tcp,,2222,,22"
----

[NOTE]
====
If you want to supply the Ignition configuration file URL statically, you can modify the raw disk before converting it to a VirtualBox disk image.

To correctly mount the boot partition you have to find out the start point of it and the disk's sector size. Multiply the two values to calculate the mount `offset`.
[source, bash]
----
TMP_FCOS_BOOT_VOLUME=$(realpath /tmp/fcos_boot_volume)
mkdir "${TMP_FCOS_BOOT_VOLUME}"
=== Setting the Ignition configuration

fdisk -l "${UNPACKED_DISK}"
sudo mount -o loop,offset="${OFFSET}" "${UNPACKED_DISK}" "${TMP_FCOS_BOOT_VOLUME}"
----
This is done by using the guest property on the virtual machine. The guest property does have come character limits to consider and they are as follows.

On macOS you have to replace `fdisk -l "$\{UNPACKED_DISK}"` with `hdiutil imageinfo -imagekey diskimage-class=CRawDiskImage "$\{UNPACKED_DISK}"`. Mounting the partition requires https://osxfuse.github.io[macFUSE] with an https://github.com/osxfuse/osxfuse/wiki/Ext[ext filesystem extension].
The boot config you are looking for is located in `/loader/entries/ostree-1-fedora-coreos.conf` on the boot partition you just mounted. The file contains a line containing the string `ignition.platform.id=metal $ignition_firstboot` – add `ignition.config.url=http://10.0.2.2:8000/example.ign` after the first boot parameter, save your changes and unmount the disk.
[source, bash]
----
sudo vi "${TMP_FCOS_BOOT_VOLUME}/loader/entries/ostree-1-fedora-coreos.conf"
# ...
sudo umount "${TMP_FCOS_BOOT_VOLUME}"
----
====

Continue with converting the raw disk image into a VirtualBox disk image:
[source, bash]
----
vboxmanage convertfromraw "${UNPACKED_DISK}" "${VM_DISK}" --format VDI --variant Standard
# Resize the disk to match FCOS requirements
vboxmanage modifymedium disk "${VM_DISK}" --resize 10240
# Add the converted disk to the VM
vboxmanage storageattach "${VM_NAME}" --storagectl SATA --type hdd --port 0 --device 0 --medium "${VM_DISK}"
----

TIP: You can use https://www.virtualbox.org/manual/UserManual.html#vboxmanage-snapshot[snapshots] and https://www.virtualbox.org/manual/UserManual.html#vboxmanage-clonevm[cloning] in case you want to reuse the VM as an empty baseline before applying an Ignition configuration to it.
| OS | Limit |
| - | - |
| Linux | 128 KiB |
| macOS | 256 KiB |

[NOTE]
====
*Fedora CoreOS requires the root filesystem to be at least 8 GiB.* For practical reasons, disk images for some platforms ship with a smaller root filesystem, which by default automatically expands to fill all available disk space. If you add additional partitions after the root filesystem, you must make sure to explicitly resize the root partition as shown so that it is at least 8 GiB.
Currently, if the root filesystem is smaller than 8 GiB, a warning is emitted on login. Starting from June 2021, if the root filesystem is smaller than 8 GiB and is followed by another partition, Fedora CoreOS will refuse to boot. For more details, see https://github.com/coreos/fedora-coreos-tracker/issues/586[this bug].
If your Ignition configuration is to large then you will need to follow the appropriate steps for doing a config merge.
You can read more about this process here https://docs.fedoraproject.org/en-US/fedora-coreos/remote-ign/
====

You can now boot the target system you previously configured.

If you decided to supply the Ignition configuration URL dynamically or want to override your static URL, press `e` when the GRUB menu shows up. This allows you to edit the current boot entry and specify the remote Ignition configuration URL to use:
[source, bash]
----
load_video
#...
linux ($root)/ostree/fedora-coros- #...
ignition.firstboot ignition.config.url=http://10.0.2.2:8000/example.ign
initrd ($root)/ostree/fedora-coreos- #...
IGN_PATH="SetWithABSPathToIGNConfig"
VM_NAME="Fedora CoreOS"
VBoxManage guestproperty set ${VM_NAME} /Ignition/Config "$(cat ${IGN_PATH}})"
----

The actual first boot process begins now. It is at this time that Ignition ingests the configuration file and provisions the system as specified.

Once the VM finished booting, you can log in from your host:
[source, bash]
----
ssh core@localhost -p 2222
----
You can now boot the target system you have configured.

== Troubleshooting First-boot Problems

Expand All @@ -193,4 +97,4 @@ VM_LOG=$(realpath .)/${VM_NAME}.log
vboxmanage modifyvm "${VM_NAME}" --uart1 '0x3F8' '4'
vboxmanage modifyvm "${VM_NAME}" --uartmode1 file "${VM_LOG}"
----
----

0 comments on commit 0bfd176

Please sign in to comment.