Capistrano::DataPlaneApi

Capistrano plugin which helps you automatically change the admin state of your HAProxy servers using the Data Plane API.

Capistrano is a remote server automation and deployment tool. HAProxy is a load balancer.

Install the gem and add to the application's Gemfile by executing:

$ bundle add capistrano-data_plane_api

Or add it to Gemfile manually:

gem "capistrano-data_plane_api"

Afterwards, you can use the installer to set up your app.

We highly recommend it.

$ bundle exec cap_data_plane_api install

This gem hooks into capistrano to add new tasks which enable you to change the admin state of your HAProxy servers during the deployment process using using the Data Plane API.

We recommend creating separate Capistrano stages for every HAProxy server.

The installer generates a handy deployment script which let's you deploy your app to all servers in a particular HAProxy backend with one command.

All admin state switching is handled automatically for you. You can go make yourself a coffee without having to worry.

It prints a beautiful summary after the deployment.

It can be invoked like that

$ bin/deploy -h

That particular command prints a help message, which is a good reference for how to use this script.

Usage: bin/deploy [options]

This script can be used to deploy this app to remote servers.

    -c, --current                    Deploy from the currently checked out branch
    -t, --test                       Show the commands that would be executed but do not carry out the deployment
    -C, --check                      Test deployment dependencies. Checks things like directory permissions, necessary utilities, HaProxy backends and servers
    -g, --group=GROUP                Deploy the code to every server in the passed HAProxy backend/group
        --no-haproxy                 Do not modify the state of any server in HAProxy
        --force-haproxy              Ignore the current state of servers in HAProxy
    -o, --only=ONLY                  Deploy the code only to the passed servers in the same order
    -H, --haproxy-config             Show the current HAProxy configuration
    -S, --haproxy-state              Show the current HAProxy state
    -T, --tasks                      Print a list of all available deployment Rake tasks
    -r, --rake=RAKE                  Carry out a particular Rake task on the server
    -h, --help                       Prints this help
    -b, --branch=BRANCH              Deploy the code from the passed Git branch
        --no-migrations              Do not carry out migrations
        --no-asset-precompilation    Skip asset precompilation during deployment

$ bin/deploy -S

$ bin/deploy -H

$ bin/deploy -g staging

$ bin/deploy -g staging -c

$ bin/deploy -g staging -o staging_serv3,staging_serv1

$ bin/deploy -g edge -b development

Same as cap staging_serv3 deploy

$ bin/deploy staging_serv3

$ bin/deploy -g production -r deploy:restart

There are three new Rake tasks:

• data_plane_api:server:check -- check the state of the currently deployed server and log it to stdout
• data_plane_api:server:set_drain -- sets the admin state of the currently deployed server to DRAIN
• data_plane_api:server:set_maint -- sets the admin state of the currently deployed server to MAINT
• data_plane_api:server:set_ready -- sets the admin state of the currently deployed server to READY

To load them and and invoke them manually you should add this line to your Capfile

require 'capistrano/data_plane_api'

These tasks will only run when the :web role is added to the deployment stage.

If you used the installer, your app is already set up with hooks.

In order to use our recommended configuration of these new tasks, you should add the following line to your Capfile

require 'capistrano/data_plane_api/hooks'

Our config works as follows:

deploy
  deploy:starting
    deploy:check
      [before]
        data_plane_api:server:check
  deploy:started
    [after]
        data_plane_api:server:set_drain
  deploy:updating
  deploy:updated
  deploy:publishing
    [before]
        data_plane_api:server:set_maint
  deploy:published
  deploy:finishing
  deploy:finished
    [after]
        data_plane_api:server:set_ready

These tasks will only run when the :web role is added to the deployment stage.

In order for the --no-migrations and --no-asset-precompilation flags to work correctly, you need to use this configuration in your Capfile:

require 'capistrano/rails/assets' if ::ENV['NO_ASSET_PRECOMPILATION'].nil?
require 'capistrano/rails/migrations' if ::ENV['NO_MIGRATIONS'].nil?

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/espago/capistrano-data_plane_api.

The gem is available as open source under the terms of the MIT License.