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

View as json feed
EC2 Region AMI Type AMI ID
ap-northeast-1 PV ami-0e3a0f208cafea4a4
HVM ami-0ab04ea7c277456a5
ap-northeast-2 HVM ami-03732fd4762f02a79
ap-south-1 HVM ami-0a63993ace551da38
ap-southeast-1 PV ami-0af5633e51fdb05ee
HVM ami-071e9d348cf71c0d5
ap-southeast-2 PV ami-0204537854e119cec
HVM ami-0040c81165c044604
ca-central-1 HVM ami-01c3f705abf36c7c7
cn-north-1 PV ami-0b0f092f38d6dc999
HVM ami-036ec68decafe5578
cn-northwest-1 HVM ami-094575891bc00a476
eu-central-1 PV ami-0ffed1009ae10d5c3
HVM ami-03a59e011fb203060
eu-north-1 HVM ami-0f048df0b56267922
eu-west-1 PV ami-0e276db43db37e2ba
HVM ami-0353b1d30560fd585
eu-west-2 HVM ami-0ab8b4db06378a8ad
eu-west-3 HVM ami-040f612797df2f162
sa-east-1 PV ami-02419edbbbf517886
HVM ami-0544257d13a7a8456
us-east-1 PV ami-0bdf29bc1950eed10
HVM ami-01b3a26e91d3218a4
us-east-2 HVM ami-01a0a4e19e2f90126
us-gov-east-1 HVM ami-03434dbb1863d2dad
us-gov-west-1 PV ami-ffa2d49e
HVM ami-01b1c760
us-west-1 PV ami-04d50b7b20768c621
HVM ami-049477cd57eaeff54
us-west-2 PV ami-0aa2b262955774288
HVM ami-0a9654ab89366ebce

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

View as json feed
EC2 Region AMI Type AMI ID
ap-northeast-1 PV ami-0e73b03b4618a01b8
HVM ami-0d3a9785820124591
ap-northeast-2 HVM ami-03230b2fa6af112bf
ap-south-1 HVM ami-0b85fd1356963d2ee
ap-southeast-1 PV ami-02ce7fedf82524d74
HVM ami-0f8a9aa9857d8af7e
ap-southeast-2 PV ami-09abb449143dcee62
HVM ami-0e87752a1d331823a
ca-central-1 HVM ami-0c0100bac23bb1d39
cn-north-1 PV ami-0312487c765c2ae3c
HVM ami-01e99c7e0a343d325
cn-northwest-1 HVM ami-0773341917796083a
eu-central-1 PV ami-03dca803621ba56df
HVM ami-012abdf0d2781f0a5
eu-north-1 HVM ami-09fbda19ac2fc6c3f
eu-west-1 PV ami-0c5c18bab9e57abec
HVM ami-01f5fbceb7a9fa4d0
eu-west-2 HVM ami-069966bea0809e21d
eu-west-3 HVM ami-0194c504244182155
sa-east-1 PV ami-0b9768ca5a526da2d
HVM ami-0cd830cc037613a7d
us-east-1 PV ami-06200cebbb5eb506f
HVM ami-08e58b93705fb503f
us-east-2 HVM ami-03172282aaa2899be
us-gov-east-1 HVM ami-0ff9e298ea0bacf53
us-gov-west-1 PV ami-e9f49f88
HVM ami-e7f59e86
us-west-1 PV ami-0fe069c504547db88
HVM ami-08d3e245ebf4d560f
us-west-2 PV ami-08e9621af018d03ad
HVM ami-0a4f49b2488e15346

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-01b3a26e91d3218a4 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-01b3a26e91d3218a4.
  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-07f02a1bce260e853.
    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-08e58b93705fb503f.
    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).