Installing CoreOS on Bare Metal

This guide provides instructions to install Fedora CoreOS to bare metal. Three options are available:

  • Installing from live ISO

  • Installing from PXE

  • Installing from the container

Prerequisite

Before installing FCOS, you must have an Ignition configuration file and host it somewhere (e.g. using python3 -m http.server). If you do not have one, see Producing an Ignition File.

Installing from live ISO

To install FCOS onto bare metal using the live ISO, follow these steps:

  1. Download the ISO image:

podman run --privileged --pull=always --rm -v .:/data -w /data \
    quay.io/coreos/coreos-installer:release download -f iso

+ NOTE: The live system requires at least 3 GiB of RAM. You can boot it in either legacy BIOS or UEFI mode, regardless of what mode the OS will use once installed.

+ . Burn the ISO to disk and boot it on the target system. The ISO is capable of bringing up a fully functioning FCOS system purely from memory (i.e. without using any disk storage). Once booted, you will have access to a bash command prompt. . You can now run coreos-installer:

sudo coreos-installer install /dev/sda \
    --ignition-url https://example.com/example.ign

Once the installation is complete, you can simply sudo reboot. After rebooting, the first boot process begins. It is at this time that Ignition ingests the configuration file and provisions the system as specified.

Check out coreos-installer install --help for more options on how to install Fedora CoreOS.

Installing from PXE

To install from PXE, follow these steps:

  1. Download an FCOS PXE kernel, initramfs, and rootfs image:

podman run --privileged --pull=always --rm -v .:/data -w /data \
    quay.io/coreos/coreos-installer:release download -f pxe

+ NOTE: You can install in either legacy boot (BIOS) mode or in UEFI mode, regardless of what mode the OS will use once installed.

+ . Follow this example pxelinux.cfg for booting the installer images with PXELINUX:

+

DEFAULT pxeboot
TIMEOUT 20
PROMPT 0
LABEL pxeboot
    KERNEL fedora-coreos-32.20200726.3.1-live-kernel-x86_64
    APPEND initrd=fedora-coreos-32.20200726.3.1-live-initramfs.x86_64.img,fedora-coreos-32.20200726.3.1-live-rootfs.x86_64.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://192.168.1.101:8000/config.ign
IPAPPEND 2

For more details on how to use this information, see this blog post for testing a PXE installation via a local VM and libvirt.

Installing from the container

You can use the coreos-installer container from an existing system to install to an attached block device. For example (substitute docker for podman if needed):

sudo podman run --pull=always --privileged --rm \
    -v /dev:/dev -v /run/udev:/run/udev -v .:/data -w /data \
    quay.io/coreos/coreos-installer:release \
    install /dev/vdb -i config.ign

In this example, coreos-installer will download the latest stable FCOS metal image and install it onto /dev/vdb. It will then inject the Ignition file config.ign in the current directory into the image. Use --help to see all the available options.

Downloading and mirroring the metal image

Sometimes, it’s necessary to download the metal image ahead of time and then have it passed locally to coreos-installer for installation. You can download the metal image directly from the FCOS download page, or you can use coreos-installer download.

When installing via the live ISO or PXE, there is no need to download the metal image. It is already part of those environments.

There are two metal images: one for 512b-sector disks (labeled "Raw" on the download page), and one for 4k-sector native disks (labeled "Raw (4K Native)"). Unless you know to be targeting a 4k native disk, use the 512b one, which is the most common. See this page for more information.

To download the 4kn native metal image with coreos-installer download, use the --format 4k.raw.xz switch.

The metal image uses a hybrid partition layout which supports both BIOS and UEFI booting.

When you’re finally ready to install FCOS, you can point it at your downloaded image using coreos-installer install --image-url <LOCAL_MIRROR> or coreos-install --image-file <PATH>.

Live PXE

In this model, rather than performing a "persistent" installation to disk, you can run directly from RAM. This is useful in e.g. "diskless" scenarios. The steps are similar to the above, just omit the coreos.inst arguments, and instead have the system itself run Ignition:

DEFAULT pxeboot
TIMEOUT 20
PROMPT 0
LABEL pxeboot
    KERNEL fedora-coreos-32.20200726.3.1-live-kernel-x86_64
    APPEND initrd=fedora-coreos-32.20200726.3.1-live-initramfs.x86_64.img,fedora-coreos-32.20200726.3.1-live-rootfs.x86_64.img ignition.firstboot ignition.platform.id=metal ignition.config.url=http://192.168.1.101/config.ign systemd.unified_cgroup_hierarchy=0
IPAPPEND 2

PXE rootfs image

Before August 2020, the Fedora CoreOS PXE image included two components: a kernel image and an initramfs image. Beginning August 12, a third rootfs image was added. At present, the rootfs image is optional, and Fedora CoreOS displays a warning on login if the system was booted without it. After an initial migration period, the rootfs image will be mandatory and the live PXE system will not boot without it.

The migration timeline is:

  • August 12: rootfs image available in next, testing, and stable streams

  • August 25: rootfs image required in next stream

  • September 22: rootfs image required in testing stream

  • October 6: rootfs image required in stable stream

To boot with the rootfs artifact, make one of the following changes to your PXE config:

  • Specify only the initramfs file as the initrd, and pass an HTTP(S) URL for the rootfs using the coreos.live.rootfs_url= kernel argument.

  • Specify both initramfs and rootfs files as initrds in your PXE configuration. This can be done via multiple initrd directives, or using additional initrd= parameters as kernel arguments.

  • Concatenate the initramfs and rootfs files together, and specify the combined file as the initrd.

For more information on this change, see the tracker issue.