Quickstart

Installation

Virtualenv

Both the automatic and manual install assume that the virtualenv tool is installed. If you do not have virtualenv installed, you may do the following:

# only run this if you are missing the virtualenv tool.
sudo pip install virtualenv

Automatic install from source with botoform-bootstrap.sh

Note

You should always review scripts prior to piping them from the Internet into your shell.

This script automates the steps in the manual install from source section.

The following one-liner will install botoform (bf) into your home directory:

wget -O - https://raw.githubusercontent.com/russellballestrini/botoform/master/botoform-bootstrap.sh | sh

Next you should verify the botoform install.

Manual install from source

Clone botoform repo:

git clone https://github.com/russellballestrini/botoform.git $HOME/botoform
cd $HOME/botoform

Create and activate a Python virtualenv named env:

virtualenv env
. env/bin/activate

Install dependencies into virtualenv:

python setup.py develop

Next you should verify the botoform install.

Verify the botoform install

Whenever you want to use the bf tool, you need to activate the virtualenv:

You may verify installation by running:

bf --help

You should see usage information.

Next, edit your AWS configuration file with your access/secret keys.

Configuration

Setup your AWS CLI config file, for example -

~/.aws/config:

[profile development]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region = us-west-2

You are now ready to begin using Botoform!

Using Botoform

Create VPC

Note

This section will create real resources on AWS.

bf --profile=development --region=ap-southeast-1 create dogtest01 -e 'vpc_cidr=192.168.1.0/24' tests/fixtures/webapp.yaml

Unlock VPC

Note

This command will unlock instances to allow them to be terminated.

Disable API Termination Protection on all instances in VPC.

bf --profile=development --region=ap-southeast-1 unlock dogtest01

Destroy VPC

Danger

This command will completely destroy the entire VPC and all related resources!

bf --profile=development --region=ap-southeast-1 destroy dogtest01

Example Output

bf -p development -r us-east-1 create -e 'vpc_cidr=10.20.20.0/24' stg example.yaml

creating vpc (stg, 10.20.20.0/24)
tagging vpc (Name:stg)
modifying vpc for dns support
modifying vpc for dns hostnames
creating internet_gateway (igw-stg)
tagging gateway (Name:igw-stg)
attaching igw to vpc (igw-stg)
creating DHCP Options Set for stg
associating DHCP Options dopt-30731454 with VPC stg
creating route_table (stg-public)
tagging route_table (Name:stg-public)
creating route_table (stg-private)
tagging route_table (Name:stg-private)
creating subnet 10.20.20.96/27 in us-east-1c
tagging subnet (Name:stg-private-2)
creating subnet 10.20.20.64/27 in us-east-1b
tagging subnet (Name:stg-private-1)
creating subnet 10.20.20.32/27 in us-east-1b
tagging subnet (Name:stg-public-1)
creating subnet 10.20.20.0/27 in us-east-1c
tagging subnet (Name:stg-public-2)
creating security_group stg-all
tagging security_group (Name:stg-all)
creating security_group stg-bastion
tagging security_group (Name:stg-bastion)
creating key pair default
associating rt private with sn private-2
associating rt private with sn private-1
associating rt public with sn public-1
associating rt public with sn public-2
creating role: bastion
1 instances of role bastion launching into stg-public-1 subnet
inbound rule: 'bastion' -> 'all' over ports 22 (TCP)
inbound rule: '98.110.147.178/32' -> 'bastion' over ports 22 (TCP)
inbound rule: '184.188.101.86/32' -> 'bastion' over ports 22 (TCP)
waiting for i-00b858ff5644d8634 to start
waiting for i-00b858ff5644d8634 to be in status OK
tagging instance i-00b858ff5644d8634 (Name:stg-bastion-delawareriver)
tagging volumes for instance stg-bastion-delawareriver (Name:stg-bastion-delawareriver)
allocating eip and associating with stg-bastion-delawareriver
allocated eip 54.80.219.185 and associated with stg-bastion-delawareriver
locking new normal (not autoscaled) instances to prevent termination
adding route ['0.0.0.0/0', 'internet_gateway'] to route_table (stg-public)
managing route53 private zone.
done! don't you look awesome. : )