Running Flatcar Container Linux on EC2

The current AMIs for all Flatcar Container Linux channels and EC2 regions are listed below and updated frequently. Using CloudFormation is the easiest way to launch a cluster, but it is also possible to follow the manual steps at the end of the article. Questions can be directed to the Flatcar Container Linux IRC channel or user mailing list.

Choosing 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 2387.0.0.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-0885c9343b175ea7f Launch Stack
HVM ami-095157f5c2a3f6c4d Launch Stack
ap-northeast-2 PV Launch Stack
HVM ami-03254f5e797f415d9 Launch Stack
ap-south-1 PV Launch Stack
HVM ami-0f7c27197c1dcc5a0 Launch Stack
ap-southeast-1 PV ami-0776b75a7efec1be1 Launch Stack
HVM ami-0b377e85cffd15cab Launch Stack
ap-southeast-2 PV ami-0cbf134051284f3b0 Launch Stack
HVM ami-04a55de6299390838 Launch Stack
ca-central-1 PV Launch Stack
HVM ami-0497cc2a73375e4e9 Launch Stack
eu-central-1 PV ami-0ca5c4815cac7c163 Launch Stack
HVM ami-04692c6574b4ac264 Launch Stack
eu-west-1 PV ami-06aae4c183887c258 Launch Stack
HVM ami-0900eac6dc5d4def2 Launch Stack
eu-west-2 PV Launch Stack
HVM ami-0fbd4a72b92c5fffe Launch Stack
eu-west-3 PV Launch Stack
HVM ami-07dd3226a064c7243 Launch Stack
sa-east-1 PV ami-08636f9a10851de59 Launch Stack
HVM ami-00f78cf802f97d1b8 Launch Stack
us-east-1 PV ami-0ca6ecb8d30abed15 Launch Stack
HVM ami-0cf25fd1e26d631ed Launch Stack
us-east-2 PV Launch Stack
HVM ami-013710b47ace12003 Launch Stack
us-west-1 PV ami-0ba6f6a8231290433 Launch Stack
HVM ami-0eb2613a01d666189 Launch Stack
us-west-2 PV ami-0688c6aa5120445a3 Launch Stack
HVM ami-099ff1ca7c85e04d7 Launch Stack

The Edge channel includes bleeding-edge features with the newest versions of the Linux kernel, systemd and other core packages. Can be highly unstable. The current version is Flatcar Container Linux 2345.99.1.

EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-0c7422e38fb23386f Launch Stack
HVM ami-0b25f5bbd7e3d3da5 Launch Stack
ap-northeast-2 PV Launch Stack
HVM ami-07e52d3fc57146545 Launch Stack
ap-south-1 PV Launch Stack
HVM ami-048d862347fc494c9 Launch Stack
ap-southeast-1 PV ami-0416bc909dc677b5d Launch Stack
HVM ami-0ca069d54a4b65a45 Launch Stack
ap-southeast-2 PV ami-01c09abfe0cd9667f Launch Stack
HVM ami-0eb37382e58dfb533 Launch Stack
ca-central-1 PV Launch Stack
HVM ami-0abe7ae9b4d53db9e Launch Stack
eu-central-1 PV ami-0bc8af98e9a952bfb Launch Stack
HVM ami-09ff60cee7c4ffc8e Launch Stack
eu-west-1 PV ami-03e756b443c450947 Launch Stack
HVM ami-05efc3b2a5f697dd9 Launch Stack
eu-west-2 PV Launch Stack
HVM ami-0c247ef5d8a6fe7c2 Launch Stack
eu-west-3 PV Launch Stack
HVM ami-05425f4a4bf305aeb Launch Stack
sa-east-1 PV ami-0ab7c0e232f7d2ce8 Launch Stack
HVM ami-08d1e6336fae969cf Launch Stack
us-east-1 PV ami-0117111fc44762683 Launch Stack
HVM ami-0c54ba5c38902dfcb Launch Stack
us-east-2 PV Launch Stack
HVM ami-09c7b9d482457a872 Launch Stack
us-west-1 PV ami-0eb5a87f96628c8f8 Launch Stack
HVM ami-0e00b48536b558ae2 Launch Stack
us-west-2 PV ami-0b78af9c664b686e1 Launch Stack
HVM ami-095cbf5ddb670be6e Launch Stack

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 2303.3.1.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-0c4ac2c9b7da8e8dc Launch Stack
HVM ami-0394df49d3cb3b0f0 Launch Stack
ap-northeast-2 PV Launch Stack
HVM ami-01ed6597adfa7baae Launch Stack
ap-south-1 PV Launch Stack
HVM ami-0330711a1827d99d1 Launch Stack
ap-southeast-1 PV ami-053b27196160aeb3a Launch Stack
HVM ami-0c4a6ebbb5dc59b73 Launch Stack
ap-southeast-2 PV ami-0e3fd2163aff11827 Launch Stack
HVM ami-0c3a27cfbf2a07830 Launch Stack
ca-central-1 PV Launch Stack
HVM ami-009157164163bf01e Launch Stack
eu-central-1 PV ami-0c2f014e89a25be49 Launch Stack
HVM ami-0215a3496f6a601d6 Launch Stack
eu-west-1 PV ami-0a7e7ce1232581aa7 Launch Stack
HVM ami-02815ba59fd1215da Launch Stack
eu-west-2 PV Launch Stack
HVM ami-0ccb9d395b9e03ff1 Launch Stack
eu-west-3 PV Launch Stack
HVM ami-04dd061b93942c838 Launch Stack
sa-east-1 PV ami-096b60465cf84c37d Launch Stack
HVM ami-03441ef7cdc572d84 Launch Stack
us-east-1 PV ami-03b819d21e98a5c67 Launch Stack
HVM ami-0db7de4b628d58045 Launch Stack
us-east-2 PV Launch Stack
HVM ami-0ddd9867c53c030da Launch Stack
us-west-1 PV ami-008089a396f374e05 Launch Stack
HVM ami-021144166741aaa1e Launch Stack
us-west-2 PV ami-06cfb02bb6d02f886 Launch Stack
HVM ami-014436c61e95d301f Launch Stack

