Quick Start

If you don't have a CoreOS machine running, check out the guides on running CoreOS on most cloud providers (EC2, Rackspace, GCE), virtualization platforms (Vagrant, VMware, OpenStack, QEMU/KVM) and bare metal servers (PXE, iPXE, ISO, Installer). With any of these guides you will have machines up and running in a few minutes.

It's highly recommended that you set up a cluster of at least 3 machines — it's not as much fun on a single machine. If you don't want to break the bank, Vagrant allows you to run an entire cluster on your laptop. For a cluster to be properly bootstrapped, you have to provide cloud-config via user-data, which is covered in each platform's guide.

CoreOS gives you three essential tools: service discovery, container management and process management. Let's try each of them out.

First, on the client start your user agent by typing: eval $(ssh-agent)

Then, add your private key to the agent by typing: ssh-add

Connect to a CoreOS machine via SSH as the user core. For example, on Amazon, use:

$ ssh -A core@an.ip.compute-1.amazonaws.com
CoreOS (beta)

The -A forwards your ssh-agent to the machine, which is needed for the fleet section of this guide.

If you're using Vagrant, you'll need to connect a bit differently:

$ ssh-add ~/.vagrant.d/insecure_private_key
Identity added: /Users/core/.vagrant.d/insecure_private_key (/Users/core/.vagrant.d/insecure_private_key)
$ vagrant ssh core-01 -- -A
CoreOS (beta)

Service Discovery with etcd

The first building block of CoreOS is service discovery with etcd (docs). Data stored in etcd is distributed across all of your machines running CoreOS. For example, each of your app containers can announce itself to a proxy container, which would automatically know which machines should receive traffic. Building service discovery into your application allows you to add more machines and scale your services seamlessly.

If you used an example cloud-config from a guide linked in the first paragraph, etcd is automatically started on boot.

A good starting point would be something like:

#cloud-config

hostname: coreos0
ssh_authorized_keys:
  - ssh-rsa AAAA...
coreos:
  units:
    - name: etcd.service
      command: start
    - name: fleet.service
      command: start
  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>

In order to get the discovery token, visit https://discovery.etcd.io/new and you will receive a URL including your token. Paste the whole thing into your cloud-config file.

The API is easy to use. From a CoreOS machine, you can simply use curl to set and retrieve a key from etcd:

Set a key message with value Hello world:

curl -L http://127.0.0.1:4001/v2/keys/message -XPUT -d value="Hello world"

Read the value of message back:

curl -L http://127.0.0.1:4001/v2/keys/message

If you followed a guide to set up more than one CoreOS machine, you can SSH into another machine and can retrieve this same value.

More Detailed Information

View Complete Guide Read etcd API Docs

Container Management with docker

The second building block, docker (docs), is where your applications and code run. It is installed on each CoreOS machine. You should make each of your services (web server, caching, database) into a container and connect them together by reading and writing to etcd. You can quickly try out a minimal busybox container in two different ways:

Run a command in the container and then stop it:

docker run busybox /bin/echo hello world

Open a shell prompt inside the container:

docker run -i -t busybox /bin/sh

More Detailed Information

View Complete Guide Read docker Docs

Process Management with fleet

The third building block of CoreOS is fleet, a distributed init system for your cluster. You should use fleet to manage the life cycle of your docker containers.

Fleet works by receiving systemd unit files and scheduling them onto machines in the cluster based on declared conflicts and other preferences encoded in the unit file. Using the fleetctl tool, you can query the status of a unit, remotely access its logs and more.

First, let's construct a simple systemd unit that runs a docker container. Save this as hello.service in the home directory:

hello.service

[Unit]
Description=My Service
After=docker.service

[Service]
TimeoutStartSec=0
ExecStartPre=-/usr/bin/docker kill hello
ExecStartPre=-/usr/bin/docker rm hello
ExecStartPre=/usr/bin/docker pull busybox
ExecStart=/usr/bin/docker run --name hello busybox /bin/sh -c "while true; do echo Hello World; sleep 1; done"
ExecStop=/usr/bin/docker stop hello

The Getting Started with systemd guide explains the format of this file in more detail.

Then load and start the unit:

$ fleetctl load hello.service
Unit hello.service loaded on 8145ebb7.../172.17.8.105
$ fleetctl start hello.service
Unit hello.service launched on 8145ebb7.../172.17.8.105

Your container has been started somewhere on the cluster. To verify the status, run:

$ fleetctl status hello.service
● hello.service - My Service
   Loaded: loaded (/run/fleet/units/hello.service; linked-runtime)
   Active: active (running) since Wed 2014-06-04 19:04:13 UTC; 44s ago
 Main PID: 27503 (bash)
   CGroup: /system.slice/hello.service
           ├─27503 /bin/bash -c /usr/bin/docker start -a hello || /usr/bin/docker run --name hello busybox /bin/sh -c "while true; do echo Hello World; sleep 1; done"
           └─27509 /usr/bin/docker run --name hello busybox /bin/sh -c while true; do echo Hello World; sleep 1; done

Jun 04 19:04:57 core-01 bash[27503]: Hello World
..snip...
Jun 04 19:05:06 core-01 bash[27503]: Hello World

To stop the container, run:

fleetctl destroy hello.service

Fleet has many more features that you can explore in the guides below.

More Detailed Information

View Complete Guide View Getting Started with systemd Guide