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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-9ae39f77 Launch Stack
HVM ami-e9e69a04 Launch Stack
ap-northeast-2 PV ami-030d112cf35135234 Launch Stack
HVM ami-043379220879549ed Launch Stack
ap-south-1 PV ami-0b8969ad4ab548950 Launch Stack
HVM ami-04f770c1105f7e224 Launch Stack
ap-southeast-1 PV ami-5bf8bab1 Launch Stack
HVM ami-2ff5b7c5 Launch Stack
ap-southeast-2 PV ami-31d17153 Launch Stack
HVM ami-01d07063 Launch Stack
ca-central-1 PV ami-0263ee66 Launch Stack
HVM ami-d66be6b2 Launch Stack
cn-north-1 PV ami-aeea32c3 Launch Stack
HVM ami-adea32c0 Launch Stack
cn-northwest-1 HVM ami-77607715 Launch Stack
eu-central-1 PV ami-ab9b9440 Launch Stack
HVM ami-7f9b9494 Launch Stack
eu-west-1 PV ami-0bcabf1e251306012 Launch Stack
HVM ami-0ca694025112d1ca7 Launch Stack
eu-west-2 PV ami-eb85708c Launch Stack
HVM ami-f0837697 Launch Stack
eu-west-3 HVM ami-0cd6efe9275536d0d Launch Stack
sa-east-1 PV ami-058c98a290d62ff1a Launch Stack
HVM ami-0f189b21710800d96 Launch Stack
us-east-1 PV ami-7dd8c402 Launch Stack
HVM ami-b1213dce Launch Stack
us-east-2 PV ami-07e73f275c49d888c Launch Stack
HVM ami-0073ca2f5e943946a Launch Stack
us-gov-west-1 PV ami-d6f26eb7 Launch Stack
HVM ami-26ea7647 Launch Stack
us-west-1 PV ami-54947b37 Launch Stack
HVM ami-df957abc Launch Stack
us-west-2 PV ami-bfe6c2c7 Launch Stack
HVM ami-ba1a3ec2 Launch Stack

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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-05f28ee8 Launch Stack
HVM ami-c4dda129 Launch Stack
ap-northeast-2 PV ami-0541c20a7682a3d7c Launch Stack
HVM ami-06ec8dbb3f2952985 Launch Stack
ap-south-1 PV ami-095e94db17de24eaa Launch Stack
HVM ami-0b3107968a440d4a2 Launch Stack
ap-southeast-1 PV ami-d5fab83f Launch Stack
HVM ami-92f7b578 Launch Stack
ap-southeast-2 PV ami-b1cd6dd3 Launch Stack
HVM ami-bbce6ed9 Launch Stack
ca-central-1 PV ami-ad64e9c9 Launch Stack
HVM ami-2c61ec48 Launch Stack
cn-north-1 PV ami-acea32c1 Launch Stack
HVM ami-abea32c6 Launch Stack
cn-northwest-1 HVM ami-c26f78a0 Launch Stack
eu-central-1 PV ami-97e9e67c Launch Stack
HVM ami-caeee121 Launch Stack
eu-west-1 PV ami-06cec1ec0e8a45e96 Launch Stack
HVM ami-0518e1ac70d8a3389 Launch Stack
eu-west-2 PV ami-ec85708b Launch Stack
HVM ami-609b6e07 Launch Stack
eu-west-3 HVM ami-0571e6abe36c0b940 Launch Stack
sa-east-1 PV ami-001d6a517cf1b88a5 Launch Stack
HVM ami-056d3c5af8a4c0990 Launch Stack
us-east-1 PV ami-87dfc3f8 Launch Stack
HVM ami-1c213d63 Launch Stack
us-east-2 PV ami-03eb70dbd90f85103 Launch Stack
HVM ami-0a0d729dc60b8e386 Launch Stack
us-gov-west-1 PV ami-cdf06cac Launch Stack
HVM ami-9cc65afd Launch Stack
us-west-1 PV ami-e7967984 Launch Stack
HVM ami-21957a42 Launch Stack
us-west-2 PV ami-cee4c0b6 Launch Stack
HVM ami-71e4c009 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 1800.6.0.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-e8dea205 Launch Stack
HVM ami-e2dca00f Launch Stack
ap-northeast-2 PV ami-08871d16d557a6aeb Launch Stack
HVM ami-04030c62eff91ed37 Launch Stack
ap-south-1 PV ami-00f7eba860b4fe72e Launch Stack
HVM ami-0a40e2443e565f3f6 Launch Stack
ap-southeast-1 PV ami-b5f8ba5f Launch Stack
HVM ami-6ef9bb84 Launch Stack
ap-southeast-2 PV ami-facf6f98 Launch Stack
HVM ami-e8d0708a Launch Stack
ca-central-1 PV ami-ae64e9ca Launch Stack
HVM ami-4560ed21 Launch Stack
cn-north-1 PV ami-65ec3408 Launch Stack
HVM ami-afea32c2 Launch Stack
cn-northwest-1 HVM ami-7b607719 Launch Stack
eu-central-1 PV ami-b0959a5b Launch Stack
HVM ami-879b946c Launch Stack
eu-west-1 PV ami-071e720f28e4a7457 Launch Stack
HVM ami-012afb51d9c2d918f Launch Stack
eu-west-2 PV ami-758c7912 Launch Stack
HVM ami-289b6e4f Launch Stack
eu-west-3 HVM ami-0b9727badec366ad9 Launch Stack
sa-east-1 PV ami-0aabe44672435f9ed Launch Stack
HVM ami-0b098d9d561172f16 Launch Stack
us-east-1 PV ami-a5fee2da Launch Stack
HVM ami-b8ccd0c7 Launch Stack
us-east-2 PV ami-05465556e2add9edb Launch Stack
HVM ami-04d978e741ee88c5d Launch Stack
us-gov-west-1 PV ami-c3f26ea2 Launch Stack
HVM ami-9dc65afc Launch Stack
us-west-1 PV ami-7e917e1d Launch Stack
HVM ami-55937c36 Launch Stack
us-west-2 PV ami-b7e2c6cf Launch Stack
HVM ami-2de0c455 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-b1213dce 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-b1213dce.
  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-1c213d63.
    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-b8ccd0c7.
    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).