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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-70a79517 Launch Stack
HVM ami-a3a193c4 Launch Stack
ap-northeast-2 PV ami-25e5384b Launch Stack
HVM ami-dde439b3 Launch Stack
ap-south-1 PV ami-fe077a91 Launch Stack
HVM ami-ea047985 Launch Stack
ap-southeast-1 PV ami-7e30b51d Launch Stack
HVM ami-b332b7d0 Launch Stack
ap-southeast-2 PV ami-342a2057 Launch Stack
HVM ami-992822fa Launch Stack
ca-central-1 PV ami-1f833f7b Launch Stack
HVM ami-267cc042 Launch Stack
cn-north-1 PV ami-d85680b5 Launch Stack
HVM ami-a42bfdc9 Launch Stack
eu-central-1 PV ami-045f816b Launch Stack
HVM ami-0421ff6b Launch Stack
eu-west-1 PV ami-263a3440 Launch Stack
HVM ami-0c3a346a Launch Stack
eu-west-2 PV ami-5e47503a Launch Stack
HVM ami-9f4552fb Launch Stack
sa-east-1 PV ami-ef117e83 Launch Stack
HVM ami-ab137cc7 Launch Stack
us-east-1 PV ami-750f7963 Launch Stack
HVM ami-36007620 Launch Stack
us-east-2 PV ami-4fc5e22a Launch Stack
HVM ami-9bc4e3fe Launch Stack
us-gov-west-1 PV ami-cc1397ad Launch Stack
HVM ami-9d1397fc Launch Stack
us-west-1 PV ami-b8dff9d8 Launch Stack
HVM ami-65def805 Launch Stack
us-west-2 PV ami-f2aecb92 Launch Stack
HVM ami-71acc911 Launch Stack

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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-9cf5cffb Launch Stack
HVM ami-d0f1cbb7 Launch Stack
ap-northeast-2 PV ami-0a944864 Launch Stack
HVM ami-bb9a46d5 Launch Stack
ap-south-1 PV ami-9ec6bbf1 Launch Stack
HVM ami-32c3be5d Launch Stack
ap-southeast-1 PV ami-d99214ba Launch Stack
HVM ami-879315e4 Launch Stack
ap-southeast-2 PV ami-54657137 Launch Stack
HVM ami-01677362 Launch Stack
ca-central-1 PV ami-b05ae6d4 Launch Stack
HVM ami-2c56ea48 Launch Stack
cn-north-1 PV ami-ab6eb8c6 Launch Stack
HVM ami-ee62b483 Launch Stack
eu-central-1 PV ami-fd60b892 Launch Stack
HVM ami-2561b94a Launch Stack
eu-west-1 PV ami-45475323 Launch Stack
HVM ami-8b4753ed Launch Stack
eu-west-2 PV ami-610a1d05 Launch Stack
HVM ami-0c081f68 Launch Stack
sa-east-1 PV ami-0f9df363 Launch Stack
HVM ami-019df36d Launch Stack
us-east-1 PV ami-f1b3f2e7 Launch Stack
HVM ami-02b0f114 Launch Stack
us-east-2 PV ami-3f6d4b5a Launch Stack
HVM ami-b26d4bd7 Launch Stack
us-gov-west-1 PV ami-a7f97ec6 Launch Stack
HVM ami-29f97e48 Launch Stack
us-west-1 PV ami-61290901 Launch Stack
HVM ami-052a0a65 Launch Stack
us-west-2 PV ami-b14e2ed1 Launch Stack
HVM ami-234c2c43 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 1353.7.0.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-1885af7f Launch Stack
HVM ami-8284aee5 Launch Stack
ap-northeast-2 PV ami-2661b348 Launch Stack
HVM ami-b974a6d7 Launch Stack
ap-south-1 PV ami-5f483a30 Launch Stack
HVM ami-2a403245 Launch Stack
ap-southeast-1 PV ami-a9873cca Launch Stack
HVM ami-67863d04 Launch Stack
ap-southeast-2 PV ami-14d9d177 Launch Stack
HVM ami-1fc7cf7c Launch Stack
ca-central-1 PV ami-58b60a3c Launch Stack
HVM ami-30b10d54 Launch Stack
cn-north-1 PV ami-6e36e003 Launch Stack
HVM ami-6a09df07 Launch Stack
eu-central-1 PV ami-2104d84e Launch Stack
HVM ami-d60ad6b9 Launch Stack
eu-west-1 PV ami-cbcdcdad Launch Stack
HVM ami-0bcbcb6d Launch Stack
eu-west-2 PV ami-a39581c7 Launch Stack
HVM ami-7eeafe1a Launch Stack
sa-east-1 PV ami-eccea380 Launch Stack
HVM ami-a3cda0cf Launch Stack
us-east-1 PV ami-a6a7c2b0 Launch Stack
HVM ami-ad593cbb Launch Stack
us-east-2 PV ami-d62007b3 Launch Stack
HVM ami-102f0875 Launch Stack
us-gov-west-1 PV ami-3ba2265a Launch Stack
HVM ami-6fae2a0e Launch Stack
us-west-1 PV ami-c17255a1 Launch Stack
HVM ami-25735445 Launch Stack
us-west-2 PV ami-d2aa34b2 Launch Stack
HVM ami-e5af3185 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": {
    "version": "2.0.0",
    "config": {}
  },
  "storage": {},
  "systemd": {
    "units": [
      {
        "name": "etcd-member.service",
        "enable": true,
        "dropins": [
          {
            "name": "20-clct-etcd-member.conf",
            "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\""
          }
        ]
      }
    ]
  },
  "networkd": {},
  "passwd": {}
}

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
        create:
          force: false

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": {
    "version": "2.0.0",
    "config": {}
  },
  "storage": {
    "filesystems": [
      {
        "mount": {
          "device": "/dev/xvdb",
          "format": "ext4",
          "create": {}
        }
      }
    ]
  },
  "systemd": {
    "units": [
      {
        "name": "media-ephemeral.mount",
        "enable": true,
        "contents": "[Mount]\nWhat=/dev/xvdb\nWhere=/media/ephemeral\nType=ext4\n\n[Install]\nRequiredBy=local-fs.target"
      }
    ]
  },
  "networkd": {},
  "passwd": {}
}

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-750f7963 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-750f7963.
  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": {
        "version": "2.0.0",
        "config": {}
      },
      "storage": {},
      "systemd": {
        "units": [
          {
            "name": "etcd-member.service",
            "enable": true,
            "dropins": [
              {
                "name": "20-clct-etcd-member.conf",
                "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\""
              }
            ]
          }
        ]
      },
      "networkd": {},
      "passwd": {}
    }
    
    • 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-f1b3f2e7.
  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": {
        "version": "2.0.0",
        "config": {}
      },
      "storage": {},
      "systemd": {
        "units": [
          {
            "name": "etcd-member.service",
            "enable": true,
            "dropins": [
              {
                "name": "20-clct-etcd-member.conf",
                "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\""
              }
            ]
          }
        ]
      },
      "networkd": {},
      "passwd": {}
    }
    
    • 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-a6a7c2b0.
  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": {
        "version": "2.0.0",
        "config": {}
      },
      "storage": {},
      "systemd": {
        "units": [
          {
            "name": "etcd-member.service",
            "enable": true,
            "dropins": [
              {
                "name": "20-clct-etcd-member.conf",
                "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\""
              }
            ]
          }
        ]
      },
      "networkd": {},
      "passwd": {}
    }
    
    • 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.