Fedora CoreOS - Getting Started

Fedora CoreOS has no install-time configuration. Every Fedora CoreOS system begins with a generic, unconfigured disk image. On first boot Ignition will read the supplied config and configure the system. Ignition configs are usually supplied via the cloud’s userdata mechanism, or, in the case of bare metal, injected at install time. This guide will show you how to launch Fedora CoreOS on AWS, QEMU, and bare metal as well as how to create Ignition configs.

Launching Fedora CoreOS

Booting on AWS

To boot on AWS, find the correct AMI in the download page and specify the Ignition config as the user-data. Note that while the AWS documentation mentions cloud-init and scripts, Fedora CoreOS only accepts Ignition configs; it does not support cloud-init or running scripts from userdata.

Example launching Fedora CoreOS on AWS
aws ec2 run-instances <other options> --user-data file://config.ign

Booting with QEMU

Download the QEMU Fedora CoreOS image from the download page.

Specify your Ignition config by using -fw_cfg to set the opt/com.coreos/config key in the QEMU firmware configuration device.

Example launching Fedora CoreOS with QEMU
qemu-system-x86_64 -machine accel=kvm -m 2048 -cpu host -nographic \
	-drive if=virtio,file=path/to/fedora-coreos-qemu.qcow2 \
	-device virtio-rng-pci \
	-fw_cfg name=opt/com.coreos/config,file=path/to/ignition-config.ign

Installing on bare metal

Follow the coreos-installer instructions to install Fedora CoreOS to disk. This will inject your specified Ignition config in the installed image.

Generating Ignition configs

Ignition configs are not intended to be hand-written. Instead, use the Fedora CoreOS Config Transpiler (FCCT) to translate Fedora CoreOS Configs (FCCs) to Ignition configs. In addition to be easier to write, FCCT will also validate your config and check for errors. Here’s an example FCC that adds an SSH key to the core user’s authorized keys:

Example FCC adding an SSH key to the core user
variant: fcos
version: 1.0.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAA

Then use FCCT to convert the FCC to an Ignition config:

Using FCCT to convert from an FCC to an Ignition config
./bin/amd64/fcct --strict --pretty --input your_config.fcc --output your_config.ign

Then launch or install Fedora CoreOS with that config as described above and check that you can SSH in:

SSHing in as the core user
ssh core@<ip>

Refer to the FCCT getting started guide, examples and configuration specification for more information on using FCCT, more examples, and a complete list of configuration FCCT supports.

Running containers

Fedora CoreOS ships with both docker and podman installed. Use systemd units to start and stop containers.

Example for running busybox using systemd and podman
variant: fcos
version: 1.0.0
systemd:
  units:
    - name: hello.service
      enabled: true
      contents: |
        [Unit]
        Description=MyApp
        After=network-online.target
        Wants=network-online.target

        [Service]
        TimeoutStartSec=0
        ExecStartPre=-/bin/podman kill busybox1
        ExecStartPre=-/bin/podman rm busybox1
        ExecStartPre=/bin/podman pull busybox
        ExecStart=/bin/podman run --name busybox1 busybox /bin/sh -c "trap 'exit 0' INT TERM; while true; do echo Hello World; sleep 1; done"

        [Install]
        WantedBy=multi-user.target

Note that when using docker instead of podman, units starting docker containers will need Requires=docker.service and After=docker.service to ensure the docker daemon is running before trying to start containers.

Running etcd

etcd is not shipped as part of Fedora CoreOS and should instead be run as a container.

FCC for setting up single node etcd
variant: fcos
version: 1.0.0
systemd:
  units:
    - name: etcd-member.service
      enabled: true
      contents: |
        [Unit]
        Description=Run single node etcd
        After=network-online.target
        Wants=network-online.target

        [Service]
        ExecStartPre=mkdir -p /var/lib/etcd
        ExecStartPre=-/bin/podman kill etcd
        ExecStartPre=-/bin/podman rm etcd
        ExecStartPre=-/bin/podman pull quay.io/coreos/etcd
        ExecStart=/bin/podman run --name etcd --volume /var/lib/etcd:/etcd-data:z --net=host quay.io/coreos/etcd:latest /usr/local/bin/etcd --data-dir /etcd-data --name node1 \
                --initial-advertise-peer-urls http://127.0.0.1:2380 --listen-peer-urls http://127.0.0.1:2380 \
                --advertise-client-urls http://127.0.0.1:2379 \
                --listen-client-urls http://127.0.0.1:2379 \
                --initial-cluster node1=http://127.0.0.1:2380

        ExecStop=/bin/podman stop etcd

        [Install]
        WantedBy=multi-user.target

See the etcd documentation for more information on running etcd in containers and how to set up multi-node etcd.

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 or on the Fedora CoreOS mailing list.