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 or user mailing list.

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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-c82ee3b7 Launch Stack
HVM ami-246faf5b Launch Stack
ap-northeast-2 PV ami-fdb81293 Launch Stack
HVM ami-8bf05ae5 Launch Stack
ap-south-1 PV ami-61ebc30e Launch Stack
HVM ami-62b39a0d Launch Stack
ap-southeast-1 PV ami-d51014a9 Launch Stack
HVM ami-e6cff59a Launch Stack
ap-southeast-2 PV ami-d476aab6 Launch Stack
HVM ami-1bb66a79 Launch Stack
ca-central-1 PV ami-0873f06c Launch Stack
HVM ami-1152d175 Launch Stack
cn-north-1 PV ami-f8914895 Launch Stack
HVM ami-a49e47c9 Launch Stack
cn-northwest-1 HVM ami-19aabe7b Launch Stack
eu-central-1 PV ami-8508386e Launch Stack
HVM ami-1e3100f5 Launch Stack
eu-west-1 PV ami-d4e5e7ad Launch Stack
HVM ami-84ebebfd Launch Stack
eu-west-2 PV ami-f058b797 Launch Stack
HVM ami-6307e804 Launch Stack
eu-west-3 HVM ami-992091e4 Launch Stack
sa-east-1 PV ami-0a095266 Launch Stack
HVM ami-b591c9d9 Launch Stack
us-east-1 PV ami-fc246083 Launch Stack
HVM ami-cc2a53b3 Launch Stack
us-east-2 PV ami-4c3b0529 Launch Stack
HVM ami-6481be01 Launch Stack
us-gov-west-1 PV ami-3b35a45a Launch Stack
HVM ami-4032a321 Launch Stack
us-west-1 PV ami-aa8367c9 Launch Stack
HVM ami-0803e66b Launch Stack
us-west-2 PV ami-862061fe Launch Stack
HVM ami-f623628e Launch Stack

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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-0e34fb71 Launch Stack
HVM ami-1636f969 Launch Stack
ap-northeast-2 PV ami-b763c9d9 Launch Stack
HVM ami-1062c87e Launch Stack
ap-south-1 PV ami-fa7f5495 Launch Stack
HVM ami-f57f549a Launch Stack
ap-southeast-1 PV ami-a3e1e6df Launch Stack
HVM ami-36e1e64a Launch Stack
ap-southeast-2 PV ami-6d17c80f Launch Stack
HVM ami-e11fc083 Launch Stack
ca-central-1 PV ami-240f8c40 Launch Stack
HVM ami-fd0a8999 Launch Stack
cn-north-1 PV ami-ab845dc6 Launch Stack
HVM ami-a8845dc5 Launch Stack
cn-northwest-1 HVM ami-54574036 Launch Stack
eu-central-1 PV ami-48c2f1a3 Launch Stack
HVM ami-040c3fef Launch Stack
eu-west-1 PV ami-bdd1ddc4 Launch Stack
HVM ami-f2d0dc8b Launch Stack
eu-west-2 PV ami-69ee000e Launch Stack
HVM ami-d7907eb0 Launch Stack
eu-west-3 HVM ami-6c12a311 Launch Stack
sa-east-1 PV ami-da9dc6b6 Launch Stack
HVM ami-a793c8cb Launch Stack
us-east-1 PV ami-faf3b385 Launch Stack
HVM ami-88f0b0f7 Launch Stack
us-east-2 PV ami-35f1cf50 Launch Stack
HVM ami-c8f2ccad Launch Stack
us-gov-west-1 PV ami-a0cd5dc1 Launch Stack
HVM ami-a7cd5dc6 Launch Stack
us-west-1 PV ami-860ce8e5 Launch Stack
HVM ami-ac03e7cf Launch Stack
us-west-2 PV ami-154c0e6d Launch Stack
HVM ami-6a420012 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 1745.7.0.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-d633fca9 Launch Stack
HVM ami-ab20efd4 Launch Stack
ap-northeast-2 PV ami-5c6cc632 Launch Stack
HVM ami-e46dc78a Launch Stack
ap-south-1 PV ami-2378534c Launch Stack
HVM ami-807a51ef Launch Stack
ap-southeast-1 PV ami-0ee1e672 Launch Stack
HVM ami-3cded940 Launch Stack
ap-southeast-2 PV ami-d51bc4b7 Launch Stack
HVM ami-961ac5f4 Launch Stack
ca-central-1 PV ami-1b088b7f Launch Stack
HVM ami-f90a899d Launch Stack
cn-north-1 PV ami-c5875ea8 Launch Stack
HVM ami-2a875e47 Launch Stack
cn-northwest-1 HVM ami-c9abbfab Launch Stack
eu-central-1 PV ami-b3dfec58 Launch Stack
HVM ami-d0dcef3b Launch Stack
eu-west-1 PV ami-8ed4d8f7 Launch Stack
HVM ami-1ed8d467 Launch Stack
eu-west-2 PV ami-c8907eaf Launch Stack
HVM ami-40907e27 Launch Stack
eu-west-3 HVM ami-6912a314 Launch Stack
sa-east-1 PV ami-3b9dc657 Launch Stack
HVM ami-619ec50d Launch Stack
us-east-1 PV ami-50f4b42f Launch Stack
HVM ami-f6ecac89 Launch Stack
us-east-2 PV ami-e5f0ce80 Launch Stack
HVM ami-5bf4ca3e Launch Stack
us-gov-west-1 PV ami-58cc5c39 Launch Stack
HVM ami-5fcc5c3e Launch Stack
us-west-1 PV ami-2801e54b Launch Stack
HVM ami-d90ce8ba Launch Stack
us-west-2 PV ami-f0480a88 Launch Stack
HVM ami-662f6d1e Launch Stack

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

