The Cloud Compose image plugin is used to create a base image for launching instances from. The base image should have all the package install commands applied to it, but none of the configuration changes. This ensures that all nodes in a cluster have exactly the same packages in them, but a base image can be reused across many projects by changing the configuration options.

To create a new image, you need the following items

1. cloud-compose.yml
2. image.sh script for updating the image

Once you have the configuration files run the following commands to create a new image:

cd my-configs
pip install cloud-compose cloud-compose-image
pip freeze > requirements.txt
cloud-compose image up

See the examples folder for a basic docker 1.10 image configuration.

Although the cluster plugin is designed to be cloud agnostic, AWS is the only cloud provider currently supported. Support for other cloud providers is welcomed as pull requests.

If you are using the AWS backend, the image plugin uses the Boto client which requires the following environment variables:

• AWS_REGION
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY

If you are using multiple AWS accounts, it is convenient to use Envdir to easily switch between AWS accounts.

To understand the purpose of each configuration file, consider the follow examples with an explanation of each element.

image:
  name: docker
  version: '1.10'
  search_path:
    - ../templates
  aws:
    ami: ami-6d1c2007
    subnet: subnet-9f0074c6
    keypair: drydock
    instance_type: t2.micro
    security_groups: sg-35c74951

The name is the name of image. This name will be used along with the version and a timestamp to create unique image names.

The version is used in conjuction with the name to allow clients to .

The search_path is the directories that will be examined when looking for configuration files like the image.sh file.

The AWS section contains information needed to create the cluster on AWS.

The ami is the Amazon Machine Image to start image creation process from.

The subnet to launch the instance in.

The list of security_groups that should be added to the EC2 servers. If you do not want to ssh into the instance to troubleshoot, this is not needed.

The instance_type you want to use for the image creation process. Defaults to t2.micro.

The keypair is the SSH key that will be added to the EC2 servers. If you do not want to ssh into the instance to troubleshoot, this is not needed.

Every time an image is created, unused images with the same name are deleted. The delete process uses the ImageName tag attribute to find and delete old images that are not currently being used by running instances.

To work on the code locally, checkout both cloud-compose and cloud-compose-image to the same parent directory. Then use a virtualenv and pip install editable to start working on them locally.

mkvirtualenv cloud-compose
pip install --editable cloud-compose
pip install --editable cloud-compose-image