CloudFormation will launch a cluster of Flatcar Container Linux machines with a security and autoscaling group.

Container Linux Configs

Flatcar Container Linux allows you to configure machine parameters, configure networking, launch systemd units on startup, and more via Container Linux Configs. These configs are then transpiled into Ignition configs and given to booting machines. Head over to the docs to learn about the supported features.

You can provide a raw Ignition config to Flatcar Container Linux via the Amazon web console or via the EC2 API.

As an example, this Container Linux Config will configure and start etcd:

etcd:
  # All options get passed as command line flags to etcd.
  # Any information inside curly braces comes from the machine at boot time.

  # multi_region and multi_cloud deployments need to use {PUBLIC_IPV4}
  advertise_client_urls:       "http://{PRIVATE_IPV4}:2379"
  initial_advertise_peer_urls: "http://{PRIVATE_IPV4}: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_client_urls:          "http://0.0.0.0:2379"
  listen_peer_urls:            "http://{PRIVATE_IPV4}:2380"
  # generate a new token for each unique cluster from https://discovery.etcd.io/new?size=3
  # specify the initial size of your cluster with ?size=X
  discovery:                   "https://discovery.etcd.io/<token>"

Instance storage

Ephemeral disks and additional EBS volumes attached to instances can be mounted with a .mount unit. Amazon's block storage devices are attached differently depending on the instance type. Here's the Container Linux Config to format and mount the first ephemeral disk, xvdb, on most instance types:

storage:
  filesystems:
    - mount:
        device: /dev/xvdb
        format: ext4
        wipe_filesystem: true

systemd:
  units:
    - name: media-ephemeral.mount
      enable: true
      contents: |
        [Mount]
        What=/dev/xvdb
        Where=/media/ephemeral
        Type=ext4

        [Install]
        RequiredBy=local-fs.target

For more information about mounting storage, Amazon's own documentation is the best source. You can also read about mounting storage on Flatcar Container Linux.

Adding more machines

To add more instances to the cluster, just launch more with the same Container Linux Config, the appropriate security group and the AMI for that region. New instances will join the cluster regardless of region if the security groups are configured correctly.

SSH to your instances

Flatcar Container Linux is set up to be a little more secure than other cloud images. By default, it uses the core user instead of root and doesn't use a password for authentication. You'll need to add an SSH key(s) via the AWS console or add keys/passwords via your Container Linux Config in order to log in.

To connect to an instance after it's created, run:

ssh core@<ip address>

Multiple clusters

If you would like to create multiple clusters you will need to change the "Stack Name". You can find the direct template file on S3.

Manual setup

TL;DR: launch three instances of ami-0ca6ecb8d30abed15 in us-east-1 with a security group that has open port 22, 2379, 2380, 4001, and 7001 and the same "User Data" of each host. SSH uses the core user and you have etcd and Docker to play with.

Creating the security group

You need open port 2379, 2380, 7001 and 4001 between servers in the etcd cluster. Step by step instructions below.

This step is only needed once

First we need to create a security group to allow Flatcar Container Linux instances to communicate with one another.

  1. Go to the security group page in the EC2 console.
  2. Click "Create Security Group"
    • Name: flatcar-testing
    • Description: Flatcar Container Linux instances
    • VPC: No VPC
    • Click: "Yes, Create"
  3. In the details of the security group, click the Inbound tab
  4. First, create a security group rule for SSH
    • Create a new rule: SSH
    • Source: 0.0.0.0/0
    • Click: "Add Rule"
  5. Add two security group rules for etcd communication
    • Create a new rule: Custom TCP rule
    • Port range: 2379
    • Source: type "flatcar-testing" until your security group auto-completes. Should be something like "sg-8d4feabc"
    • Click: "Add Rule"
    • Repeat this process for port range 2380, 4001 and 7001 as well
  6. Click "Apply Rule Changes"

