README.rdoc

cap-rightscale¶ ↑

Capistrano extension that maps RightScale parameters to Roles [RightScale](www.rightscale.com)

Installation¶ ↑

Install the packages

For Debian/Ubuntu:

$ apt-get install ruby ruby-dev
$ apt-get install rubygems  (if not installed)

For RHEL5 (probably needs the EPEL repository enabled):

$ yum install ruby ruby-devel
$ yum install rubygems (if not installed)

For MacOSX(MacPorts):

$ port install ruby
$ port install rb-rubygems (if not installed)

Install the cap-rightscale:

$ gem install cap-rightscale

Settings¶ ↑

To prepare, go info the root directory of that project and run capify:

$ cd <project_dir>
$ capify .

Configure Capfile(example deploy.rb):

# config/deploy.rb
require 'rubygems'
require 'cap-rightscale'
require 'cap-rightscale/recipes'

DEPLOYMENT_ID = 12345       # RightScale Deployment ID
SERVER_ARRAY_ID = 6789      # RightScale ServerArray ID

# set roles
nickname :web, :name_prefix => "proxy", :deployment => DEPLOYMENT_ID
server_array :app, :array_id => SERVER_ARRAY_ID
tag :dbm, :tags => "xx_db:role=master", :deployment => DEPLOYMENT_ID
tag :dbs, :tags => "xx_db:role=slave", :deployment => DEPLOYMENT_ID, :no_release => true

Put RightScale API Credential file into <HOME>/.rsconf/rsapiconfig.yml

# <HOME>/.rsconf/rsapiconfig.yml
username: user@example.com
password: yourpassword
account: 1

Run testing:

$ cap rs:none

For more help with Capistrano, see this: github.com/capistrano/capistrano/wiki

Roles¶ ↑

In order to define role, RightScale nickname and deployment mappings:

nickname :web, :name_prefix => "proxy", :deployment => 12345
# => role :web, ["proxyXXX", ... in deployment ID:12345]

ServerArray mappings:

server_array :app, :array_id => 6789, :backup => true
# => role(:app, :backup => true) { ["apXXX", ... in serverarray ID:6789] }

Machine tags and deployment mappings:

tag :dbm, :name_prefix => "db", :tags => ["xx_db:env=prod", "xx_db:role=master"], :deployment => 12345, :primary => true
# => role(:dbm, :primary => true) { ["dbXXX", ... in deployment ID:12345] }

RightScale API Credential¶ ↑

see the below site:

Authentication - RightScale Cloud Management Support Portal

You must authenticate to use the RightScale API, Make sure to set your own login/password(used to login to RightScale dashboard) and account number(the tail end of the Dashboard URL: Settings > Account)

Put Authentication file described in RightScale API credentials into <HOME>/.rsconf/rsapiconfig.yml

Or, You can define filepath:

# config/deploy.rb
set :rs_confpath, "/project/config/rs_auth.yml"

Caches¶ ↑

These functions require RightScale api calls, which are slow. On the first call, Write a cache file in the temp directory. Default cache lifetime is 86400 seconds(1day) each role.

modified cache life time:

# config/deploy.rb
set :rs_lifetime, 86400 * 7  # 1week

This can be disabled with ENV variable: RS_CACHE=false , set :rs_lifetime 0 OR rs_disable :use_rs_cache in the Capfile.

$ cap invoke COMMAND='hostname' RS_CACHE=false

# disable cache config/deploy.rb
set :rs_lifetime, 0
# the other way
rs_disable :use_rs_cache

Conversely, to use cache to infinity with set :rs_lifetime -1.

# config/deploy.rb
set :rs_lifetime, -1

Cache clear task(needs after modifying the Capfile):

$ cap rs:cache:clear
$ cap rs:cc

Server name to associate with the role¶ ↑

Default name is Amazon EC2 local IP address, This can be changed according to the parameter.

Use EC2 public IP address:

# config/deploy.rb
rs_enable :use_public_ip

Use RightScale nickname(use as name to resolve for host in /etc/hosts or dns record entry). This takes priority over ip address. Using RightScale Nickname, How to DNS hostname for ec2 instances:

• “Developing RightScripts - RightScale Cloud Management Support Portal”

• “Environment Inputs - RightScale Cloud Management Support Portal”

• “HowTo update DNS hostnames automatically for your Amazon EC2 instances | MDLog:/sysadmin”

  # config/deploy.rb
  rs_enable :use_nickname         # RightScale nickname
  set :rs_domain, "ec2.int.com"   # set subdomain managed by your dns server zone(option: default ref <tt>search</tt> in <tt>/etc/resolv.conf</tt>)
  
  # set domain each role(priority over <tt>set :rs_domain</tt>)
  nickname :web, :nickname => "lb", :domain => "ec2.com"
  

Instance nickname in Server Array is <ServerArray name> #number

# ServerArray name: prod-web
prod-web #1   # <= instance nickname

cap-rightscale replace instance nickname in Server Array to use dns hostname for your dns server. Default format is “%d”(example: web #1 => web1).

Use rs_array_number_format to replace nickname format:

# config/deploy.rb
rs_array_number_format "%03d"   # web #1 => web001
rs_array_number_format "-%d"    # web #1 => web-1

Validate¶ ↑

Using ping and name resolv, validate host(except invalid host).

• rs_enable :validate_echo: In case you want to except hang-up instance

• rs_enable :validate_resolv: In case you want to except host can not be resolved

  # config/deploy.rb
  rs_enable :validate_echo, :validate_resolv
  

nickname¶ ↑

Definition:

nickname(role, params)

Arguments¶ ↑

role¶ ↑

Capistrano role paramter(:app, :web, :db)

params¶ ↑

Example:

nickname :app, :name_prefix => "ap", :deployment => 12345, :user => "www"
nickname :db, :name_prefix => "db", :deployment => 12345, :except_tags => "xx_db:state=broken"
nickname :mem, :name_prefix => "mem", :deployment => 12345, :except_tags => ["xx_mem:state=out_of_service"]

server_array¶ ↑

Definition:

server_array(role, params)

Arguments¶ ↑

role¶ ↑

Capistrano role paramter(:app, :web, :db)

params¶ ↑

Example:

server_array :app, :array_id => 6789, :user => "www"
server_array :mem, :array_id => 4321, :except_tags => "xx_mem:state=broken", :domain => "ec2.int.com"

tag¶ ↑

Definition:

tag(role, params)

role¶ ↑

Capistrano role paramter(:app, :web, :db)

params¶ ↑

Example:

tag :dbm, :deployment => 12345, :name_prefix => "db", :tags => "xx_db:role=master", :primary => true
tag :dbs, :deployment => 12345, :tags => ["xx_db:role=slave", "xx_db:master"]   # matching tag "xx_db:master=<master_ip>"

Output message¶ ↑

To suppress output as possible(-v option):

$ cap -v shell
$ cap -v invoke COMMAND='cat /var/log/httpd/access_log' 2>/tmp/collect_httpd_access_log

Contributing to cap-rightscale¶ ↑

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

• Fork the project

• Start a feature/bugfix branch

• Commit and push until you are happy with your contribution

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright¶ ↑

Copyright © 2011 Satoshi Ohki. See LICENSE.txt for further details.