Container Linux Configs

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 Container Linux via the Amazon web console or via the EC2 API.

As an example, this Container Linux 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.

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>"
This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
{
  "ignition": {
    "config": {},
    "timeouts": {},
    "version": "2.1.0"
  },
  "networkd": {},
  "passwd": {},
  "storage": {},
  "systemd": {
    "units": [
      {
        "dropins": [
          {
            "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/lib/coreos/etcd-wrapper $ETCD_OPTS \\\n  --listen-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n  --listen-client-urls=\"http://0.0.0.0:2379\" \\\n  --initial-advertise-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n  --advertise-client-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2379\" \\\n  --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\"",
            "name": "20-clct-etcd-member.conf"
          }
        ],
        "enable": true,
        "name": "etcd-member.service"
      }
    ]
  }
}

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:

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

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

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>

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-cc2a53b3 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 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-cc2a53b3.
  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.
    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.
    
              etcd:
                # All options get passed as command line flags to etcd.
                # Any information inside curly braces comes from the machine at boot time.
    
    This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
    {
      "ignition": {
        "config": {},
        "timeouts": {},
        "version": "2.1.0"
      },
      "networkd": {},
      "passwd": {},
      "storage": {},
      "systemd": {}
    }
    
    ` # 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/" ```
    • Paste configuration 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-88f0b0f7.
    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.
      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.
      
            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>"
      
      This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
      {
        "ignition": {
          "config": {},
          "timeouts": {},
          "version": "2.1.0"
        },
        "networkd": {},
        "passwd": {},
        "storage": {},
        "systemd": {
          "units": [
            {
              "dropins": [
                {
                  "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/lib/coreos/etcd-wrapper $ETCD_OPTS \\\n  --listen-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n  --listen-client-urls=\"http://0.0.0.0:2379\" \\\n  --initial-advertise-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n  --advertise-client-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2379\" \\\n  --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\"",
                  "name": "20-clct-etcd-member.conf"
                }
              ],
              "enable": true,
              "name": "etcd-member.service"
            }
          ]
        }
      }
      
      • 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
      • "coreos-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-f6ecac89.
    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.
      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.
      
            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>"
      
      This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
      {
        "ignition": {
          "config": {},
          "timeouts": {},
          "version": "2.1.0"
        },
        "networkd": {},
        "passwd": {},
        "storage": {},
        "systemd": {
          "units": [
            {
              "dropins": [
                {
                  "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/lib/coreos/etcd-wrapper $ETCD_OPTS \\\n  --listen-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n  --listen-client-urls=\"http://0.0.0.0:2379\" \\\n  --initial-advertise-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n  --advertise-client-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2379\" \\\n  --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\"",
                  "name": "20-clct-etcd-member.conf"
                }
              ],
              "enable": true,
              "name": "etcd-member.service"
            }
          ]
        }
      }
      
      • 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
      • "coreos-testing" as above.
      • "Continue"
    9. Launch!
    ```` </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).