diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e3ae28b8..d09dabb5 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-applehv.adoc[Booting on macOS] diff --git a/modules/ROOT/pages/provisioning-hetzner.adoc b/modules/ROOT/pages/provisioning-hetzner.adoc new file mode 100644 index 00000000..21cd3bfb --- /dev/null +++ b/modules/ROOT/pages/provisioning-hetzner.adoc @@ -0,0 +1,122 @@ += 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. +Thus you must first download the Fedora CoreOS disk image for Hetzner, then create a snapshot from it in your Hetzner account using the https://github.com/apricote/hcloud-upload-image[hcloud-upload-image] tool, and finally create your servers from this snapshot. + +IMPORTANT: Support for Fedora CoreOS on Hetzner is considered 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. + +== Downloading an Hetzner image + +Fedora CoreOS is designed to be updated automatically, with different schedules per stream. Once you have picked the relevant stream, download and verify the latest Hetzner image: + +[source, bash] +---- +ARCH="x86_64" # or "aarch64" +STREAM="stable" # or "testing", "next" +coreos-installer download -s "$STREAM" -p hetzner -a "$ARCH" -f raw.xz +---- + +NOTE: Both x86_64 and aarch64 architectures are supported on Hetzner. + +Alternatively, you can manually download an Hetzner image from the https://fedoraproject.org/coreos/download/?stream=stable[download page]. +Verify the download, following the instructions on that page. + +== Creating a snapshot + +. Use the `hcloud-upload-image` to create a snapshot from this image: ++ +[source, bash] +---- +IMAGE_NAME="fedora-coreos-41.20250213.0-hetzner.x86_64.raw.xz" +export HCLOUD_TOKEN="" +STREAM="stable" # or "testing", "next" +HETZNER_ARCH="x86" # or "arm" + +hcloud-upload-image upload \ + --architecture "$HETZNER_ARCH" \ + --compression xz \ + --image-path "$IMAGE_NAME" \ + --labels os=fedora-coreos,channel="$STREAM" \ + --description "Fedora CoreOS ($STREAM, $ARCH)" +---- ++ +NOTE: The `hcloud-upload-image` tool uses different names for architectures (`x86_64` -> `x86`, `aarch64` -> `arm`). ++ +. Wait for the process to complete and 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 and SSH key +[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 and website mentions `cloud-init` and "cloud config", FCOS does not support cloud-init. + 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")" +----