Amazon EC2

Add your AWS credentials to a custom profile inside your ~/.boto configuration file.

[profile laniakea]
aws_access_key_id = <your_access_key_id>
aws_secret_access_key = <your_secret_key>

Complement the provided amazon.json file with your AWS AMI information (see laniakea -h for location).

# Example: an on-demand instance
"default": {
  "image_id":"ami-<AMI_ID>",
  "instance_type": "<INSTANCE_TYPE>",
  "security_groups": ["laniakea"],
  "key_name": "<AWS_KEY_NAME>",
  "instance_profile_name": "<name-of-role>",
  "min_count": 3,
  "max_count": 3
}

# Example: a spot instance
"peach": {
  "image_id":"ami-<AMI_ID>",
  "instance_type": "<INSTANCE_TYPE>",
  "security_groups": ["laniakea"],
  "key_name": "<AWS_KEY_NAME>",
  "instance_profile_name": "<name-of-role>",
  "count": 3
}

Add your UserData script - which is going to be used for provisioning your EC2 instances - to the userdata/ folder.

In the likely case that you want to use a custom UserData script rather than modifying the default.sh file, then you need to point the -userdata parameter to that file.

Please refer to https://help.ubuntu.com/community/CloudInit to learn more about UserData scripts.

Basic Usage Examples

Run N on-demand instances with a custom -userdata script

laniakea ec2 -create-on-demand -tags Name=peach -userdata userdata/peach.private.sh

Run N spot instances with a custom -userdata script and a -max-spot-price of $0.05

laniakea ec2 -create-spot -tags Name=peach -image-name peach -userdata userdata/peach.private.sh -image-args count=10

Show which instances are running and are tagged with the name 'peach'

laniakea ec2 -status -only tag:Name=peach instance-state-code=16

Filters support wildcards. Example: "tag:Name=peach-*" would be suitable to list all instances having the word "peach" as prefix of a tag name. For a list of available filters refer to http://docs.aws.amazon.com/AWSEC2/latest/CommandLineReference/ApiReference-cmd-DescribeInstances.html

Terminate all running instances which are tagged with the name 'peach'

laniakea ec2 -terminate -only tag:Name=peach

Scale down and terminate the oldest N running instances

laniakea ec2 -terminate N -only tag:Name=peach

Terminate a specific instance by id

laniakea ec2 -status -only tag:Name=peach instance-id=i-9110fa9e

List available macros in a UserData script

laniakea ec2 -list-userdata-macros -userdata userdata/peach.pit.sh

EC2 Help Menu

python3 -m laniakea ec2 -h

usage: laniakea ec2 [-h] [-create-on-demand | -create-spot | -stop [n] | -terminate [n] | -status | -run cmd |
                    -list-userdata-macros | -print-userdata] [-userdata path] [-userdata-macros k=v [k=v ...]]
                    [-tags k=v [k=v ...]] [-only k=v [k=v ...]] [-images path] [-image-name str]
                    [-image-args k=v [k=v ...]] [-profile str] [-max-spot-price #] [-region REGION] [-zone ZONE]
                    [-root-device-type {ebs,instance_store}] [-ebs-size EBS_SIZE] [-ebs-volume-type {gp2,io1,standard}]
                    [-ebs-volume-delete-on-termination]

optional arguments:
  -h, --help                            show this help message and exit

Mandatory EC2 Parameters:
  -create-on-demand                     Create on-demand instances. (default: False)
  -create-spot                          Create spot instances. (default: False)
  -stop [n]                             Stop active instances. (default: None)
  -terminate [n]                        Terminate active instances. (default: None)
  -status                               List current state of instances. (default: False)
  -run cmd                              Execute commands via SSH (default: )
  -list-userdata-macros                 List available macros. (default: False)
  -print-userdata                       Print the UserData script to stdout. (default: False)

UserData Parameters:
  -userdata path                        UserData script for cloud-init process. (default:
                                        /Users/posidron/Library/Application Support/laniakea/userdata/ec2/default.sh)
  -userdata-macros k=v [k=v ...]        Custom macros for the UserData. (default: None)

Optional Parameters:
  -tags k=v [k=v ...]                   Assign tags to instances. (default: None)
  -only k=v [k=v ...]                   Filter instances by criterias. (default: None)
  -images path                          EC2 image definitions. (default: /Users/posidron/Library/Application
                                        Support/laniakea/amazon.json)
  -image-name str                       Name of image definition. (default: default)
  -image-args k=v [k=v ...]             Custom image arguments. (default: None)
  -profile str                          AWS profile name in the .boto configuration. (default: laniakea)
  -max-spot-price #                     Max price for spot instances. (default: 0.05)
  -region REGION                        EC2 region name. (default: us-west-2)
  -zone ZONE                            EC2 placement zone. (default: None)
  -root-device-type {ebs,instance_store}
                                        The root device type. (default: ebs)
  -ebs-size EBS_SIZE                    The root disk space size. (default: None)
  -ebs-volume-type {gp2,io1,standard}   The root disk volume type. (default: gp2)
  -ebs-volume-delete-on-termination     Delete the root EBS volume on termination. (default: False)