Running CoreOS Container Linux on EC2

The current AMIs for all 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 CoreOS [IRC channel][irc] or [user mailing list][coreos-user].

Choosing a channel

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 Container Linux 1353.1.0.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
eu-central-1 PV ami-2eb46241 Launch Stack
HVM ami-9cb462f3 Launch Stack
ap-northeast-1 PV ami-1289d575 Launch Stack
HVM ami-ac89d5cb Launch Stack
us-gov-west-1 PV ami-c69114a7 Launch Stack
HVM ami-d69613b7 Launch Stack
ap-northeast-2 PV ami-97cf1cf9 Launch Stack
HVM ami-89cf1ce7 Launch Stack
ca-central-1 PV ami-12368b76 Launch Stack
HVM ami-8f318ceb Launch Stack
ap-south-1 PV ami-59e19136 Launch Stack
HVM ami-d1e292be Launch Stack
sa-east-1 PV ami-e22f4f8e Launch Stack
HVM ami-7d2d4d11 Launch Stack
ap-southeast-2 PV ami-bc868bdf Launch Stack
HVM ami-7f878a1c Launch Stack
ap-southeast-1 PV ami-e648fa85 Launch Stack
HVM ami-e148fa82 Launch Stack
us-east-1 PV ami-f8d67cee Launch Stack
HVM ami-26d67c30 Launch Stack
us-east-2 PV ami-e5270380 Launch Stack
HVM ami-c32501a6 Launch Stack
us-west-2 PV ami-fed45c9e Launch Stack
HVM ami-2bd55d4b Launch Stack
us-west-1 PV ami-23623a43 Launch Stack
HVM ami-c9653da9 Launch Stack
eu-west-1 PV ami-0791a761 Launch Stack
HVM ami-a09caac6 Launch Stack
eu-west-2 PV ami-35a1b451 Launch Stack
HVM ami-d3a4b1b7 Launch Stack

The Beta channel consists of promoted Alpha releases. The current version is Container Linux 1353.2.0.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
eu-central-1 PV ami-a16ebfce Launch Stack
HVM ami-5097473f Launch Stack
ap-northeast-1 PV ami-ef7c5988 Launch Stack
HVM ami-257f5a42 Launch Stack
us-gov-west-1 PV ami-857efbe4 Launch Stack
HVM ami-4278fd23 Launch Stack
ap-northeast-2 PV ami-ee499a80 Launch Stack
HVM ami-5d4d9e33 Launch Stack
ca-central-1 PV ami-280bb64c Launch Stack
HVM ami-0e0fb26a Launch Stack
ap-south-1 PV ami-46700329 Launch Stack
HVM ami-2b700344 Launch Stack
sa-east-1 PV ami-f52b4899 Launch Stack
HVM ami-6a2a4906 Launch Stack
ap-southeast-2 PV ami-cb1619a8 Launch Stack
HVM ami-c11619a2 Launch Stack
ap-southeast-1 PV ami-1e4bf77d Launch Stack
HVM ami-f749f594 Launch Stack
us-east-1 PV ami-9f43fb89 Launch Stack
HVM ami-45388053 Launch Stack
us-east-2 PV ami-94e7c3f1 Launch Stack
HVM ami-d4e5c1b1 Launch Stack
us-west-2 PV ami-2e91054e Launch Stack
HVM ami-31930751 Launch Stack
us-west-1 PV ami-3bc2995b Launch Stack
HVM ami-57c79c37 Launch Stack
eu-west-1 PV ami-f6bb8790 Launch Stack
HVM ami-b1bb87d7 Launch Stack
eu-west-2 PV ami-646c7800 Launch Stack
HVM ami-2a61754e Launch Stack

