scottslowe-learning-tools/coreos-cloudinit-toolbox/README.md

Customizing the CoreOS Toolbox using Cloud-Init

These files were created to allow users to see how to use cloud-init (http://cloudinit.readthedocs.org/) to customize the CoreOS (https://coreos.com/) toolbox. There are three ways you can use this learning environment:

• Users can use Vagrant (http://www.vagrantup.com) and a virtualization provider (such as VMware Fusion with the Vagrant VMware plugin) to spin up a local environment.
• Users can spin up an instance in an existing OpenStack cloud.
• Users can spin up an AWS instance.

Contents

• machines.yml: This YAML file contains a list of VM definitions. It is referenced by Vagrantfile when Vagrant instantiates the VMs. You may need to edit this file to provide appropriate IP addresses and other VM configuration data (see "Instructions" below). This file is not needed when testing with OpenStack or AWS intances.

• README.md: This file you're currently reading.

• user-data: This cloud-init configuration file should be able to be used unchanged, and is used by Vagrant, OpenStack, and AWS (see "Instructions") below.

• Vagrantfile: This file is used by Vagrant to spin up local VMs. This file is fairly extensively commented to help explain what's happening. You should be able to use this file unchanged; all the VM configuration options are stored outside this file. This file is not needed when testing with OpenStack or AWS instances.

Instructions

Using Vagrant

This section assumes you've already installed Vagrant and the necessary virtualization provider. Please refer to the documentation for those products for more information on installation or configuration. This was tested using Vagrant 1.8.1, VMware Fusion 8.1.0, and the Vagrant VMware plugin.

1. Use vagrant box add to install the CoreOS Vagrant box. See http://stable.release.core-os.net/amd64-usr/ for downloads of the Vagrant box for the CoreOS Stable release channel.

2. Place the files from the coreos-cloudinit-toolbox directory of this GitHub repository into a directory on your local system. You can clone the entire "learning-tools" repository (using git clone) or just download the specific files from the the coreos-cloudinit-toolbox folder.

3. Edit machines.yml file to provide the specific details on the VMs that Vagrant should create. The Vagrantfile expects five values for each VM: name (the user-friendly name of the VM, which will also be used as the hostname for the guest OS inside the VM); box (the name of the CoreOS Vagrant box downloaded in step #1); ram (the amount of memory to be assigned to the VM); vcpu (the number of vCPUs that should be assigned to the VM); and ip_addr (a private IP address to be statically assigned to the VM).

4. If the box you downloaded in step #1 is named something other than "coreos-stable", then edit Vagrantfile and change all instances of "coreos-stable" to match the name of the box you downloaded.

5. Once you have edited machines.yml (and Vagrantfile, if necessary), use vagrant up to bring up the VMs (a single CoreOS VM, by default).

6. Log into the VM using vagrant ssh. Once you're logged in, verify that .toolboxrc exists in the core user's home directory, and verify that /opt/bin/python exists. The presence of these two files shows that cloud-init worked properly. Optionally, feel free to run python -i and watch CoreOS download the appropriate Python container and drop you at a Python interpreter prompt.

Using OpenStack

This section assumes that you have a functioning OpenStack cloud and that this cloud already has a CoreOS image for users to use. If this is not the case, you'll need to upload a CoreOS image (or ask your cloud administrator to make one accessible). This was tested using OpenStack "Juno" on Ubuntu/KVM with VMware NSX providing the networking functionality.

Because of wide variations in how OpenStack is configured and in how users consume OpenStack, this section provides only high-level directions as opposed to step-by-step instructions.

• You'll need to supply the user-data file from the coreos-cloudinit-toolbox directory of the repository (or its contents) to OpenStack when launching your instance(s). In the Dashboard GUI, this is done via the "Post-Creation" tab of the Launch Instance wizard. When using the nova boot CLI command, this is done via the --user-data flag.

• When you log into the running instance (note you may need to use an SSH bastion host or assign a floating IP to the instance), check for the existence of .toolboxrc in the core user's home directory and the existence of /opt/bin/python. Both of these files are created by cloud-init when OpenStack launches the instance. Optionally, feel free to run python -i and watch CoreOS download the appropriate Python container and drop you at a Python interpreter prompt.

Using AWS

This section assumes you have an Amazon AWS account and are relatively familiar with launching instances on AWS. Due to wide variations in how users may consume AWS resources, this section provides only high-level directions.

• Launch your instance in the desired AWS region. Refer to https://coreos.com/os/docs/latest/booting-on-ec2.html for a list of the CoreOS AMIs for each AWS region.

• If you're using the AWS Management Console, you'll need to supply the user-data file (or its contents) from the coreos-cloudinit-toolbox directory of the repository in step 3 (Configure Instance). This is found in the Advanced Details section. If you're using the AWS CLI, this is done with the --user-data flag to the aws ec2 run-instances command.

• When you log into the running instance, check for the existence of .toolboxrc in the core user's home directory and the existence of /opt/bin/python. Both of these files are created by cloud-init when AWS launches the instance. Optionally, feel free to run python -i and watch CoreOS download the appropriate Python container and drop you at a Python interpreter prompt.

Enjoy!