Installing CoreOS Container Linux to disk

Install script

There is a simple installer that will destroy everything on the given target disk and install Container Linux. Essentially it downloads an image, verifies it with gpg, and then copies it bit for bit to disk. An installation requires at least 8 GB of usable space on the device.

The script is self-contained and located on GitHub here and can be run from any Linux distribution. You cannot normally install Container Linux to the same device that is currently booted. However, the Container Linux ISO or any Linux liveCD will allow Container Linux to install to a non-active device.

If you boot Container Linux via PXE, the install script is already installed. By default the install script will attempt to install the same version and channel that was PXE-booted:

coreos-install -d /dev/sda

If you are using the ISO with VMware, first sudo to root:

sudo su - root

Then install as you would with the PXE booted system, but be sure to include user information, especially an SSH key, in a Container Linux Config, or else you will not be able to log into your Container Linux instance.

coreos-install -d /dev/sda -i ignition.json

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

If you want to ensure you are installing the latest alpha version, use the -C option:

coreos-install -d /dev/sda -C alpha

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

If you want to ensure you are installing the latest beta version, use the -C option:

coreos-install -d /dev/sda -C beta

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.

If you want to ensure you are installing the latest stable version, use the -C option:

coreos-install -d /dev/sda -C stable

For reference here are the rest of the coreos-install options:

-d DEVICE   Install Container Linux to the given device.
-V VERSION  Version to install (e.g. current)
-C CHANNEL  Release channel to use (e.g. beta)
-o OEM      OEM type to install (e.g. openstack)
-c CLOUD    Insert a cloud-init config to be executed on boot.
-i IGNITION Insert an Ignition config to be executed on boot.
-t TMPDIR   Temporary location with enough space to download images.
-v          Super verbose, for debugging.
-b BASEURL  URL to the image mirror

Container Linux Configs

By default there isn't a password or any other way to log into a fresh Container Linux system. The easiest way to configure accounts, add systemd units, and more is via Container Linux Configs. Jump over to the docs to learn about the supported features.

After using the Container Linux Config Transpiler to produce an Ignition config, the installation script will process your ignition.json file specified with the -i flag and use it when the installation is booted.

A Container Linux Config that specifies an SSH key for the core user but doesn't use any other parameters looks like:

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.

passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq.......
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": {},
  "networkd": {},
  "passwd": {
    "users": [
      {
        "name": "core",
        "sshAuthorizedKeys": [
          "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq......."
        ]
      }
    ]
  }
}

Note: The {PRIVATE_IPV4} and {PUBLIC_IPV4} substitution variables referenced in other documents are not supported on libvirt.

To start the installation script with a reference to our Ignition config, run:

coreos-install -d /dev/sda -C stable -i ~/ignition.json

Advanced Container Linux Config example

This example will configure Container Linux components: etcd and flannel. You have to substitute <PEER_ADDRESS> to your host's IP or DNS address.

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.

passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq.......
etcd:
  # 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>
  advertise_client_urls: http://<PEER_ADDRESS>:2379,http://<PEER_ADDRESS>:4001
  initial_advertise_peer_urls: http://<PEER_ADDRESS>: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,http://0.0.0.0:4001
  listen_peer_urls: http://<PEER_ADDRESS>:2380
systemd:
  units:
    - name: flanneld.service
      enable: true
      dropins:
      - name: 50-network-config.conf
        contents: |
          [Service]
          ExecStartPre=/usr/bin/etcdctl set /coreos.com/network/config '{"Network":"10.1.0.0/16", "Backend": {"Type": "vxlan"}}'
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": "[Service]\nExecStart=\nExecStart=/usr/lib/coreos/etcd-wrapper $ETCD_OPTS \\\n  --listen-peer-urls=\"http://\u003cPEER_ADDRESS\u003e:2380\" \\\n  --listen-client-urls=\"http://0.0.0.0:2379,http://0.0.0.0:4001\" \\\n  --initial-advertise-peer-urls=\"http://\u003cPEER_ADDRESS\u003e:2380\" \\\n  --advertise-client-urls=\"http://\u003cPEER_ADDRESS\u003e:2379,http://\u003cPEER_ADDRESS\u003e:4001\" \\\n  --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\""
          }
        ]
      },
      {
        "name": "flanneld.service",
        "enable": true,
        "dropins": [
          {
            "name": "50-network-config.conf",
            "contents": "[Service]\nExecStartPre=/usr/bin/etcdctl set /coreos.com/network/config '{\"Network\":\"10.1.0.0/16\", \"Backend\": {\"Type\": \"vxlan\"}}'"
          }
        ]
      }
    ]
  },
  "networkd": {},
  "passwd": {
    "users": [
      {
        "name": "core",
        "sshAuthorizedKeys": [
          "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq......."
        ]
      }
    ]
  }
}

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.