diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9f1c8081..0a1212e5 100644 --- a/modules/ROOT/nav.adoc +++ b/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-hetzner.adoc[Booting on Hetzner] ** xref:provisioning-hyperv.adoc[Booting on Hyper-V] ** xref:provisioning-ibmcloud.adoc[Booting on IBM Cloud] ** xref:provisioning-kubevirt.adoc[Booting on KubeVirt] diff --git a/modules/ROOT/pages/provisioning-hetzner.adoc b/modules/ROOT/pages/provisioning-hetzner.adoc new file mode 100644 index 00000000..e92962cf --- /dev/null +++ b/modules/ROOT/pages/provisioning-hetzner.adoc @@ -0,0 +1,182 @@ += Provisioning Fedora CoreOS on Hetzner + +This guide shows how to provision new Fedora CoreOS (FCOS) nodes on Hetzner. +Fedora CoreOS is currently not available as an option in the operating system selection on Hetzner. +Fedora CoreOS images for Hetzner are currently not directly available for download either. +Thus you must first download a Fedora CoreOS RAW disk image, then convert it to an Hetzner image locally and finally create a snapshot from it in your Hetzner account using the https://github.com/apricote/hcloud-upload-image[hcloud-upload-image] tool. + +IMPORTANT: Support for Fedora CoreOS on Hetzner is considerer emerging, in that it does not yet offer an optimized user experience and relies on tools not officially supported by Hetzner. + See https://github.com/coreos/fedora-coreos-tracker/issues/1324[issue #1324] for more details. + +IMPORTANT: The https://github.com/apricote/hcloud-upload-image[hcloud-upload-image] tool is not an official Hetzner Cloud product and Hetzner Cloud does not provide support for it. + Alternatively, you can also use the official https://github.com/hetznercloud/packer-plugin-hcloud[packer-plugin-hcloud] to install the image via `coreos-installer`. + +IMPORTANT: In order to create a snapshot, the https://github.com/apricote/hcloud-upload-image[hcloud-upload-image] tool will provision a small server and boot it in rescue mode. + As this server is short lived, the cost should be very limited. + The resulting snapshots are charged per GB per month. + See https://docs.hetzner.com/cloud/servers/backups-snapshots/overview/[Backups/Snapshots] in the Hetzner Cloud documentation. + You may delete this snapshot once the server has been provisioned. + +== Prerequisites + +Before provisioning 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]. + +NOTE: Fedora CoreOS has a default `core` user that can be used to explore the OS. + If you want to use it, finalize its xref:authentication.adoc[configuration] by providing e.g. an SSH key. + +If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support] and only configure SSH keys. + +You also need to have access to a Hetzner account. +The examples below use the https://github.com/hetznercloud/cli[hcloud] command-line tool, the https://github.com/apricote/hcloud-upload-image[hcloud-upload-image] tool and https://stedolan.github.io/jq/[jq] as a command-line JSON processor. + +== Creating a snapshot + +Fedora CoreOS is designed to be updated automatically, with different schedules per stream. + +. Once you have picked the relevant stream, download the latest RAW image from the https://fedoraproject.org/coreos/download/?stream=stable#baremetal[download page] or with podman (see https://coreos.github.io/coreos-installer/cmd/download/[documentation] for options): ++ +[source, bash] +---- +arch="x86_64" # or aarch64 +podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \ + quay.io/coreos/coreos-installer:release download -s stable -p metal -f raw -a "${arch}" +---- ++ +Note this is just using `coreos-installer` as a tool to download the RAW disk image. ++ +NOTE: Both x86_64 and aarch64 architectures are supported on Hetzner. + +. Copy paste the following Bash script into a file name `convert-image.sh`: ++ +.QEMU to Hetzner image conversion script +[source, bash] +---- +#!/bin/bash + +set -euo pipefail + +if [[ ${#} -ne 3 ]]; then + echo "Usage: " + echo "" + echo "Example:" + echo "./$(basename "${0}") fedora-coreos-40.20240616.3.0-{metal,hetzner}.x86_64.raw hetzner" + exit 1 +fi + +source="${1}" +dest="${2}" +platform="${3}" + +if [[ ! -f "${source}" ]]; then + echo "Source image ${source} does not exists" + exit 1 +fi + +if [[ -f "${dest}" ]]; then + echo "Destination image ${dest} already exists" + exit 1 +fi + +if [[ -z "$(command -v guestfish)" ]]; then + echo "Could not find 'guestfish' command" + exit 1 +fi + +cp --reflink=auto "${source}" "${dest}" +guestfish -a "${dest}" <