= ey_cloud_awareness

This gem makes it a little easier to live on the EngineYard cloud:

* allow your instances to get information (metadata) about the app_master, db_master, utility workers, etc. in its EngineYard environment
* automatically map cap tasks to all your instances
* automatically update your ssh aliases

We use it over at http://brighterplanet.com.

== DEPRECATED

Use http://rubygems.org/gems/engineyard-metadata instead.

== Purpose

To define an unchanging interface to certain metadata that is buried deep inside JSON config files and EC2 API calls.

== /etc/chef/dna.json must be readable

This gem depends on

  /etc/chef/dna.json

being READABLE and containing certain attributes as named by EngineYard. You might have to add:

  sudo 'chmod a+r /etc/chef/dna.json'

to your before_restart.rb hook.

== Using the commandline tool directly

Running this command only works from EngineYard AppCloud Amazon EC2 instances.

  seamus-absheres-macbook:~ $ ssh my_app_staging-app_master
  Last login: Wed Sep 22 10:33:56 2010 from 9.9.9.9
  deploy@ip-10-202-197-254 ~ $ sudo gem install ey_cloud_awareness --no-rdoc --no-ri
  Successfully installed string_replacer-0.0.1
  Successfully installed ey_cloud_awareness-0.2.0
  2 gems installed
  deploy@ip-10-202-197-254 ~ $ sudo chmod a+r /etc/chef/dna.json
  deploy@ip-10-202-197-254 ~ $ ey_cloud_awareness
  {"apps":[{"name":"my_app","ebuilds":[{"name":"dev-libs/oniguruma"}],"repository_name":"git@github.com:seamusabshere/my_app.git","database_name":"my_app", [...]

* SSH into one of your EngineYard AppCloud Amazon EC2 instances.
* Running <tt>sudo gem install ey_cloud_awareness --no-rdoc --no-ri</tt> makes sure the gem binary is installed somewhere in your path.
* Running <tt>sudo chmod a+r /etc/chef/dna.json</tt> makes sure everybody can read the EngineYard DNA information.
* Running <tt>ey_cloud_awareness</tt>, you should get back a JSON-encoded hash of instance, environment, app, and other metadata.

It returns a cleaned-up combination of Amazon EC2 and EngineYard metadata.

== Capistrano

Put this in your <tt>config/deploy.rb</tt> (or your Capfile):

  # don't miss this line just because it's at the top
  load "#{Gem.searcher.find('ey_cloud_awareness').full_gem_path}/lib/ey_cloud_awareness/capistrano_tasks.rb"

  task :my_production do
    role :app_master, 'my_app.com'
    find_and_execute_task 'eyc_setup'       # gets a fresh list of your environment's instances and sets roles
  end

  task :my_staging do
    role :app_master, 'staging.my_app.com'
    find_and_execute_task 'eyc_setup'       # gets a fresh list of your environment's instances and sets roles
  end
  
  # add more tasks if you have more cloud environments

If you want to use EngineYard tasks like

  cap my_production monit:status
  cap my_production deploy:web:disable
  cap my_production deploy:web:enable
  cap my_production passenger:restart
  cap my_production nginx:restart

then you should make sure the tasks look like

  [...]
  require 'eycap/recipes'
  ssh_options[:compression] = false
  set :user, 'deploy'
  set :runner, 'deploy'
  [...]
  
  task :my_production do
    role :app_master, 'my_app.com'
    find_and_execute_task 'eyc_setup'
    set :rails_env, 'production'          # required for eycap
    set :deploy_to, '/data/my_app'        # required for eycap too
  end
  
  task :my_staging do
    role :app_master, 'staging.my_app.com'
    find_and_execute_task 'eyc_setup'
    set :rails_env, 'production'          # required for eycap
    set :deploy_to, '/data/my_app'        # required for eycap too
  end
  
== SSH into your instances

You can easily create SSH aliases like...

  ssh my_production-app_master

using the following task:

  cap my_production eyc:ssh
  cap my_staging eyc:ssh

That will magically update <tt>~/.ssh/config</tt> with aliases like

  ssh my_production-db_master
  ssh my_production-app_master
  ssh my_production-app0
  ssh my_production-app1
  ssh my_production-app2
  ssh my_production-util0
  ssh my_production-util1
  
  ssh my_staging-app_master
  ssh my_staging-db_master

Unfortunately, the counters are arbitrary and so the assignment of util0 versus util1, etc. may change every time you update your <tt>.ssh/config</tt> file with this task.

Once you've done the quickstart, try:

  cap my_production eyc:app_servers # gets a list of your app instances, including app_master
  cap my_production eyc:utilities   # ditto for utility instances
  cap my_production eyc:db_servers  # ditto for db instances
  cap my_production eyc:all         # gets a list of all your instances

== Making your instances aware of each other

You can use EngineYardCloudInstance to pull up information on other instances in an environment:

  >> db_master = EngineYardCloudInstance.db_master
  => #<EngineYardCloudInstance:0xb5e12f70 @instance_id="i-50cf5838">
  >> db_master.dns_name
  => "ec2-67-201-47-30.compute-1.amazonaws.com"

You can also inspect the whole set of metadata itself. This may change over time:

  >> pp db_master.data
  => {:block_device_mapping=>
        [{:ebs=>
           {:status=>"attached",
            :volumeId=>"vol-26172ee8",
            :deleteOnTermination=>"false",
            :attachTime=>"2010-04-07T21:09:37.000Z"},
          :deviceName=>"/dev/sdz2"},
         {:ebs=>
           {:status=>"attached",
            :volumeId=>"vol-26172ee8",
            :deleteOnTermination=>"false",
            :attachTime=>"2010-04-07T21:09:37.000Z"},
          :deviceName=>"/dev/sdz1"}],
        :launch_time=>"2010-04-07T21:08:10.000Z",
        :instance_type=>"c1.medium",
        :private_dns_name=>"domU-44-44-44-44-A4-02.compute-1.internal",
        :instance_state=>{:code=>"16", :name=>"running"},
        :ami_launch_index=>"0",
        :users=>
        [{:password=>"hoppAugEv",
          :username=>"deploy",
          :uid=>"1000",
          :comment=>"",
          :gid=>"1000"}],
        :environment=>
        {:framework_env=>"production",
         :name=>"my_staging",
         :stack=>"nginx_passenger"},
        :instance_id=>"i-50cf5838",
        :group_id=>"ey-my_staging-XXXXXXXXXXXXXXXXXXXX",
        :root_device_type=>"instance-store",
        :private_ip_address=>"10.201.102.201",
        :kernel_id=>"aki-9b00e5f2",
        :placement=>{:availabilityZone=>"us-east-1a"},
        :product_codes=>nil,
        :image_id=>"ami-7044a419",
        :reason=>nil,
        :dns_name=>"ec2-67-201-47-30.compute-1.amazonaws.com",
        :ip_address=>"199.99.99.99",
        :architecture=>"i386",
        :role=>"db_master",
        :monitoring=>{:state=>"disabled"}}

== A note on caching and network needs

I tried to be smart about caching the results of network calls.

Stuff like the present instance id, which is pulled from an EC2 metadata server, is stored in

  ~/.ey_cloud_awareness/engine_yard_cloud_instance_id

Please let me know if this causes problems.

== Copyright

Copyright (c) 2009, 2010 Seamus Abshere. See LICENSE for details.