Getting Started with Fedora CoreOS
Introduction
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.
Each stream has a canonical URL representing its current state in JSON format. For example, the URL for the stable stream is: https://builds.coreos.fedoraproject.org/streams/stable.json
While Fedora CoreOS does automatic in-place updates, it is generally a good practice to start provisioning new machines from the latest images. The format of this JSON file is stable, and you can parse it to e.g. find the latest ISO/AMI/etc.
For more information on streams and switching between them, see Update Streams.
Provisioning Philosophy
Fedora CoreOS does not have a separate install disk. Instead, every instance starts from a generic disk image which is customized on first boot via Ignition.
Each platform has specific logic to retrieve and apply the first boot configuration. For cloud deployments, Ignition gathers the configuration via user-data mechanisms. In the case of bare metal, Ignition can fetch its configuration from the disk or from a remote source.
For more information on configuration, refer to the documentation for Producing an Ignition File.
Quickstart
Booting on a cloud VM (AWS example)
New AWS instances can be directly created and booted from public FCOS images. You can find the latest AMI for each region from the Update Streams, which is also visualized in the download page.
If you are only interested in exploring FCOS without further customization, you can directly use a registered SSH key-pair for the default core
user.
In order to test out FCOS this way, simply select the relevant SSH key-pair via --key-name
when launching the new instance:
SSH_KEY_NAME="my-key"
aws ec2 run-instances <other options> --image-id <ami> --key-name "${SSH_KEY_NAME}"
In order to launch a customized FCOS instance, a valid Ignition configuration must be passed as its user data at creation time:
aws ec2 run-instances <other options> --image-id <ami> --user-data file://example.ign
By design, cloud-init configuration and startup scripts are not supported on FCOS. Instead, it is recommended to encode any startup logic as systemd service units in the Ignition configuration. |
Booting on a local hypervisor (libvirt example)
-
Fetch the latest image suitable for the
qemu
platform usingcoreos-installer
(or download and verify it from the web). You can usecoreos-installer
as a container, or on Fedora install it from the repos.STREAM="stable" # as an installed binary: coreos-installer download -s "${STREAM}" -p qemu -f qcow2.xz --decompress -C ~/.local/share/libvirt/images/ # or as a container: podman run --pull=always --rm -v $HOME/.local/share/libvirt/images/:/data -w /data \ quay.io/coreos/coreos-installer:release download -s "${STREAM}" -p qemu -f qcow2.xz --decompress
-
Launch a new machine via
virt-install
, using the Ignition file with your customizations.IGNITION_CONFIG="/path/to/example.ign" IMAGE="/path/to/image.qcow2" VM_NAME="fcos-test-01" VCPUS="2" RAM_MB="2048" DISK_GB="10" virt-install --connect="qemu:///system" --name="${VM_NAME}" --vcpus="${VCPUS}" --memory="${RAM_MB}" \ --os-variant="fedora-coreos-$STREAM" --import --graphics=none \ --disk="size=${DISK_GB},backing_store=${IMAGE}" \ --qemu-commandline="-fw_cfg name=opt/com.coreos/config,file=${IGNITION_CONFIG}"
virt-install requires both the OS image and Ignition file to be specified as absolute paths.
|
Depending on your version of virt-install , you may not be able to use --os-variant=fedora-coreos-* and will get an error. In this case, you should pick an older Fedora variant (--os-variant=fedora31 for example). You can find the variants that are supported by you current version of virt-install with osinfo-query os | grep '^\s*fedora' .
|
Make sure that your user has access to /dev/kvm . The default is to allow access for everyone, but on some distributions you may need to add yourself to the kvm group.
|
Exploring the OS
Once the VM has finished booting, its IP addresses will appear on the serial console. By design, there are no hard-coded default credentials.
If you set up an SSH key for the default core
user, you can SSH into the VM and explore the OS:
ssh core@<ip address>
Getting in touch
Bugs can be reported to the Fedora CoreOS Tracker.
For live questions, feel free to reach out on the #fedora-coreos
IRC channel on freenode.
For doubts and longer discussions related to Fedora CoreOS, a forum and a mailing list are available.