README for libswarm EC2 Service

ec2-libswarm-readme.md

https://github.com/docker/libswarm

EC2 Libswarm Service

This service will deploy Docker container onto EC2 instance. It will do all of the work spinning up the instance if it doesn't exist already.

Usage:

export AWS_ACCESS_KEY_ID=XXXX

export AWS_SECRET_ACCESS_KEY=XXXX

export DOCKER_HOST=tcp://localhost:4243

./bin/swarmd "dockerserver tcp://localhost:4243" "ec2 <options>"

If everything is setup correctly you should be able to run Docker client commands against the running instance.

Options differ depending on your EC2 running environment (EC2 Classic or VPC). Below is a full list of available options.

Options:

Environment Variables:

AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Make sure the account associated has suffient permissions to run an instance.

Commandline Arguments:

Name	Required	Default	Example
keypair	Yes		your.pem
security_group_id	Yes		sg-xxxxxx
region	No	us-east-1	us-west-1
zone	No		us-east-1b
tag	No	docker-ec2-libswarm
ami	No		ami-76817c1e
instance_type	No	t2.micro
ssh_user	No	ec2-user
ssh_port	No	22
subnet_id	No		subnet-xxxxxxxx

• security_group_id This requires matching ssh_port to be opened.

• region: Possible values: us-east-1, us-west-1, us-west-2, eu-west-1, sa-east-1, ap-northeast-1, ap-southeast-1, ap-southeast-2

• zone By default first available zone is used within a given region. If in VPC it's based on your subnet AZ.

• tag This is used to retrieve previously instantiated instance.

• ami By default the ami id is looked up by this ami name amzn-ami-hvm-2014.03.2.x86_64-ebs. The actual ami id will vary based on region. If you wish to specify your own ami, ami id should be used, NOT ami name.

• ssh_user If custom ami is used, the user might need to be adjusted.

EC2 Classic:

MAKE SURE YOUR SSH PRIVATE KEY HAS THE CORRECT PERMISSIONS SET (600)

./bin/swarmd "dockerserver tcp://localhost:4243" \
             "ec2 --instance_type=m3.medium \
                  --keypair=your-keypair \
                  --ssh_key=/full/path/to/your.pem 
                  --security_group_id=sg-xxxxxxxx"

Not all EC2 instance type is available to run within EC2 Classic. By default, instance type is set to t2.micro. However, this instance type is only available within VPC. In this example, m3.medium is used in order to run within EC2 Classic since t2.micro is only available within VPC.

Amazon has been slowly moving away from EC2 Classic, so if you have a newer AWS account, you might not even be able to run under EC2 Classic.

VPC:

MAKE SURE THE INSTANCE IS IN A REACHABLE PART OF THE SUBNET

./bin/swarmd "dockerserver tcp://localhost:4243" \
              "ec2 --keypair=your-keypair \
                   --subnet_id=subnet-xxxxxxxx \
                   --ssh_key=/full/path/to/your.pem  \
                   --security_group=sg-xxxxxxxx"

subnet_id is specified in order to run under VPC within a particular subnet.

Common Issues:

• Stuck on waiting for ssh port to be opened

  Output:

  Waiting for ssh to be available. make sure ssh is open on port 22.

  Verify that your security group is allowing incoming SSH. EC2 and VPC security groups are separate from each other, make sure you are specifying the correct subnet_id.

• Stuck on waiting for Docker daemon to be available

  Output:

  Waiting for docker daemon on remote machine to be available.

  Verify the running instance keypair and --ssh_key are lined up correctly. Make sure --ssh_key is point at the correct path. If problem persists, manually SSH into the running instance to verify SSH key is setup correctly.

• Unable to communicate to Docker daemon via Docker client

  Make sure SSH private key path is correct and has the correct permissions set. It should be set to chmod 600.

• Invalid EC2 argument combinations

  It is possible to pass in EC2 arguments that are conflicting. In most cases, the error message will be helpful in guiding you on fixing the problem.

Caveat:

Docker daemon is currently installed via userdata script. It is assumed that you are running Amazon Linux. If you specify a custom ami most likely Docker will fail to install since the userdata script might not be compatible with the ami. One temporary workaround is to have the Docker daemon already installed in the ami. This is not ideal since the userscript will still run. Below is the hardcoded userdata script:

#!/bin/bash
yum install -y docker
cat << EOF > /etc/sysconfig/docker
other_args="-H tcp://127.0.0.1:4243"
EOF
service docker start

Near Future Improvements:

• Remove the hardcoded userdata script and allow user specified userdata.
• Accept multiple security group ids.
• Allow user to specify custom SSH port. Currently it is hardcoded to port 22.
• Move commandline arguments into a configuration file.

Questions:

Feel free to reach out. @aaronfeng or aaron.feng@gmail.com.