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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-1b824b7d Launch Stack
HVM ami-ff834a99 Launch Stack
ap-northeast-2 PV ami-3472a95a Launch Stack
HVM ami-c071aaae Launch Stack
ap-south-1 PV ami-0d8dcb62 Launch Stack
HVM ami-6e8cca01 Launch Stack
ap-southeast-1 PV ami-02473161 Launch Stack
HVM ami-a44630c7 Launch Stack
ap-southeast-2 PV ami-c128cea3 Launch Stack
HVM ami-962accf4 Launch Stack
ca-central-1 PV ami-ef99208b Launch Stack
HVM ami-369d2452 Launch Stack
cn-north-1 PV ami-6792410a Launch Stack
HVM ami-d49241b9 Launch Stack
eu-central-1 PV ami-e4da6b8b Launch Stack
HVM ami-8edb6ae1 Launch Stack
eu-west-1 PV ami-e15b9798 Launch Stack
HVM ami-6654981f Launch Stack
eu-west-2 PV ami-95cbd8f1 Launch Stack
HVM ami-a0c4d7c4 Launch Stack
sa-east-1 PV ami-53f8853f Launch Stack
HVM ami-90f885fc Launch Stack
us-east-1 PV ami-4d2bc537 Launch Stack
HVM ami-7229c708 Launch Stack
us-east-2 PV ami-eebb998b Launch Stack
HVM ami-b0ba98d5 Launch Stack
us-gov-west-1 PV ami-8c1a99ed Launch Stack
HVM ami-8d1a99ec Launch Stack
us-west-1 PV ami-067a4b66 Launch Stack
HVM ami-a37c4dc3 Launch Stack
us-west-2 PV ami-03b8447b Launch Stack
HVM ami-4fb94537 Launch Stack

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

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-70814816 Launch Stack
HVM ami-a68d44c0 Launch Stack
ap-northeast-2 PV ami-f57ca79b Launch Stack
HVM ami-2c7ca742 Launch Stack
ap-south-1 PV ami-7a8dcb15 Launch Stack
HVM ami-2f8fc940 Launch Stack
ap-southeast-1 PV ami-c6592fa5 Launch Stack
HVM ami-0e5d2b6d Launch Stack
ap-southeast-2 PV ami-1b28ce79 Launch Stack
HVM ami-1328ce71 Launch Stack
ca-central-1 PV ami-ec992088 Launch Stack
HVM ami-b79a23d3 Launch Stack
cn-north-1 PV ami-18934075 Launch Stack
HVM ami-1b934076 Launch Stack
eu-central-1 PV ami-b9db6ad6 Launch Stack
HVM ami-b1d869de Launch Stack
eu-west-1 PV ami-e55e929c Launch Stack
HVM ami-c25f93bb Launch Stack
eu-west-2 PV ami-71c7d415 Launch Stack
HVM ami-3bc5d65f Launch Stack
sa-east-1 PV ami-8982ffe5 Launch Stack
HVM ami-47ff822b Launch Stack
us-east-1 PV ami-052ec07f Launch Stack
HVM ami-79d33d03 Launch Stack
us-east-2 PV ami-3fba985a Launch Stack
HVM ami-beb597db Launch Stack
us-gov-west-1 PV ami-5f15963e Launch Stack
HVM ami-c41b98a5 Launch Stack
us-west-1 PV ami-907d4cf0 Launch Stack
HVM ami-8e7a4bee Launch Stack
us-west-2 PV ami-fcbd4184 Launch Stack
HVM ami-52bd412a 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 1465.8.0.

View as json feed
EC2 Region AMI Type AMI ID CloudFormation
ap-northeast-1 PV ami-388f465e Launch Stack
HVM ami-e98c458f Launch Stack
ap-northeast-2 PV ami-817ca7ef Launch Stack
HVM ami-2d7ca743 Launch Stack
ap-south-1 PV ami-798dcb16 Launch Stack
HVM ami-d18dcbbe Launch Stack
ap-southeast-1 PV ami-8a5b2de9 Launch Stack
HVM ami-3f5b2d5c Launch Stack
ap-southeast-2 PV ami-3429cf56 Launch Stack
HVM ami-b02accd2 Launch Stack
ca-central-1 PV ami-2e9a234a Launch Stack
HVM ami-e899208c Launch Stack
cn-north-1 PV ami-19934074 Launch Stack
HVM ami-6292410f Launch Stack
eu-central-1 PV ami-f9d86996 Launch Stack
HVM ami-e1d9688e Launch Stack
eu-west-1 PV ami-1a589463 Launch Stack
HVM ami-40589439 Launch Stack
eu-west-2 PV ami-70c7d414 Launch Stack
HVM ami-6cc6d508 Launch Stack
sa-east-1 PV ami-61fc810d Launch Stack
HVM ami-42ff822e Launch Stack
us-east-1 PV ami-bbd13fc1 Launch Stack
HVM ami-e2d33d98 Launch Stack
us-east-2 PV ami-c0ba98a5 Launch Stack
HVM ami-5ab7953f Launch Stack
us-gov-west-1 PV ami-581a9939 Launch Stack
HVM ami-c31b98a2 Launch Stack
us-west-1 PV ami-277a4b47 Launch Stack
HVM ami-a57d4cc5 Launch Stack
us-west-2 PV ami-85bd41fd Launch Stack
HVM ami-82bd41fa 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-4d2bc537 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-4d2bc537.
  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-052ec07f.
  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-bbd13fc1.
  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.