Running CoreOS Container Linux on EC2

The current AMIs for all Container Linux channels and EC2 regions are listed below and updated frequently. 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 2205.0.0.

View as json feed
EC2 Region AMI Type AMI ID
ap-northeast-1 PV ami-0a77bebf48fd7e7ed
HVM ami-051df3a486abde061
ap-northeast-2 HVM ami-000c0eaf11d443c9a
ap-south-1 HVM ami-0d4ccabd316702bb8
ap-southeast-1 PV ami-07a5ce6eac6bb7907
HVM ami-0fbd241b0319df7e7
ap-southeast-2 PV ami-0f27b6e0544cd84f1
HVM ami-0a86e7434d0cbb79c
ca-central-1 HVM ami-0f7671bf623845f35
cn-north-1 PV ami-0b2a40c3b5cc71bfb
HVM ami-02bcc773c6cd1ee42
cn-northwest-1 HVM ami-0433581e45bb7960d
eu-central-1 PV ami-047dc0d8a1658bafd
HVM ami-0f09e52ad29ed1b78
eu-north-1 HVM ami-01e0e54077a5cf2d4
eu-west-1 PV ami-01cc6739a077a6c0b
HVM ami-0428c09a26d8fecdf
eu-west-2 HVM ami-09d49fd45968911a7
eu-west-3 HVM ami-087f591a162bcd1ba
sa-east-1 PV ami-0ca745b190c10bd4b
HVM ami-0fb94ce11e68fed3c
us-east-1 PV ami-083f1d2e71174d109
HVM ami-0e713b5dc8e0510f7
us-east-2 HVM ami-08458d9f6f8afdd50
us-gov-east-1 HVM ami-06b47e61237cc0ca7
us-gov-west-1 PV ami-5ea0e63f
HVM ami-c6aee8a7
us-west-1 PV ami-0994da1daed9d4e89
HVM ami-044f84c4a2e39ac27
us-west-2 PV ami-0c60d6a36e54a609c
HVM ami-0c026cc3991699325

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

View as json feed
EC2 Region AMI Type AMI ID
ap-northeast-1 PV ami-09673be92fa59a18c
HVM ami-070d50353dfb032ba
ap-northeast-2 HVM ami-041a583a9761bda64
ap-south-1 HVM ami-083eec4a98ca0396b
ap-southeast-1 PV ami-06b44b502238c091d
HVM ami-0bdf64786279efbbc
ap-southeast-2 PV ami-0cc32476b1b941cf3
HVM ami-0bb7c56044b64aa56
ca-central-1 HVM ami-082a1a74cfc2d2403
cn-north-1 PV ami-0fe0dc6001c982cb6
HVM ami-0d8ca8372e3b0aff4
cn-northwest-1 HVM ami-049ed451bb483d4be
eu-central-1 PV ami-051b84d3e0a89fec0
HVM ami-0cfac31dd01a5f898
eu-north-1 HVM ami-009c476af4072d56a
eu-west-1 PV ami-0898e2390ed497160
HVM ami-053d1b6039e1098d4
eu-west-2 HVM ami-09e2e4b79ea105d0f
eu-west-3 HVM ami-0a409979da233373a
sa-east-1 PV ami-0ef096d9aa2909669
HVM ami-0b2f9ee1da741ad19
us-east-1 PV ami-01d492ec136ec8359
HVM ami-02b51824b39a1d52a
us-east-2 HVM ami-03aa12465ead76468
us-gov-east-1 HVM ami-0dc23aad3fa5a13c9
us-gov-west-1 PV ami-e35b1f82
HVM ami-6f5d190e
us-west-1 PV ami-084c9acb389f1801b
HVM ami-04a1dd7b81fe80e40
us-west-2 PV ami-0108b87fd991ef10e
HVM ami-071f4352a744b29aa

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>

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-0e713b5dc8e0510f7 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-0e713b5dc8e0510f7.
  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": {}
    }
    
    `
    • 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-0565b53f5b9629782.
  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-02b51824b39a1d52a.
  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!
```

Using CoreOS Container Linux

Now that you have a machine booted it is time to play around. Check out the Container Linux Quickstart guide or dig into more specific topics.