The Stable channel should be used by production clusters. Versions of Container Linux are battle-tested within the Beta and Alpha channels before being promoted. The current version is Container Linux 1298.6.0.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
eu-central-1 PV ami-2126f14e Launch Stack
HVM ami-8424f3eb Launch Stack
ap-northeast-1 PV ami-15471a72 Launch Stack
HVM ami-e6461b81 Launch Stack
us-gov-west-1 PV ami-46fb7e27 Launch Stack
HVM ami-83fb7ee2 Launch Stack
ap-northeast-2 PV ami-51d5063f Launch Stack
HVM ami-52d5063c Launch Stack
ca-central-1 PV ami-ea3e838e Launch Stack
HVM ami-b73d80d3 Launch Stack
ap-south-1 PV ami-8186f6ee Launch Stack
HVM ami-3d89f952 Launch Stack
sa-east-1 PV ami-33f1905f Launch Stack
HVM ami-adf091c1 Launch Stack
ap-southeast-2 PV ami-59202d3a Launch Stack
HVM ami-d2232eb1 Launch Stack
ap-southeast-1 PV ami-2fa2104c Launch Stack
HVM ami-c7a210a4 Launch Stack
us-east-1 PV ami-78359b6e Launch Stack
HVM ami-55339d43 Launch Stack
us-east-2 PV ami-6b57730e Launch Stack
HVM ami-23527646 Launch Stack
us-west-2 PV ami-71ef6611 Launch Stack
HVM ami-70ef6610 Launch Stack
us-west-1 PV ami-4c28702c Launch Stack
HVM ami-bf2870df Launch Stack
eu-west-1 PV ami-f0fbcc96 Launch Stack
HVM ami-79fccb1f Launch Stack
eu-west-2 PV ami-c7b3a6a3 Launch Stack
HVM ami-62b1a406 Launch Stack

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

Ignition config

Container Linux allows you to configure machine parameters, configure networking, launch systemd units on startup, and more via Ignition. Head over to the docs to learn about the supported features.

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

As an example, this config will configure and start etcd:

This is the human-readable config file. This should not be immediately passed to Container Linux. Learn more.
# This config is meant to be consumed by the config transpiler, which will
# generate the corresponding Ignition config. Do not pass this config directly
# to instances of Container Linux.

systemd:
  units:
    - name: etcd2.service
      enable: true
      dropins:
        - name: metadata.conf
          contents: |
            [Unit]
            Requires=coreos-metadata.service
            After=coreos-metadata.service

            [Service]
            EnvironmentFile=/run/metadata/coreos
            ExecStart=
            ExecStart=/usr/bin/etcd2 \
                --advertise-client-urls=http://${COREOS_EC2_IPV4_LOCAL}:2379 \
                --initial-advertise-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \
                --listen-client-urls=http://0.0.0.0:2379 \
                --listen-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \
                --discovery=https://discovery.etcd.io/<token>
This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
{
  "ignition": {
    "version": "2.0.0",
    "config": {}
  },
  "storage": {},
  "systemd": {
    "units": [
      {
        "name": "etcd2.service",
        "enable": true,
        "dropins": [
          {
            "name": "metadata.conf",
            "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/bin/etcd2 \\\n    --advertise-client-urls=http://${COREOS_EC2_IPV4_LOCAL}:2379 \\\n    --initial-advertise-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \\\n    --listen-client-urls=http://0.0.0.0:2379 \\\n    --listen-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \\\n    --discovery=https://discovery.etcd.io/\u003ctoken\u003e"
          }
        ]
      }
    ]
  },
  "networkd": {},
  "passwd": {}
}

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 Ignition config to format and mount the first ephemeral disk, xvdb, on most instance types:

This is the human-readable config file. This should not be immediately passed to Container Linux. Learn more.
# This config is meant to be consumed by the config transpiler, which will
# generate the corresponding Ignition config. Do not pass this config directly
# to instances of Container Linux.

storage:
  filesystems:
    - mount:
        device: /dev/xvdb
        format: ext4
        create:

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

        [Install]
        RequiredBy=local-fs.target
