Installing Flatcar Linux to disk

Install script

There is a simple installer that will destroy everything on the given target disk and install Flatcar 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 Linux to the same device that is currently booted. However, the Flatcar Linux ISO or any Linux liveCD will allow Flatcar Linux to install to a non-active device.

If you boot Flatcar 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 Container Linux Config, or you will not be able to log into your Flatcar 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 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 Linux 2121.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 Linux 2107.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 Linux are battle-tested within the Beta and Alpha channels before being promoted. The current version is Flatcar Linux 2079.3.1.

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 Linux to the given device.
-V VERSION  Version to install (e.g. current)
-B BOARD    Flatcar Linux board to use
-C CHANNEL  Release channel to use (e.g. beta)
-o OEM      OEM type to install (e.g. ami)
-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)
-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.

Container Linux Configs

By default there isn't a password or any other way to log into a fresh Flatcar Linux system. The easiest way to configure accounts, add systemd units, and more is via Container Linux Configs. Jump over to the docs to learn about the supported features.

After using the Container Linux Config Transpiler 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 Container Linux Config that specifies an SSH key for the core user but doesn't use any other parameters looks like:

    - name: core
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq.......

Note: The {PRIVATE_IPV4} and {PUBLIC_IPV4} substitution variables referenced in other documents are not supported on libvirt.

To start the installation script with a reference to our Ignition config, run:

flatcar-install -d /dev/sda -C stable -i ~/ignition.json

Advanced Container Linux Config example

This example will configure Flatcar Linux components: etcd and flannel. You have to substitute <PEER_ADDRESS> to your host's IP or DNS address.

    - name: core
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq.......
  # generate a new token for each unique cluster from
  # specify the initial size of your cluster with ?size=X
  advertise_client_urls: http://<PEER_ADDRESS>:2379,http://<PEER_ADDRESS>:4001
  initial_advertise_peer_urls: http://<PEER_ADDRESS>:2380
  # listen on both the official ports and the legacy ports
  # legacy ports can be omitted if your application doesn't depend on them
  listen_peer_urls: http://<PEER_ADDRESS>:2380
    - name: flanneld.service
      enable: true
      - name: 50-network-config.conf
        contents: |
          ExecStartPre=/usr/bin/etcdctl set / '{"Network":"", "Backend": {"Type": "vxlan"}}'

Using Flatcar Linux

Now that you have a machine booted it is time to play around. Check out the Flatcar Linux Quickstart guide or dig into more specific topics.