Running CoreOS with Vagrant is the easiest way to bring up a single machine or virtualize an entire cluster on your laptop. Since the true power of CoreOS can be seen with a cluster, we’re going to concentrate on that. Instructions for a single machine can be found towards the end of the guide.

You can direct questions to the IRC channel or mailing list.

Install Vagrant and VirtualBox

Vagrant is a simple-to-use command line virtual machine manager. There are install packages available for Windows, Linux and OSX. Find the latest installer on the Vagrant downloads page. Be sure to get version 1.6.3 or greater.

Vagrant can use either the free VirtualBox provider or the commercial VMware provider. Instructions for both are below. For the VirtualBox provider, version 4.3.10 or greater is required.

Clone Vagrant Repo

Now that you have Vagrant installed you can bring up a CoreOS instance.

The following commands will clone a repository that contains the CoreOS Vagrantfile. This file tells Vagrant where it can find the latest disk image of CoreOS. Vagrant will download the image the first time you attempt to start the VM.

git clone https://github.com/coreos/coreos-vagrant.git

cd coreos-vagrantStarting a Cluster

To start our cluster, we need to provide some config parameters in cloud-config format via the user-data file and set the number of machines in the cluster in config.rb.

Cloud-Config

CoreOS allows you to configure machine parameters, launch systemd units on start-up and more via cloud-config. Jump over to the docs to learn about the supported features. You can provide cloud-config data to your CoreOS Vagrant VM by editing the user-data file inside of the cloned directory. A sample file user-data.sample exists as a base and must be renamed to user-data for it to be processed.

Our cluster will use an etcd discovery URL to bootstrap the cluster of machines and elect an initial etcd leader. Be sure to replace with your own URL from https://discovery.etcd.io/new:

#cloud-config

coreos:

etcd:# generate a new token for each unique cluster from https://discovery.etcd.io/new?size=3# specify the intial size of your cluster with ?size=X# WARNING: replace each time you ‘vagrant destroy’discovery: https://discovery.etcd.io/addr: $public_ipv4:4001peer-addr: $public_ipv4:7001fleet:public-ip: $public_ipv4units:– name: etcd.servicecommand: start– name: fleet.servicecommand: startThe $private_ipv4 and $public_ipv4 substitution variables are fully supported in cloud-config on Vagrant. They will map to the first statically defined private and public networks defined in the Vagrantfile.

Your Vagrantfile should copy your cloud-config file to /var/lib/coreos-vagrant/vagrantfile-user-data. The provided Vagrantfile is already configured to do this. cloudinit reads vagrantfile-user-data on every boot and uses it to create the machine’s user-data file.

If you need to update your cloud-config later on, run vagrant reload –provision to reboot your VM and apply the new file.

Start up CoreOS

The config.rb.sample file contains a few useful settings about your Vagrant environment and most importantly, how many machines you’d like in your cluster.

CoreOS is designed to be updated automatically with different schedules per channel. Select the channel you’d like to use for this cluster below. Read the release notes for specific features and bug fixes.

Stable Channel

Beta ChannelAlpha ChannelThe Stable channel should be used by production clusters. Versions of CoreOS are battle-tested within the Beta and Alpha channels before being promoted. Current version is CoreOS 633.1.0.

Rename the file to config.rb then uncomment and modify:

config.rb

# Size of the CoreOS cluster created by Vagrant

$num_instances=3# Official CoreOS channel from which updates should be downloaded$update_channel=’stable’Start Machines Using Vagrant’s default VirtualBox Provider

Start the machine(s):

vagrant up

List the status of the running machines:

$ vagrant status

Current machine states:

core-01 running (virtualbox)

core-02 running (virtualbox)core-03 running (virtualbox)

This environment represents multiple VMs. The VMs are all listed

above with their current state. For more information about a specificVM, run `vagrant status NAME`.Connect to one of the machines:

vagrant ssh core-01 — -A

Start Machines Using Vagrant’s VMware Provider

If you have purchased the VMware Vagrant provider, run the following commands:

vagrant up –provider vmware_fusion

vagrant ssh core-01 — -ASingle Machine

To start a single machine, we need to provide some config parameters in cloud-config format via the user-data file.

Cloud-Config

This cloud-config starts etcd and fleet when the machine is booted:

#cloud-config

coreos:

etcd:addr: $public_ipv4:4001peer-addr: $public_ipv4:7001fleet:public-ip: $public_ipv4units:– name: etcd.servicecommand: start– name: fleet.servicecommand: startStart up CoreOSThe config.rb.sample file contains a few useful settings about your Vagrant environment. We’re going to set the CoreOS channel that we’d like the machine to track.

Beta Channel

Alpha ChannelThe beta channel consists of promoted alpha releases. Current version is CoreOS 647.0.0.

Rename the file to config.rb then uncomment and modify:

config.rb

# Official CoreOS channel from which updates should be downloaded

$update_channel=’beta’Start Machine Using Vagrant’s default VirtualBox Provider

Start the machine:

vagrant up

Connect to the machine:

vagrant ssh core-01 — -A

Start Machine Using Vagrant’s VMware Provider

If you have purchased the VMware Vagrant provider, run the following commands:

vagrant up –provider vmware_fusion

vagrant ssh core-01 — -AShared Folder Setup

Optionally, you can share a folder from your laptop into the virtual machine. This is useful for easily getting code and Dockerfiles into CoreOS.

config.vm.synced_folder “.”, “/home/core/share”, id: “core”, :nfs => true, :mount_options => [‘nolock,vers=3,udp’]

After a ‘vagrant reload’ you will be prompted for your local machine password.

New Box Versions

CoreOS is a rolling release distribution and versions that are out of date will automatically update. If you want to start from the most up to date version you will need to make sure that you have the latest box file of CoreOS. You can do this using vagrant box update – or, simply remove the old box file and Vagrant will download the latest one the next time you vagrant up.

vagrant box remove coreos-alpha vmware_fusion

vagrant box remove coreos-alpha virtualboxIf you’d like to download the box separately, you can download the URL contained in the Vagrantfile and add it manually:

vagrant box add coreos-alpha Using CoreOS

Now that you have a machine booted it is time to play around. Check out the CoreOS Quickstart guide, learn about CoreOS clustering with Vagrant, or dig into more specific topics.