holepunch

Holepunch manages AWS EC2 security groups in a declarative way through a DSL.

• Ruby 1.9.3 or newer.

gem install holepunch

or in your Gemfile

gem 'holepunch'

You need to provide your AWS security credentials and a region. These can be provided via the command-line options, or you can use the standard AWS environment variables:

export AWS_ACCESS_KEY_ID='...'
export AWS_SECRET_ACCESS_KEY='...'
export AWS_REGION='us-west-2'

Specify your security groups in a SecurityGroups file in your project's root. Declare security groups that you need and the ingresses you want to expose. You can add ingresses using tcp, udp, and ping. For each ingress you can list allowed hosts using group names or CIDR notation.

group 'web' do
  desc 'Web servers'

  tcp 80
end

group 'db' do
  desc 'database servers'

  tcp 5432, 'web'
end

group 'log' do
  desc 'log server'

  tcp 9999, 'web', 'db', '10.1.0.0/16'
end

An environment can be specified which is available through the env variable. This allows you to have custom security groups per server environment.

group "#{env}-web"
group "#{env}-db" do
  tcp 5432, "#{env}-web"
end

Your application may depend on security groups defined by other services. Ensure they exist using the depends method.

depends 'my-other-service'
group 'my-service' do
  udp 9999, 'my-other-service'
end

You may specify port ranges for tcp and udp using the range operator.

group 'my-service' do
  udp 5000..9999, '0.0.0.0/0'
end

You can specify ping/icmp rules with icmp (alias: ping).

group 'my-service' do
  ping '10.0.0.0/16'
end

It can be useful to describe groups of security groups you plan to launch instances with by using the service declaration.

service "#{env}-web" do
  groups %W(
    admin
    #{env}-log-producer
    #{env}-web
  )
end

Simply navigate to the directory containing your SecurityGroups file and run holepunch.

$ holepunch

If you need to specify an environment:

$ holepunch -e live

You can get a list of security groups for a service using the service subcommand.

$ holepunch service -e prod prod-web
admin,prod-log-producer,prod-web

You can also get a list of all defined services.

$ holepunch service --list

You can run the unit tests by simply running rspec.

$ rspec

By default the integration tests with EC2 are not run. You may run them with:

$ rspec -t integration

• Ben Scott (gamepoet@gmail.com)
• Pat Wyatt (pat@codeofhonor.com)

Copyright 2014 Undead Labs, LLC.

Licensed under the MIT License: http://opensource.org/licenses/MIT