prepare-machine

Setting up your own cluster

If you want to go through this orchestration workshop on your own, you will need a cluster of Docker nodes.

These instructions will walk you through the required steps, using Docker Machine to create the nodes.

Requirements

You need Docker Machine. To check if it is installed, try to run the following command:

$ docker-machine -v
docker-machine version 0.8.2, build e18a919

If you see a Docker Machine version number, perfect! Otherwise, you need to install it; either as part of the Docker Toolbox, or as a stand-alone tool. See Docker Machine installation docs for details.

You also need either credentials for a cloud provider, or a local VirtualBox or VMware installation (or anything supported by Docker Machine, really).

Discrepancies with official environment

The resulting environment will be slightly different from the one that we provision for people attending the workshop at conferences and similar events, and you will have to adapt a few things.

We try to list all the differences here.

User name

The official environment uses user docker. If you use Docker Machine, the user name will probably be different.

Node aliases

In the official environment, aliases are seeded in /etc/hosts, allowing you to resolve node IP addresses with the aliases node1, node2, etc.; if you use Docker Machine, you will have to lookup the IP addresses with the docker-machine ip nodeX command instead.

SSH keys

In the official environment, you can log from one node to another with SSH, without having to provide a password, thanks to pre-generated (and pre-copied) SSH keys. If you use Docker Machine, you will have to use docker-machine ssh from your machine instead.

Machine and Compose

In the official environment, Docker Machine and Docker Compose are installed on your nodes. If you use Docker Machine you will have to install at least Docker Compose.

The easiest way to install Compose (verified to work with the EC2 and VirtualBox drivers, and probably others as well) is do use docker-machine ssh to connect to your node, then run the following command:

sudo curl -L \
  https://github.com/docker/compose/releases/download/1.15.0/docker-compose-`uname -s`-`uname -m` \
  -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Note that it is not necessary (or even useful) to install Docker Machine on your nodes, since if you're following that guide, you already have Machine on your local computer. ☺

IP addresses

In some environments, your nodes will have multiple IP addresses. This is the case with VirtualBox, for instance. At any point in the workshop, if you need a node's IP address, you should use the address given by the docker-machine ip command.

Creating your nodes with Docker Machine

Here are some instructions for various Machine Drivers.

AWS EC2

You have to retrieve your AWS access key and secret access key, and set the following environment variables:

export MACHINE_DRIVER=amazonec2
export AWS_ACCESS_KEY_ID=AKI...
export AWS_SECRET_ACCESS_KEY=...

Optionally, you can also set AWS_DEFAULT_REGION to the region closest to you. See AWS documentation for the list of available regions and their codes.

For instance, if you are on the US West Coast, I recommend that you set AWS_DEFAULT_REGION to us-west-2; if you are in Europe, to eu-central-1 (except in UK and Ireland where you probably want eu-west-1), etc.

If you don't specify anything, your nodes will be in us-east-1.

You can also set AWS_INSTANCE_TYPE if you want bigger or smaller instances than t2.micro. For the official workshops, we use m3.large, but remember: the bigger the instance, the more expensive it gets, obviously!

After setting these variables, run the following command:

for N in $(seq 1 5); do
  docker-machine create node$N
  docker-machine ssh node$N usermod -aG docker ubuntu
done

And after a few minutes, your five nodes will be ready. To log into a node, use docker-machine ssh nodeX.

By default, Docker Machine places the created nodes in a security group aptly named docker-machine. By default, this group is pretty restrictive, and will only let you connect to the Docker API and SSH. For the purpose of the workshop, you will need to open that security group to normal traffic. You can do that through the AWS EC2 console, or with the following CLI command:

aws ec2 authorize-security-group-ingress --group-name docker-machine --protocol -1 --cidr 0.0.0.0/0

If Docker Machine fails, complaining that it cannot find the default VPC or subnet, this could be because you have an "old" EC2 account (created before the introduction of EC2 VPC) and your account has no default VPC. In that case, you will have to create a VPC, a subnet in that VPC, and use the corresponding Machine flags (--amazonec2-vpc-id and --amazonec2-subnet-id) or environment variables (AWS_VPC_ID and AWS_SUBNET_ID) to tell Machine what to use.

You will get similar error messages if you have set these flags (or environment variables) but the VPC (or subnets) indicated do not exist. This can happen if you frequently switch between different EC2 accounts, and forget that you have set the AWS_VPC_ID or AWS_SUBNET_ID.

Microsoft Azure

You have to retrieve your subscription ID, and set the following environment variables:

export MACHINE_DRIVER=azure
export AZURE_SUBSCRIPTION_ID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Additionally, you can set AZURE_LOCATION to an Azure datacenter close to you. By default, it will pick "West US". You can see the available regions on Azure's website. For instance, if you want to deploy on the US East Coast, set AZURE_LOCATION to East US or eastus (capitalization and spacing shouldn't matter; just use the names shown on the map or table on Azure's website).

Then run the following command:

for N in $(seq 1 5); do
  docker-machine create node$N
  docker-machine ssh node$N usermod -aG docker docker-user
done

The CLI will give you instructions to authenticate on the Azure portal, and once you've done that, it will create your VMs.

You will log into your nodes with docker-machine ssh nodeX.

By default, the firewall only allows access to the Docker API and SSH ports. To open access to other ports, you can use the following command:

for N in $(seq 1 5); do
az network nsg rule create -g docker-machine --name AllowAny --nsg-name node$N-firewall \
   --access allow --direction inbound --protocol '*' \
   --source-address-prefix '*' --source-port-range '*' \
   --destination-address-prefix '*' --destination-port-range '*'
done

(The command takes a while. Be patient.)

Local VirtualBox or VMware Fusion

If you want to run with local VMs, set the environment variable MACHINE_DRIVER to virtualbox or vmwarefusion and create your nodes:

export MACHINE_DRIVER=virtualbox
for N in $(seq 1 5); do
  docker-machine create node$N
done

Terminating instances

When you're done, if you started your instance on a public cloud (or anywhere where it costs you money!) you will want to terminate (destroy) them. This can be done with the following command:

for N in $(seq 1 5); do
  docker-machine rm -f node$N
done