Remove the configuration pain when deploying to cloud servers.

When deploying applications with Capistrano, you need to itemize the servers for each role. When you only have a server or two this is easily managed, but keeping track of them becomes difficult if you have many servers provisioned via a CM tool or autoscaling.

By tagging servers with some meta data when they are created, you can filter the server list to only the ones pertaining to the current deploy.


Currently, only EC2 instances are supported.


Add this line to your application's Gemfile:

gem 'instance_selector', require: false

And then execute:

$ bundle

Or install it yourself as:

$ gem install instance_selector


By default, only running instances will be included in the results. Overriding this restriction is in the TODO section.


require 'instance_selector/provider'
provider = InstanceSelector::Provider.factory(:aws)
instances = provider.instances(:tags => {"Environment" => "staging", "Role" => "web"})

With Capistrano

require 'instance_selector/capistrano'

# Assign all web servers to the app role
instance_selector :app, :aws, :tags => {"Environment" => "staging", "Role" => "web"}

# an exception is thrown if exactly one instance is not returned
instance_selector :db,
                  :tags => {"Environment" => "staging", "Role" => "cron"},
                  role_options: { primary: true },
                  expect_count: 1

Generic with Capistrano

# Centralized instance selector config
on :after, only: stages do
  @logger.log 1, "Selecting instances from the cloud"
  instance_selector :app, :aws, tags: {"Environment" => stage, "Role" => "web"}
  instance_selector :sidekiq, :aws, tags: {"Environment" => stage, "Role" => "sidekiq"}
  # NOTE: Only one cron host is supported! Tag appropriately.
  instance_selector :cron, :aws, tags: {"Environment" => stage, "CronRole" => "web"}



  • Tests
  • filters (e.g., :filters => => nil to clear the running instance filter)
  • AWS
    • ELB support
    • attach/detach
    • selecting all instances in an ELB


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request