Installing Flatcar Container Linux to disk
Required Dependencies
If you want to use the flatcar-install
script on some other environment than Flatcar Container Linux, ensure that the following binaries are present:
bash
lbzip2 or bzip2
mount, lsblk (often found in the util-linux packaage)
wget
grep
cp, dd, mkfifo, mkdir, rm, tee (often found in the GNU coreutils package or as part of busybox)
udevadm (found in systemd-udev package, or for Alpine images in eudev)
gpg, gpg2 (found in gnupg2)
gawk (often found in GNU gawk package)
Install script
There is a simple installer that will destroy everything on the given target disk and install Flatcar Container Linux. Essentially it downloads an image, verifies it with gpg, and then copies it bit for bit to disk. An installation requires at least 8 GB of usable space on the device.
The script is self-contained and located on GitHub here and can be run from any Linux distribution. You cannot normally install Flatcar Container Linux to the same device that is currently booted. However, the Flatcar Container Linux ISO or any Linux liveCD will allow Flatcar Container Linux to install to a non-active device.
If you boot Flatcar Container Linux via PXE, the install script is already installed. By default the install script will attempt to install the same version and channel that was PXE-booted:
flatcar-install -d /dev/sda -i ignition.json
ignition.json
should include user information (especially an SSH key) generated from a
Butane Config
, or you will not be able to log into your Flatcar Container Linux instance.
If you are installing on VMware, pass -o vmware_raw
to install the VMware-specific image:
flatcar-install -d /dev/sda -i ignition.json -o vmware_raw
Choose a channel
Flatcar Container Linux is designed to be updated automatically with different schedules per channel. You can disable this feature , although we don’t recommend it. Read the release notes for specific features and bug fixes.
The Alpha channel closely tracks master and is released frequently. The newest versions of system libraries and utilities will be available for testing. The current version is Flatcar Container Linux 4116.0.0.
If you want to ensure you are installing the latest alpha version, use the -C
option:
flatcar-install -d /dev/sda -C alpha
The Beta channel consists of promoted Alpha releases. The current version is Flatcar Container Linux 4081.1.0.
If you want to ensure you are installing the latest beta version, use the -C
option:
flatcar-install -d /dev/sda -C beta
The Stable channel should be used by production clusters. Versions of Flatcar Container Linux are battle-tested within the Beta and Alpha channels before being promoted. The current version is Flatcar Container Linux 3975.2.2.
If you want to ensure you are installing the latest stable version, use the -C
option:
flatcar-install -d /dev/sda -C stable
For reference here are the rest of the flatcar-install
options:
-d DEVICE Install Flatcar Container Linux to the given device.
-s EXPERIMENTAL: Install Flatcar Container Linux to the smallest unmounted disk found
(min. size 10GB). It is recommended to use it with -e or -I to filter the
block devices by their major numbers. E.g., -e 7 to exclude loop devices
or -I 8,259 for certain disk types. Read more about the numbers here:
https://www.kernel.org/doc/Documentation/admin-guide/devices.txt.
-V VERSION Version to install (e.g. current, or current-2022 for the LTS 2022 stream)
-B BOARD Flatcar Container Linux board to use
-C CHANNEL Release channel to use (e.g. beta)
-I|e <M,..> EXPERIMENTAL (used with -s): List of major device numbers to in-/exclude
when finding the smallest disk.
-o OEM OEM type to install (e.g. ami), using flatcar_production_<OEM>_image.bin.bz2
-c CLOUD Insert a cloud-init config to be executed on boot.
-i IGNITION Insert an Ignition config to be executed on boot.
-b BASEURL URL to the image mirror (overrides BOARD and CHANNEL)
-k KEYFILE Override default GPG key for verifying image signature
-f IMAGE Install unverified local image file to disk instead of fetching
-n Copy generated network units to the root partition.
-v Super verbose, for debugging.
Butane Configs
By default there isn’t a password or any other way to log into a fresh Flatcar Container Linux system. The easiest way to configure accounts, add systemd units, and more is via Butane Configs. Jump over to the docs to learn about the supported features .
After using the
Butane
to produce an Ignition config, the installation script will process your ignition.json
file specified with the -i
flag and use it when the installation is booted.
A Butane Config YAML that specifies an SSH key for the core
user but doesn’t use any other parameters looks like:
variant: flatcar
version: 1.0.0
passwd:
users:
- name: core
ssh_authorized_keys:
- ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq.......
Transpile it to Ignition JSON:
cat cl.yaml | docker run --rm -i quay.io/coreos/butane:latest > ignition.json
To start the installation script with a reference to our Ignition config, run:
flatcar-install -d /dev/sda -C stable -i ~/ignition.json
Advanced Butane Config example
This Butane YAML example will configure Flatcar Container Linux to run an NGINX Docker container.
variant: flatcar
version: 1.0.0
passwd:
users:
- name: core
ssh_authorized_keys:
- ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq.......
systemd:
units:
- name: nginx.service
enabled: true
contents: |
[Unit]
Description=NGINX example
After=docker.service
Requires=docker.service
[Service]
TimeoutStartSec=0
ExecStartPre=-/usr/bin/docker rm --force nginx1
ExecStart=/usr/bin/docker run --name nginx1 --pull always --log-driver=journald --net host docker.io/nginx:1
ExecStop=/usr/bin/docker stop nginx1
Restart=always
RestartSec=5s
[Install]
WantedBy=multi-user.target
Transpile it to Ignition JSON:
cat cl.yaml | docker run --rm -i quay.io/coreos/butane:latest > ignition.json
Using Flatcar Container Linux
Now that you have a machine booted it is time to play around. Check out the Flatcar Container Linux Quickstart guide or dig into more specific topics .