Getting Started with Flatcar Container Linux

    If you don’t have a Flatcar Container Linux machine running, check out the guides on running Flatcar Container Linux on most cloud providers ( EC2 , Azure , GCE , Equinix Metal ), virtualization platforms ( Vagrant , VMware , VirtualBox QEMU/KVM / libVirt ) and bare metal servers ( PXE , iPXE , ISO , Installer ). With any of these guides you will have machines up and running in a few minutes.

    It’s highly recommended that you set up a cluster of at least 3 machines — it’s not as much fun on a single machine. If you don’t want to break the bank, Vagrant allows you to run an entire cluster on your laptop. For a cluster to be properly bootstrapped, you have to provide ideally an Ignition config (generated from a Container Linux Config ), or possibly a cloud-config, via user-data, which is covered in each platform’s guide.

    Flatcar Container Linux gives you three essential tools: service discovery, container management and process management. Let’s try each of them out.

    First, on the client start your user agent by typing:

    eval $(ssh-agent)

    Then, add your private key to the agent by typing:


    Connect to a Flatcar Container Linux machine via SSH as the user core. For example, on Amazon, use:

    $ ssh [email protected]
    Flatcar Container Linux (beta)

    If you’re using Vagrant, you’ll need to connect a bit differently:

    $ ssh-add ~/.vagrant.d/insecure_private_key
    Identity added: /Users/core/.vagrant.d/insecure_private_key (/Users/core/.vagrant.d/insecure_private_key)
    $ vagrant ssh core-01
    Flatcar Container Linux (beta)

    Service discovery with etcd

    The first building block of Flatcar Container Linux is service discovery with etcd ( docs ). Data stored in etcd is distributed across all of your machines running Flatcar Container Linux. For example, each of your app containers can announce itself to a proxy container, which would automatically know which machines should receive traffic. Building service discovery into your application allows you to add more machines and scale your services seamlessly.

    If you used an example Container Linux Config or cloud-config from a guide linked in the first paragraph, etcd is automatically started on boot.

    A good starting point for a Container Linux Config would be something like:

        - name: core
            - ssh-rsa AAAA...

    In order to get the discovery token, visit and you will receive a URL including your token. Paste the whole thing into your Container Linux Config file.

    etcdctl is a command line interface to etcd that is preinstalled on Flatcar Container Linux. To set and retrieve a key from etcd you can use the following examples:

    Set a key message with value Hello world:

    etcdctl set /message "Hello world"

    Read the value of message back:

    etcdctl get /message

    You can also use simple curl. These examples correspond to previous ones:

    Set the value:

    curl -L -XPUT -d value="Hello world"

    Read the value:

    curl -L

    If you followed a guide to set up more than one Flatcar Container Linux machine, you can SSH into another machine and can retrieve this same value.

    More detailed information (service discovery)

    View Complete Guide Read etcd API Docs

    Container management with Docker

    The second building block, Docker ( docs ), is where your applications and code run. It is installed on each Flatcar Container Linux machine. You should make each of your services (web server, caching, database) into a container and connect them together by reading and writing to etcd. You can quickly try out a minimal busybox container in two different ways:

    Run a command in the container and then stop it:

    docker run busybox /bin/echo hello world

    Open a shell prompt inside the container:

    docker run -i -t busybox /bin/sh

    More detailed information (Docker)

    Read Docker Docs

    Cloud Providers

    This section provides information and guidance on running Flatcar instances in different cloud environments.

    Customizing the image

    This section provides information and guidance on customizing Flatcar images by placing files on the root or OEM filesystem or embedding an Ignition config.

    Virtual Machines

    This section provides information and guidance on running Flatcar instances on virtual machines.

    Bare Metal

    This section provides information and guidance on running Flatcar instances in bare-metal environments.

    Community supported platforms