Fedora CoreOS - Getting Started


Update Streams

There are three Fedora CoreOS (FCOS) update streams available: stable, testing, and next. In general, you will want to use stable, but it is recommended to run some machines on testing and next as well. For more information on streams and switching between them, see Update Streams.

Provisioning Philosophy

Fedora CoreOS (FCOS) has no install-time configuration. Every FCOS system begins with a generic disk image. For each deployment mechanism (cloud VM, local VM, bare metal), configuration can be supplied at first boot. FCOS reads and applies the configuration file with Ignition. For cloud deployments, Ignition gathers the configuration via the cloud’s user-data mechanism. In the case of bare metal, Ignition injects the configuration at install time.

For more information on configuration, refer to the documentation for Producing an Ignition File.

Launching FCOS

Launching on Amazon Web Services (AWS)

To launch FCOS on AWS:

  1. Identify the correct AMI image ID for your region from the download page

  2. Launch the VM using aws ec2 run-instances. The Ignition file can be passed to the VM as its user data. You can skip this step if you just want SSH access; simply pass a registered key name via --key-name. This provides an easy way to test out FCOS without first creating an Ignition configuration.

    Example launching FCOS on AWS using an Ignition configuration file
    aws ec2 run-instances <other options> --image-id <ami> --user-data file://example.ign
    Example launching FCOS on AWS using a registered SSH key pair
    aws ec2 run-instances <other options> --image-id <ami> --key-name my-key

    While the AWS documentation mentions cloud-init and scripts, FCOS does not support cloud-init or the ability to run scripts from user-data. It accepts only Ignition configuration files.

Launching with QEMU or libvirt

  1. Download and verify the latest image suitable for QEMU.

  2. Uncompress the file. Assuming that the downloaded file is called fedora-coreos-qemu.qcow2.xz, the command would be the following:

    unxz fedora-coreos-qemu.qcow2.xz
    Make sure that your user has access to /dev/kvm (this should already be the case on modern distros), or if /dev/kvm is owned by the kvm group, adding yourself to that group with usermod -aG kvm $USER.
  3. Launch the VM using qemu-kvm or virt-install. The Ignition file is passed to the VM via the -fw_cfg parameter, which sets the opt/com.coreos/config key in the QEMU firmware configuration device. For libvirt, you must pass this through the --qemu-commandline argument. You can use -snapshot to make qemu-kvm allocate temporary storage for the VM, or qemu-img create to first create a layered qcow2.

    Example launching FCOS with QEMU (temporary storage)
    qemu-kvm -m 2048 -cpu host -nographic -snapshot \
    	-drive if=virtio,file=fedora-coreos-qemu.qcow2 \
    	-fw_cfg name=opt/com.coreos/config,file=path/to/example.ign
    Example launching FCOS with QEMU (persistent storage)
    qemu-img create -f qcow2 -b fedora-coreos-qemu.qcow2 my-fcos-vm.qcow2
    qemu-kvm -m 2048 -cpu host -nographic \
    	-drive if=virtio,file=my-fcos-vm.qcow2 \
    	-fw_cfg name=opt/com.coreos/config,file=path/to/example.ign
    Example launching FCOS with virt-install
    virt-install --connect qemu:///system -n fcos -r 2048 --os-variant=fedora31 --import \
    	--graphics=none --disk size=10,backing_store=/path/to/fedora-coreos-qemu.qcow2 \
    	--qemu-commandline="-fw_cfg name=opt/com.coreos/config,file=/path/to/example.ign"
When using virt-install, you must specify absolute paths to the image and the Ignition file.
If running with SELinux enabled, you may need to change the label of the Ignition file to allow access: chcon -t svirt_home_t path/to/example.ign

Once the VM has finished booting, its IP addresses will appear on the serial console. You can then SSH into the FCOS VM as the core user:

ssh core@<ip address>

Installing on bare metal

Follow the Bare Metal Installation Instructions to install Fedora CoreOS to disk. This procedure injects the specified Ignition configuration at install time.

Where to report bugs and ask questions

Report bugs to the Fedora CoreOS Tracker and ask questions on the #fedora-coreos IRC channel on freenode, the Fedora CoreOS forum, or the mailing list.