Launching a test cluster

We will be launching three instances, with a few parameters in the User Data, and selecting our security group.

  1. Open the quick launch wizard to boot ami-0ca6ecb8d30abed15.
  2. On the second page of the wizard, launch 3 servers to test our clustering
    • Number of instances: 3
    • Click "Continue"
  3. Next, we need to specify a discovery URL, which contains a unique token that allows us to find other hosts in our cluster. If you're launching your first machine, generate one at https://discovery.etcd.io/new?size=3, configure the `?size=` to your initial cluster size and add it to the metadata. You should re-use this key for each machine in the cluster.
  4. Use ct to convert the following configuration into an Ignition config, and back in the EC2 dashboard, paste it into the "User Data" field. wzxhzdk:3
    • Paste configuration into "User Data"
    • "Continue"
  5. Storage Configuration
    • "Continue"
  6. Tags
    • "Continue"
  7. Create Key Pair
    • Choose a key of your choice, it will be added in addition to the one in the gist.
    • "Continue"
  8. Choose one or more of your existing Security Groups
    • "flatcar-testing" as above.
    • "Continue"
  9. Launch!

We will be launching three instances, with a few parameters in the User Data, and selecting our security group.

  1. Open the quick launch wizard to boot ami-064c38712b2c21c6b.
  2. On the second page of the wizard, launch 3 servers to test our clustering
    • Number of instances: 3
    • Click "Continue"
  3. Next, we need to specify a discovery URL, which contains a unique token that allows us to find other hosts in our cluster. If you're launching your first machine, generate one at https://discovery.etcd.io/new?size=3, configure the `?size=` to your initial cluster size and add it to the metadata. You should re-use this key for each machine in the cluster.
  4. Use ct to convert the following configuration into an Ignition config, and back in the EC2 dashboard, paste it into the "User Data" field. wzxhzdk:4
    • Paste configuration into "User Data"
    • "Continue"
  5. Storage Configuration
    • "Continue"
  6. Tags
    • "Continue"
  7. Create Key Pair
    • Choose a key of your choice, it will be added in addition to the one in the gist.
    • "Continue"
  8. Choose one or more of your existing Security Groups
    • "flatcar-testing" as above.
    • "Continue"
  9. Launch!

We will be launching three instances, with a few parameters in the User Data, and selecting our security group.

  1. Open the quick launch wizard to boot ami-03b819d21e98a5c67.
  2. On the second page of the wizard, launch 3 servers to test our clustering
    • Number of instances: 3
    • Click "Continue"
  3. Next, we need to specify a discovery URL, which contains a unique token that allows us to find other hosts in our cluster. If you're launching your first machine, generate one at https://discovery.etcd.io/new?size=3, configure the `?size=` to your initial cluster size and add it to the metadata. You should re-use this key for each machine in the cluster.
  4. Use ct to convert the following configuration into an Ignition config, and back in the EC2 dashboard, paste it into the "User Data" field. wzxhzdk:5
    • Paste configuration into "User Data"
    • "Continue"
  5. Storage Configuration
    • "Continue"
  6. Tags
    • "Continue"
  7. Create Key Pair
    • Choose a key of your choice, it will be added in addition to the one in the gist.
    • "Continue"
  8. Choose one or more of your existing Security Groups
    • "flatcar-testing" as above.
    • "Continue"
  9. Launch!

Installation from a VMDK image

One of the possible ways of installation is to import the generated VMDK Flatcar image as a snapshot. The image file will be in https://${CHANNEL}.release.flatcar-linux.net/amd64-usr/${VERSION}/flatcar_production_ami_vmdk_image.vmdk.bz2. Make sure you download the signature (it's available in https://${CHANNEL}.release.flatcar-linux.net/amd64-usr/${VERSION}/flatcar_production_ami_vmdk_image.vmdk.bz2.sig) and check it before proceeding.

$ wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_ami_vmdk_image.vmdk.bz2
$ wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_ami_vmdk_image.vmdk.bz2.sig
$ gpg --verify flatcar_production_ami_vmdk_image.vmdk.bz2.sig
gpg: assuming signed data in 'flatcar_production_ami_vmdk_image.vmdk.bz2'
gpg: Signature made Thu 15 Mar 2018 10:27:57 AM CET
gpg:                using RSA key A621F1DA96C93C639506832D603443A1D0FC498C
gpg: Good signature from "Flatcar Buildbot (Official Builds) <buildbot@flatcar-linux.org>" [ultimate]

Then, follow the instructions in Importing a Disk as a Snapshot Using VM Import/Export. You'll need to upload the uncompressed vmdk file to S3.

After the snapshot is imported, you can go to "Snapshots" in the EC2 dashboard, and generate an AMI image from it. To make it work, use /dev/sda2 as the "Root device name" and you probably want to select "Hardware-assisted virtualization" as "Virtualization type".

In the future we'll upload AMIs directly during the build process so this will be much easier.

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.