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

View as json feed
EC2 Region AMI Type AMI ID
ap-northeast-1 PV ami-0df2d11a496db66fb
HVM ami-01d20d68c856200cc
ap-northeast-2 HVM ami-0ea339e5e165e43c4
ap-south-1 HVM ami-0bebdd4e8932c154d
ap-southeast-1 PV ami-05843d9edbb283541
HVM ami-0a3341bbce476915c
ap-southeast-2 PV ami-0b06ef2826ef51765
HVM ami-00cb14d266f659be8
ca-central-1 HVM ami-06ba7ae76a29b0307
cn-north-1 PV ami-0b30870cdabcf53d5
HVM ami-0ce0b2dd41ec795a0
cn-northwest-1 HVM ami-0b48231d24b928c4a
eu-central-1 PV ami-0efd7da2eb13f612b
HVM ami-03b963fa4f08cf8b6
eu-west-1 PV ami-056aa6bbbeeb4ae52
HVM ami-063d7a06c4327e83f
eu-west-2 HVM ami-0e1f071f3af6a8e60
eu-west-3 HVM ami-0833c2963dc5ce4f5
sa-east-1 PV ami-0a1d36b052b1cba46
HVM ami-0ea50cd9cb9d39e9c
us-east-1 PV ami-00f30939b54817054
HVM ami-098f6c01449df4551
us-east-2 HVM ami-0dc18dd6376f292b4
us-gov-west-1 PV ami-93be25f2
HVM ami-edaf348c
us-west-1 PV ami-01023003e83a5cc44
HVM ami-03f0684d3851c54fe
us-west-2 PV ami-0d8c61f1e9517a9e9
HVM ami-026bdbf74b0fb01b8

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

View as json feed
EC2 Region AMI Type AMI ID
ap-northeast-1 PV ami-03620b047f1abddfc
HVM ami-086eb64b7f4485a72
ap-northeast-2 HVM ami-085e4381942bede7d
ap-south-1 HVM ami-0e920ea4c7e29a7ed
ap-southeast-1 PV ami-06288d6d92925d99f
HVM ami-0b47d43598dba794f
ap-southeast-2 PV ami-0bd818523947fb872
HVM ami-0609bb67692e98973
ca-central-1 HVM ami-0a984ec3ead59581c
cn-north-1 PV ami-0253e9c990f50fbae
HVM ami-00307a08b617fb95f
cn-northwest-1 HVM ami-0c0a607177f68f8c4
eu-central-1 PV ami-04712da793b52e462
HVM ami-0b088568a857b7c27
eu-west-1 PV ami-0d9ae8e150fb07db3
HVM ami-099b2d1bdd27b4649
eu-west-2 HVM ami-02de9d47add3bab7c
eu-west-3 HVM ami-0b8c0daca01d23eaa
sa-east-1 PV ami-042f154c1158c2734
HVM ami-09ffd65c1a16012de
us-east-1 PV ami-09db813f5ab5909c8
HVM ami-08eda98e6fe1f83d6
us-east-2 HVM ami-093e794c03f1534e4
us-gov-west-1 PV ami-51dd4430
HVM ami-98db42f9
us-west-1 PV ami-02fa2648a4e363a96
HVM ami-0a86d340ea7fde077
us-west-2 PV ami-05da9819ce9ed9159
HVM ami-02dea79d6a7f53d15

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-098f6c01449df4551 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-098f6c01449df4551.
  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-06b2c0dde66c39143.
    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-08eda98e6fe1f83d6.
    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).