= engineyard-metadata

Presents a simple, unchanging interface to get metadata about your EngineYard AppCloud instances running on Amazon EC2.

== Purpose

To define an unchanging interface to useful metadata (passwords, IP addresses, etc.) that is otherwise buried deep inside EngineYard's chef config files and various API calls.

== Examples

* Get a dynamically updated list of all running app servers so that you can pool memcached over all of them. (<tt>EY::Metadata.app_servers</tt>)
* Get the current database password so that you can write a script that connects to it. (<tt>EY::Metadata.database_password</tt>)

Here's the current method list:

	EY::Metadata.app_master
	EY::Metadata.app_name
	EY::Metadata.app_servers
	EY::Metadata.app_slaves
	EY::Metadata.current_path
	EY::Metadata.database_host
	EY::Metadata.database_name
	EY::Metadata.database_password       (only works from cloud instances)
	EY::Metadata.database_username
	EY::Metadata.db_master
	EY::Metadata.db_servers
	EY::Metadata.db_slaves
	EY::Metadata.environment_name
	EY::Metadata.mysql_command           (only works from cloud instances)
	EY::Metadata.mysqldump_command       (only works from cloud instances)
	EY::Metadata.present_instance_id     (only works from cloud instances)
	EY::Metadata.present_instance_role   (only works from cloud instances)
	EY::Metadata.present_public_hostname (only works from cloud instances)
	EY::Metadata.present_security_group  (only works from cloud instances)
	EY::Metadata.repository_uri
	EY::Metadata.shared_path
	EY::Metadata.solo
	EY::Metadata.ssh_aliases
	EY::Metadata.ssh_password            (only works from cloud instances)
	EY::Metadata.ssh_username
	EY::Metadata.stack_name
	EY::Metadata.utilities

== Use

See the rdoc at {the engineyard-metadata rdoc}[http://rubydoc.info/gems/engineyard-metadata].

=== When you're executing this gem from INSIDE the cloud

When you're executing the gem from your instances, you don't have to configure anything. Just require the gem.

=== When you're executing this gem from OUTSIDE the cloud

You must...

* have <tt>~/.eyrc</tt> or set <tt>EY::Metadata.ey_cloud_token=</tt> or set <tt>ENV['EY_CLOUD_TOKEN']</tt>.
* execute the gem from the local copy of your application's repo or set <tt>EY::Metadata.environment_name=</tt> or set <tt>ENV['EY_ENVIRONMENT_NAME']</tt>.

=== Where the methods are defined

Metadata getters are defined directly on <tt>EY::Metadata</tt> (which in turn delegates out to various adapters). Even if EngineYard changes the structure of the config files or Amazon EC2's API changes, these methods will stay the same.

  [...]
  >> require 'rubygems'
  [...]
  >> require 'engineyard-metadata'
  [...]
  >> EY::Metadata.database_host
  => "external_db_master.compute-1.amazonaws.com"
  >> EY::Metadata.app_servers
  => [ 'app_1.compute-1.amazonaws.com' , 'app_master.compute-1.amazonaws.com' ]
  >> EY::Metadata.db_servers
  => [ 'db_master.compute-1.amazonaws.com', 'db_slave_1.compute-1.amazonaws.com' ]
  [...and many more...]

== SSH alias helper

You can put the output of <tt>ey_ssh_aliases</tt> into <tt>~/.ssh/config</tt>:

	$ EY_ENVIRONMENT_NAME=my_env ey_ssh_aliases 
	Host my_env-app_master
	  Hostname ec2-11-11-111-11.compute-1.amazonaws.com
	  User deploy
	  StrictHostKeyChecking no

	Host my_env-db_master
	  Hostname ec2-111-11-11-11.compute-1.amazonaws.com
	  User deploy
	  StrictHostKeyChecking no

== Known issues

* Doesn't work with multiple apps per environment.
* It's not always clear what environment you're running in. For example, you say <tt>EY::Metadata.something</tt> and you're just supposed to know what environment you're in. You can use <tt>.environment_name=</tt>, but you might not remember.
* There are no factory methods. If we fully fleshed this out, it might be like <tt>my_env = EY::Environment.find('my_env')</tt> and <tt>my_app_master = my_env.app_master</tt>. Not sure that complexity would add a lot of value.

== History

This is the second generation of http://rubygems.org/gems/ey_cloud_awareness.

== Copyright

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