Provisioning: Add Hetzner

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]

modules/ROOT/pages/provisioning-hetzner.adoc

@@ -0,0 +1,161 @@
+= Provisioning Fedora CoreOS on Hetzner
+
+This guide shows how to provision new Fedora CoreOS (FCOS) nodes on Hetzner.
+Fedora CoreOS images are currently not published directly on Hetzner.
+Thus you must first download a Fedora CoreOS RAW disk image, then convert it to an Hetzner image and finally upload it to your Hetzner account as a snapshot 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 offer an optimized user experience right now.
+           See https://github.com/coreos/fedora-coreos-tracker/issues/1324[issue #1324] for more details.
+
+== 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].
+
+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 Hetzner custom image
+
+Fedora CoreOS is designed to be updated automatically, with different schedules per stream.
+
+. Once you have picked the relevant stream, find the corresponding QEMU image on the https://fedoraproject.org/coreos/download/?stream=stable#cloud_images[download page] and download it on your system.
+
+. 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: <source image> <dest image> <platform>"
+    echo ""
+    echo "Example:"
+    echo "./$(basename "${0}") fedora-coreos-40.20240616.3.0-{metal,heztner}.x86_64.raw heztner"
+    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
+
+cp --reflink=auto "${source}" "${dest}"
+guestfish -a "${dest}" <<EOF
+run
+mount /dev/sda3 /
+download /loader/entries/ostree-1.conf tmp.loader.entries.ostree-1.conf
+<! sed -i "s/ignition.platform.id=metal/ignition.platform.id=${platform}/" tmp.loader.entries.ostree-1.conf
+upload tmp.loader.entries.ostree-1.conf /loader/entries/ostree-1.conf
+EOF
+
+rm -v ./tmp.loader.entries.ostree-1.conf
+
+echo "Done"
+----
++
+. Convert the QEMU image to an Hetzner one:
++
+[source, bash]
+----
+source_image"fedora-coreos-qemu-image-name.qcow2"
+image_name="fcos-hetzner.qcow2"
+./covert-image.sh "${source_image}" "${image_name}" hetzner
+----
++
+. Compress the image using `bzip2`:
++
+[source, bash]
+----
+bzip2 --compress --keep "${image_name}"
+----
++
+. Upload the image somewhere publicly available over HTTPS and note down the URL:
++
+[source, bash]
+----
+image_url="https://examle.com/fedora-coreos-hetzner.raw.bz2"
+----
++
+. Use the `hcloud-upload-image` to create a snapshot out of your image:
++
+[source, bash]
+----
+hcloud-upload-image upload \
+    --architecture x86 \
+    --compression bz2 \
+    --image-url "${image_url}" \
+    --labels os=fedora-coreos,channel=stable \
+    --description "Fedora CoreOS (stable, x86_64)"
+----
++
+. Validate that you have a snapshot:
++
+[source, bash]
+----
+hcloud image list --type=snapshot --selector=os=fedora-coreos
+----
+
+=== Launching a server
+
+. If you don't already have an SSH key uploaded to Hetzner, you may upload one:
++
+.Example uploading an SSH key to Hetzner
+[source, bash]
+----
+ssh_pubkey="ssh-ed25519 ..."
+ssh_key_name="fedora-coreos-hetzner"
+hcloud ssh-key create --name "${ssh_key_name}" --public-key "${ssh_pubkey}"
+----
++
+. Launch a server. Your Ignition configuration can be passed to the VM as its user data, or you can skip passing user data if you just want SSH access. This provides an easy way to test out FCOS without first creating an Ignition config.
++
+.Example launching FCOS on Hetzner using an Ignition configuration file
+[source, bash]
+----
+image_id="$(hcloud image list \
+    --type=snapshot \
+    --selector=os=fedora-coreos \
+    --output json \
+    | jq -r '.[0].id')"
+ssh_key_name="fedora-coreos-hetzner" # See: hcloud ssh-key list
+datacenter="fsn1-dc14"               # See: hcloud datacenter list
+type="cx22"                          # See: hcloud server-type list
+name="fedora-coreos-test"
+ignition_config="./config.ign"
+hcloud server create \
+    --name "${name}" \
+    --type "${type}" \
+    --datacenter "${datacenter}" \
+    --image "${image_id}" \
+    --ssh-key "${ssh_key_name}" \
+    --user-data-from-file "${ignition_config}"
+----
++
+NOTE: While the Hetzner documentation mentions `cloud-init` and "cloud config", FCOS does not support cloud-init or the ability to run scripts from user-data.
+      It accepts only Ignition configuration files.
+
+. You now should be able to SSH into the instance using the associated IP address.
++
+.Example connecting
+[source, bash]
+----
+ssh core@"$(hcloud server ip "${name}")"
+----