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 16, 2024
1 parent ab098f7 commit ce16674
Show file tree
Hide file tree
Showing 2 changed files with 181 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
180 changes: 180 additions & 0 deletions modules/ROOT/pages/provisioning-hetzner.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
= 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, upload it to a public HTTP server 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.
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] 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,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
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}"
----
+
. Upload the image somewhere publicly available over HTTPS and note down the URL:
+
[source, bash, subs="attributes"]
----
image_url="https://example.com/fedora-coreos-{stable-version}-hetzner.x86_64.raw.bz2"
----
+
. 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-url "${image_url}" \
--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 ce16674

Please sign in to comment.