Skip to content

Commit

Permalink
Provisioning: Add Hetzner
Browse files Browse the repository at this point in the history
Initial documentation to setup FCOS on Hetzner.

Inspired by: https://www.flatcar.org/docs/latest/installing/cloud/hetzner/
See: coreos/fedora-coreos-tracker#1324
  • Loading branch information
travier committed Jul 17, 2024
1 parent ab098f7 commit 964c6b5
Show file tree
Hide file tree
Showing 2 changed files with 183 additions and 0 deletions.
1 change: 1 addition & 0 deletions modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
182 changes: 182 additions & 0 deletions modules/ROOT/pages/provisioning-hetzner.adoc
Original file line number Diff line number Diff line change
@@ -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: <source image> <dest image> <platform>"
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}" <<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"
----
+
. Make sure that you have `guestfish` installed on your system and convert the metal image to an Hetzner one:
+
[source, bash, subs="attributes"]
----
source_image"fedora-coreos-{stable-version}-metal.x86_64.raw"
image_name="fedora-coreos-{stable-version}-hetzner.x86_64.raw"
./convert-image.sh "${source_image}" "${image_name}" hetzner
----
+
. Compress the image using `bzip2`:
+
[source, bash]
----
bzip2 --compress --fast "${image_name}"
----
+
. Use the `hcloud-upload-image` to create a snapshot out of your image:
+
[source, bash]
----
export HCLOUD_TOKEN="<your token>"
hcloud-upload-image upload \
--architecture x86 \
--compression bz2 \
--image-path "${image_name}.bz2" \
--labels os=fedora-coreos,channel=stable \
--description "Fedora CoreOS (stable, x86_64)"
----
+
. 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}")"
----

0 comments on commit 964c6b5

Please sign in to comment.