Running Flatcar Linux on EC2

The current AMIs for all Flatcar 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 Linux IRC channel or user mailing list.

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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-0d4ac8cf50cbe95b4 Launch Stack
HVM ami-0160d9297a420e25d Launch Stack
ap-northeast-2 PV Launch Stack
HVM ami-0a25390e485aa2e5e Launch Stack
ap-south-1 PV Launch Stack
HVM ami-0ab9a16bf892f2b81 Launch Stack
ap-southeast-1 PV ami-01eb36dd765b826e2 Launch Stack
HVM ami-0535ee6b31a232fbe Launch Stack
ap-southeast-2 PV ami-05df497698042d8c0 Launch Stack
HVM ami-02dea6d58d9201617 Launch Stack
ca-central-1 PV Launch Stack
HVM ami-03e02a960bdad7f0b Launch Stack
eu-central-1 PV ami-0324dcc80ef3726b1 Launch Stack
HVM ami-02ed147fc95aebe41 Launch Stack
eu-west-1 PV ami-0f3e562ccd789e9b4 Launch Stack
HVM ami-074e355da08786a0c Launch Stack
eu-west-2 PV Launch Stack
HVM ami-06fb94744565ad6d6 Launch Stack
eu-west-3 PV Launch Stack
HVM ami-0923924250e0b974c Launch Stack
sa-east-1 PV ami-0d6f26fcb73820023 Launch Stack
HVM ami-0548e79d61006137d Launch Stack
us-east-1 PV ami-0b48c5478c905b8a6 Launch Stack
HVM ami-0074b44f0b594edd1 Launch Stack
us-east-2 PV Launch Stack
HVM ami-039b9fcbe5664b874 Launch Stack
us-west-1 PV ami-00f2ec2fed4860a66 Launch Stack
HVM ami-056634cad1c7c8ffe Launch Stack
us-west-2 PV ami-06b42ee928e90910f Launch Stack
HVM ami-008da258053b9221c 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 Linux 2149.99.0.

EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-04ec83d6b3da5245a Launch Stack
HVM ami-010738cf1d911cb32 Launch Stack
ap-northeast-2 PV Launch Stack
HVM ami-0fdd736e3cd86ed27 Launch Stack
ap-south-1 PV Launch Stack
HVM ami-0d14b87e2775c3ae6 Launch Stack
ap-southeast-1 PV ami-06a277aea29e19002 Launch Stack
HVM ami-0da35ecc58b90f71f Launch Stack
ap-southeast-2 PV ami-0338db38feec6b5fb Launch Stack
HVM ami-09ead16a027ac94c1 Launch Stack
ca-central-1 PV Launch Stack
HVM ami-0b0a4173ca0897e73 Launch Stack
eu-central-1 PV ami-047a56bfd20efcb4f Launch Stack
HVM ami-02865885a4695df8d Launch Stack
eu-west-1 PV ami-0ad72366acd3ce3b0 Launch Stack
HVM ami-0ceff314deeaabbbf Launch Stack
eu-west-2 PV Launch Stack
HVM ami-0696c706cd76792ca Launch Stack
eu-west-3 PV Launch Stack
HVM ami-0b1c4fbd773e842a3 Launch Stack
sa-east-1 PV ami-02051da86d45a2cea Launch Stack
HVM ami-0b4622d846091091d Launch Stack
us-east-1 PV ami-05bc2ae7feb4e4c95 Launch Stack
HVM ami-0e409d43484a1fa9d Launch Stack
us-east-2 PV Launch Stack
HVM ami-01edd91b1a4a0e7be Launch Stack
us-west-1 PV ami-0cfc411e8a2090802 Launch Stack
HVM ami-0deb877ac30b876c0 Launch Stack
us-west-2 PV ami-062d0749cb6aae338 Launch Stack
HVM ami-0d96d1bb31ccdbeab Launch Stack

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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-070e03b32cfe9dfff Launch Stack
HVM ami-0e1ba3eaff170b1e9 Launch Stack
ap-northeast-2 PV Launch Stack
HVM ami-06366cb1c75c74cb0 Launch Stack
ap-south-1 PV Launch Stack
HVM ami-00946c88196ceceb7 Launch Stack
ap-southeast-1 PV ami-0a9e67078ad5cd13b Launch Stack
HVM ami-0b4ec6b84fab94401 Launch Stack
ap-southeast-2 PV ami-02e09c850dbd0df63 Launch Stack
HVM ami-0c0261bdb377121db Launch Stack
ca-central-1 PV Launch Stack
HVM ami-0e3d47ba9a076037d Launch Stack
eu-central-1 PV ami-00b71aacfd8049d3c Launch Stack
HVM ami-01e9834a8c17e47e4 Launch Stack
eu-west-1 PV ami-0b59460a7dfefcb80 Launch Stack
HVM ami-040bff66d12d2ed42 Launch Stack
eu-west-2 PV Launch Stack
HVM ami-0dd222a5cc74e373a Launch Stack
eu-west-3 PV Launch Stack
HVM ami-0d3c1a0352e0f875e Launch Stack
sa-east-1 PV ami-066ac87334e7ae5b3 Launch Stack
HVM ami-05e403409d591f23b Launch Stack
us-east-1 PV ami-07f5a99d272656b80 Launch Stack
HVM ami-096be41989ec7e569 Launch Stack
us-east-2 PV Launch Stack
HVM ami-06cb41389c5abe6bd Launch Stack
us-west-1 PV ami-071dbcaf85c3c0483 Launch Stack
HVM ami-08e51385230d2021f Launch Stack
us-west-2 PV ami-04c0f696dbec4f499 Launch Stack
HVM ami-03a832953e2c7b6e6 Launch Stack

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

Container Linux Configs

Flatcar 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 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 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 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-0b48c5478c905b8a6 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 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 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-0b48c5478c905b8a6.
  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-03907f76955337894.
  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-07f5a99d272656b80.
  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 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.