A CoreOS development cluster with Vagrant and VirtualBox

Following CoreOS’s instructions on how to set up a development environment in VirtualBox did not work out well for me. Here are the steps I followed to get Container Linux up and running with Vagrant.

At first, I read through the instructions on CoreOS’s website but those turned out to be overly complicated and, at times, inaccurate. I then turned to the official repository’s README file which contained the information I needed to make it all work. However, it wasn’t written in a way that made it easy to find specific information without reading most paragraphs twice or thrice.

This post aims to provide a short and minimalistic guide for you to get a working CoreOS development environment up and running.

Clone the project from GitHub

To get started, clone the coreos/coreos-vagrant repository from Github.

# using SSH
git clone git@github.com:coreos/coreos-vagrant.git
# or HTTPS
git clone https://github.com/coreos/coreos-vagrant.git

Once you’ve cloned the project, move into the project folder.

cd coreos-vagrant

Tweak some Vagrant settings

The Vagrantfile is written so that it will read a config.rb file for any useful parameters. The repository includes a config.rb.sample file you can build your config.rb off of.

cp config.rb.sample config.rb

Open the config.rb file with your favorite text editor and edit the $num_instances variable to define the number of nodes in your CoreOS cluster. If you want 3 nodes, write $num_instances=3.

Further down the file, you can edit other variables to customize VM resources, forwarded ports, shared folders, et cetera, but that is completely optional.

Obtain an etcd discovery token

So that the different nodes in your cluster can be configured to communicate with each other properly, you need an etcd discovery token. You can get one at https://discovery.etcd.io/new?size=X where X is the number of nodes in your cluster.

curl https://discovery.etcd.io/new\?size\=3

Here is what the result should look like, only with a different token at the end:

https://discovery.etcd.io/d0362849eaed24304db7f6c9f23b6faf

Note: You will need to do this again after every vagrant destroy.

Generate your Ignition configuration

CoreOS systems are created using Ignition, so you need to generate your Ignition configuration file.

To do this, you will need to install the Container Linux Config Transpiler. Most distributions have a ct package. If you’re using Arch Linux like me, then you can install the AUR package with yaourt:

yaourt -S ct

The coreos-vagrant repository provides a cl.conf file that you can edit and then transpile into a valid Ignition configuration for this Vagrant environment.

Open the cl.conf file in your editor of choice and find the line that starts with discovery:. You need to replace the URL on that line with the one containing your etcd discovery token. The line should look something like this:

discovery: "https://discovery.etcd.io/d0362849eaed24304db7f6c9f23b6faf"

Save your cl.conf file then use ct to generate your config.ign Inginition configuration file.

ct --platform=vagrant-virtualbox < cl.conf > config.ign

Note: You will need to do this again after every vagrant destroy.

(Optional) Use the stable release of CoreOS

By default, the Vagrantfile will create VMs based on the latest alpha release of CoreOS Container Linux. If you wish to use the latest stable release instead, replace all mention of alpha with stable in your Vagrantfile.

sed -i 's/alpha/stable/' Vagrantfile

This repository originally supported the $update_channel variable in config.rb but this was temporarily removed, creating a mismatch with the official documentation. The maintainers of the project are making changes that made the use of this variable somewhat risky; they will add it back in once everything is stable. If the variable is present when you are reading this, you may simply set it to stable instead of using the command above.

Build your cluster

You can now create your cluster.

vagrant up

Once the cluster is created, connect to your first node.

vagrant ssh core-01

The etcd-member service should be running.

systemctl status etcd-member

Set a key in etcd.

etcdctl set /message "Hello, World!"

If etcd discovery happened properly, you should be able to read the key’s value from all your nodes.

etcdctl get /message

Start using your cluster

Your cluster is ready.

You now have a functioning CoreOS Container Linux cluster set up for you to test things on. Each node has configured and activated. Have fun!

Notes

After preparing this article, I opened up a Pull Request to update the configuration to match the official documentation. It is still pending.