This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
{
  "ignition": {
    "version": "2.0.0",
    "config": {}
  },
  "storage": {
    "filesystems": [
      {
        "mount": {
          "device": "/dev/xvdb",
          "format": "ext4"
        }
      }
    ]
  },
  "systemd": {
    "units": [
      {
        "name": "media-ephemeral.mount",
        "enable": true,
        "contents": "[Mount]\nWhat=/dev/xvdb\nWhere=/media/ephemeral\nType=ext4\n\n[Install]\nRequiredBy=local-fs.target"
      }
    ]
  },
  "networkd": {},
  "passwd": {}
}

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

Adding more machines

To add more instances to the cluster, just launch more with the same Ignition 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

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 Ignition config in order to log in.

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

ssh core@<ip address>

Optionally, you may want to configure your ssh-agent to more easily run fleet commands.

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-f8d67cee 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][etcd-docs] and [Docker][docker-docs] 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 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: coreos-testing
    • Description: 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 "coreos-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-f8d67cee.
  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. ```container-linux-config systemd: units: - name: etcd2.service enable: true dropins: - name: cluster.conf # 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 contents: | [Unit] Requires=coreos-metadata.service After=coreos-metadata.service [Service] EnvironmentFile=/run/metadata/coreos ExecStart= ExecStart=/usr/bin/etcd2 \ --advertise-client-urls=http://${COREOS_EC2_IPV4_PUBLIC}:2379 \ --initial-advertise-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \ --listen-client-urls=http://0.0.0.0:2379 \ --listen-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \ --discovery=https://discovery.etcd.io/ - name: fleet.service enable: true ``` Back in the EC2 dashboard, paste this information verbatim into the "User Data" field.
    • Paste link into "User Data"
    • "Continue"
    </li>
  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
    • "coreos-testing" as above.
    • "Continue"
  9. Launch!
  10. </ol> </div>

    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-9f43fb89.
    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. ```container-linux-config systemd: units: - name: etcd2.service enable: true dropins: - name: cluster.conf # 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 contents: | [Unit] Requires=coreos-metadata.service After=coreos-metadata.service [Service] EnvironmentFile=/run/metadata/coreos ExecStart= ExecStart=/usr/bin/etcd2 \ --advertise-client-urls=http://${COREOS_EC2_IPV4_PUBLIC}:2379 \ --initial-advertise-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \ --listen-client-urls=http://0.0.0.0:2379 \ --listen-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \ --discovery=https://discovery.etcd.io/ - name: fleet.service enable: true ``` Back in the EC2 dashboard, paste this information verbatim into the "User Data" field.
      • Paste link into "User Data"
      • "Continue"
      </li>
    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
      • "coreos-testing" as above.
      • "Continue"
    9. Launch!
    10. </ol> </div>

      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-78359b6e.
      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. ```container-linux-config systemd: units: - name: etcd2.service enable: true dropins: - name: cluster.conf # 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 contents: | [Unit] Requires=coreos-metadata.service After=coreos-metadata.service [Service] EnvironmentFile=/run/metadata/coreos ExecStart= ExecStart=/usr/bin/etcd2 \ --advertise-client-urls=http://${COREOS_EC2_IPV4_PUBLIC}:2379 \ --initial-advertise-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \ --listen-client-urls=http://0.0.0.0:2379 \ --listen-peer-urls=http://${COREOS_EC2_IPV4_LOCAL}:2380 \ --discovery=https://discovery.etcd.io/ - name: fleet.service enable: true ``` Back in the EC2 dashboard, paste this information verbatim into the "User Data" field.
        • Paste link into "User Data"
        • "Continue"
        </li>
      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
        • "coreos-testing" as above.
        • "Continue"
      9. Launch!
      10. </ol> </div> </div> </div> ## Using CoreOS Container Linux Now that you have a machine booted it is time to play around. Check out the [Container Linux Quickstart](quickstart.html) guide or dig into [more specific topics](https://coreos.com/docs). [coreos-user]: https://groups.google.com/forum/#!forum/coreos-user [docker-docs]: https://docs.docker.io [etcd-docs]: https://github.com/coreos/etcd/tree/master/Documentation [irc]: irc://irc.freenode.org:6667/#coreos