collins_shell 0.2.14

data/.pryrc

@@ -0,0 +1 @@
+Pry.config.default_asset_format = '{{tag}} {{hostname}} {{status}}'

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ruby-1.9.3

data/Gemfile

@@ -0,0 +1,18 @@
+source :rubygems
+
+Encoding.default_external = Encoding::UTF_8
+
+gem 'collins_client', '~> 0.2.7'
+gem 'highline',       '~> 1.6.15'
+gem 'mustache',       '~> 0.99.4'
+gem 'pry',            '~> 0.9.9.6'
+gem 'rubygems-update','~> 1.8.24'
+gem 'terminal-table', '~> 1.4.5'
+gem 'thor',           '~> 0.16.0'
+
+group :development do
+    gem 'jeweler',      '~> 1.8.3'
+    gem 'redcarpet'
+    gem 'rspec',        '~> 2.10.0'
+    gem 'yard',         '~> 0.8'
+end

data/Gemfile.lock

@@ -0,0 +1,59 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    coderay (1.0.8)
+    collins_client (0.2.7)
+      httparty (~> 0.8.3)
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    highline (1.6.15)
+    httparty (0.8.3)
+      multi_json (~> 1.0)
+      multi_xml
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.5)
+    method_source (0.7.1)
+    multi_json (1.3.6)
+    multi_xml (0.5.1)
+    mustache (0.99.4)
+    pry (0.9.9.6)
+      coderay (~> 1.0.5)
+      method_source (~> 0.7.1)
+      slop (>= 2.4.4, < 3)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    redcarpet (2.2.2)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    rubygems-update (1.8.24)
+    slop (2.4.4)
+    terminal-table (1.4.5)
+    thor (0.16.0)
+    yard (0.8.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  collins_client (~> 0.2.7)
+  highline (~> 1.6.15)
+  jeweler (~> 1.8.3)
+  mustache (~> 0.99.4)
+  pry (~> 0.9.9.6)
+  redcarpet
+  rspec (~> 2.10.0)
+  rubygems-update (~> 1.8.24)
+  terminal-table (~> 1.4.5)
+  thor (~> 0.16.0)
+  yard (~> 0.8)

data/README.md

@@ -0,0 +1,335 @@
+# CollinsShell Description
+
+The collins shell is a lightweight application built on top of the
+`collins_client` gem. The `collins_client` gem provides API access to collins,
+the `collins_shell` application provides CLI API access to collins.
+
+## Installation
+
+    > gem install collins_shell --source=http://repo.tumblr.net:9929
+
+## Setup
+
+Collins shell will look for a yaml file at ~/.collins.yaml, passed in via
+`--config=my_collins.yaml`, or passed in via an environment variable like
+`COLLINS=~/my_collins.yaml`. The file should look like:
+
+    ---
+    collins:
+        host: "http://somehost:8080"
+        username: "user"
+        password: "secret"
+
+You can also specify the host, username, or options via the `--host`,
+`--username` and `--password` options. If you just specify `--password`
+(without a value), or your configs are missing a password, you will be
+prompted for one.
+
+## Overview
+
+There are a few common themes found throughout the collins shell that will
+help you be productive.
+
+### Command Structure
+
+collins-shell uses thor under the hood to handle command line dispatching and
+parsing. Arguments to collins-shell consist of commands, subcommands,
+arguments, and options.
+
+Supported commands and subcommands are:
+
+    asset
+        create
+        delete
+        delete_attribute
+        find
+        get
+        set_attribute
+        set_status
+    console
+    ip_address
+        allocate
+        assets
+        delete
+        delete_all
+        find
+        pools
+        update
+    ipmi
+        create
+        update
+    latest
+    log
+    logs
+    power
+    power_status
+    provision
+        host
+        list
+    tag
+        list
+        values
+    version
+
+All commands are of the form:
+
+    collins-shell <command> <args> <options>
+
+Every command can be described via `help`, e.g. `collins-shell help log` or
+`collins-shell asset help create`. Note that to get help for a subcommand, the
+help directive must come after the command, but before the subcommand.
+
+This returns help for the `asset find` subcommand:
+
+    collins-shell asset help find
+
+This returns help for the `asset` command (the `find` subcommand is ignored):
+
+    collins-shell help asset find
+
+A command is something like `log` or `asset find`. Arguments are required
+options, passed to the command without a switch (e.g. `asset get TAG`, `TAG`
+is an argument there). Options are optional, and generally passed like
+`--option` or `--option=value`.
+
+### Universal Options
+
+The following options can be specified for every command:
+
+    --config=CONFIG       # YAML configuration file
+    --debug               # Debug output
+    --host=HOST           # Collins host (e.g. http://host:port)
+    --quiet               # Mostly used in conjunction with commands that have an --exec option
+    --timeout=SECONDS     # Seconds to allow for operation, defaults to 30
+    --username=USERNAME   # Collins username
+    --password=PASSWORD   # Collins password
+
+
+### Common Options
+
+Many options will allow you to specify either a selector (matching many
+assets) or a tag (matching a single asset). A tag is the asset tag, a selector
+is a space separated list of `key:value` pairs that are asset keys and values.
+Some examples are:
+
+    # Allocated web servers (note that multiple selectors are separated by a space)
+    --selector=hostname:'^web.*' status:Allocated
+    # Allocated master database servers in the main pool
+    --selector=primary_role:database pool:main secondary_role:master status:Allocated
+    # Asset with tag 001923
+    --tag=001923
+
+Note that any time a command will result in changing more than one asset,
+collins-shell  will prompt for confirmation.
+
+# Multi-Collins Support
+
+Collins has a feature called 'multi-collins' that allows multiple collins servers to
+know about each other. This functionality provides a unified view of all assets,
+regardless of which collins server stores a given asset. If you have enabled
+multi-collins, your collins-shell configuration only needs to have credentials and host
+information for one of your collins servers.
+
+By default, collins-shell only interacts a single collins server (the one specified in the configuration file). To run commands against all of your collins servers, pass the `--remote` option.
+
+One exception to this is `asset get`. `asset get` takes `--remote=TAG` where
+tag is the asset tag of the datacenter that has the asset, e.g.
+`--remote=ewr01` or `--remote=d2`.
+
+The following commands support multi-collins:
+
+    asset find
+    asset get (with --remote=DC)
+    asset set_attribute
+    asset delete_attribute
+    asset set_status
+    log
+
+Because `asset find` supports multi-collins, for any commands that don't (e.g.
+`power_status`, it's trivial to script piping the results of the find to some
+other command.
+
+# Usage
+
+## Getting Help
+
+Before using any command, check out the help. You can see help for a command
+by running:
+
+    collins-shell help <command>
+
+or
+
+    collins-shell <sub> help <command>
+
+Where `<sub>` is something like `asset`, `ipmi` or `ip_address` and
+`<command>` is something like `create`, `delete` or `get`. For example
+
+    > collins-shell asset help get
+    Usage:
+      collins-shell asset get TAG
+    
+    Options:
+      --config=CONFIG      # YAML configuration file
+      --debug              # Debug output
+      --host=HOST          # Collins host (e.g. http://host:port)
+      --password=PASSWORD  # Collins password
+      --quiet              # Be quiet when appropriate
+      --timeout=N          # Collins client timeout
+                           # Default: 30
+      --username=USERNAME  # Collins username
+      --confirm            # Require exec confirmation. Defaults to true
+                           # Default: true
+      --exec=EXEC          # Execute a command using the data from this asset. Use {{hostname}}, {{ipmi.password}}, etc for substitution
+      --logs               # Also display asset logs
+      --remote=REMOTE      # Remote location to search. This is a tag in collins corresponding to the datacenter asset
+    
+    get an asset and display its attributes
+
+## Examples
+
+    > collins-shell
+    Tasks:
+      collins-shell asset <command>                         # Asset related commands
+      collins-shell console                                 # drop into the interactive collins shell
+      collins-shell help [TASK]                             # Describe available tasks or one specific task
+      collins-shell ip_address <command>                    # IP address related commands
+      collins-shell ipmi <command>                          # IPMI related commands
+      collins-shell log MESSAGE                             # log a message on an asset
+      collins-shell power ACTION --reason=REASON --tag=TAG  # perform power action (off, on, rebootSoft, rebootHard, etc) on an asset
+      collins-shell power_status --tag=TAG                  # check power status on an asset
+      collins-shell provision <command>                     # Provisioning related commands
+      collins-shell tag <command>                           # Tag related commands
+    > collins-shell asset
+    Tasks:
+      collins-shell asset create --tag=TAG           # create an asset in collins
+      collins-shell asset delete --tag=TAG           # delete an asset in collins (must be cancelled)
+      collins-shell asset delete_attribute KEY       # delete an attribute in collins
+      collins-shell asset find --selector=key value  # find assets using the specified selector
+      collins-shell asset get TAG                    # get an asset and display its attributes
+      collins-shell asset help [COMMAND]             # Describe subcommands or one specific subcommand
+      collins-shell asset set_attribute KEY VALUE    # set an attribute in collins
+      collins-shell asset set_status STATUS          # set status on an asset
+    > collins-shell asset find --selector=status:Allocated 'hostname:^web.*'
+    id,tag,status,type,created,updated
+    18,sl-90918,Allocated,Server Node,2012-02-08T00:34:43+00:00,2012-06-09T00:31:39+00:00
+    20,sl-111623,Allocated,Server Node,2012-02-08T00:34:44+00:00,2012-06-09T01:25:35+00:00
+    21,sl-70108,Allocated,Server Node,2012-02-08T00:34:44+00:00,2012-06-09T00:42:16+00:00
+    23,sl-89121,Allocated,Server Node,2012-02-08T00:34:47+00:00,2012-06-09T00:33:31+00:00
+
+# Tips and Tricks
+
+There are a couple of neat features in the collins shell to be aware of.
+
+## Detailed asset views
+
+I have tried to make the shell as consistent with the web UI as possible. Try
+running a command like:
+
+    collins-shell asset get VALID_TAG_HERE
+
+The display should be familiar to people if you've logged into the web UI.
+
+## Asset Logs
+
+Adding `--logs` to your `asset get` or `asset find` commands will show logs
+for each asset.
+
+## Making find more useful
+
+There are three switches that are useful to know about with the `asset find`
+command.
+
+### awk format
+
+If you need to do some kind of post processing on data not found in the
+default find results, you can specify them via the `--tags` option. This will
+give you a comma separated list of tags, one for each asset. For example:
+
+    collins-shell asset find --selector=hostname:'^web' status:Allocated --tags=hostname addresses
+
+Will provide you a list that might look like:
+
+    hostname,addresses
+    web-7c177b48.d2.tumblr.net,10.80.96.243|10.80.96.1|255.255.248.0,192.172.29.80|192.172.29.65|255.255.255.224
+    web-a1a316af.d2.tumblr.net,10.80.97.95|10.80.96.1|255.255.248.0,192.172.38.108|192.172.38.97|255.255.255.224
+
+The header line tells you the asset tags you are displaying. Each
+line has a comma separated list of values. If a value is an array of some
+sort, values within it are separated by pipes. Easy parsing!
+
+If you would prefer not to display the header line, just add `--header=false` to your find command.
+
+Note there is one caveat, the current version of collins-shell cannot prompt for authentication
+data if you are passing output to a pipe. In order to pass output to a pipe, you must have your
+collins server and credentials defined in ~/.collins.yaml or pass them to collins-shell on the
+command line.
+
+### Detailed output
+
+Try adding `--details` to your `asset find` command to get a detailed asset
+view of each of the assets in the result set.
+
+### Size
+
+Setting `--size=N` (e.g. `--size=1000`) will give you that number of results
+or less. The default is 50 results.
+
+## Friendly Sizes
+
+If you're querying on the `memory_size_total` or `disk_storage_total`, you can
+use human readable values like `72GB` or `2.18298348411918TB`. Yeah, the disk
+one kind of sucks. But, if you do a `get` or `find --details` you can see what
+the correct query value is.
+
+## Execute commands using asset data
+
+Some commands support an `--exec` option that allows you to execute a command
+using the information associated with the asset. An example might be:
+
+    collins-shell asset get TAG \
+      --exec='IPMI_PASSWORD={{ipmi.password}} ipmitool -I lanplus -E -U {{ipmi.username}} -H {{ipmi.address}} sol activate'
+
+This will create a console session using IPMI with the asset specified by `TAG`. Any attributes of an asset
+can be specified as `{{attribute}}`, e.g. `{{hostname}}` or `{{addresses.first.address}}`.
+
+# The Interactive Shell
+
+It is also possible to use collins shell in an interactive mode. You can drop
+into the collins shell console by doing:
+
+    collins-shell console
+
+Be sure to provide your config YAML in the usual way. Once you are in the shell
+you can get a list of global commands by typing `help`. Global commands can be
+used regardless of context. Below is a sample interactive session.
+
+    collins / > ls /
+    ....
+    collins / > cd /PRIMARY_ROLE
+    collins /PRIMARY_ROLE > ls
+    collins /PRIMARY_ROLE > cd DEVEL
+    collins /PRIMARY_ROLE/DEVEL > ls --format='{{hostname}} {{status}} {{tag}}' --grep=blake
+    collins /PRIMARY_ROLE/DEVEL > cd sl-91016
+    collins /PRIMARY_ROLE/DEVEL/sl-91016* > ls
+    collins /PRIMARY_ROLE/DEVEL/sl-91016* > cat -b
+    collins /PRIMARY_ROLE/DEVEL/sl-91016* > cat /var/log/messages
+    collins /PRIMARY_ROLE/DEVEL/sl-91016* > cat /var/log/NOTE
+    collins /PRIMARY_ROLE/DEVEL/sl-91016* > asset.created.to_s
+    collins /PRIMARY_ROLE/DEVEL/sl-91016* > power?
+    collins /PRIMARY_ROLE/DEVEL/sl-91016* > reboot!
+    collins /PRIMARY_ROLE/DEVEL/sl-91016* > cd ../sl-102313
+    collins /PRIMARY_ROLE/DEVEL/sl-102313* > stat
+
+This is all ruby, so you can play with a lot of this data using ruby as you
+would expect. Some examples:
+
+    collins / > ls /HOSTNAME/.*blake.* | {|array| array.map{|a| [a.tag,a.hostname,a.status]}}
+    collins / > hosts = _
+    collins / > hosts.select do |host|
+    collins / *   host[2] == 'Allocated'
+    collins / * end.map do |host|  
+    collins / *   [host[0], host[1], collins_client.with_asset(host[0]).power_status]
+    collins / * end  
+
+The above checks the power status of the selected hosts.

data/Rakefile

@@ -0,0 +1,64 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+require 'jeweler'
+
+jeweler = Jeweler::Tasks.new do |gem|
+  gem.name = 'collins_shell'
+  gem.homepage = 'https://github.com/tumblr/collins/tree/master/support/collins-shell'
+  gem.license = 'APL 2.0'
+  gem.summary = %Q{Shell for Collins API}
+  gem.description = "Provides basic CLI for interacting with Collins API"
+  gem.email = 'bmatheny@tumblr.com'
+  gem.authors = ['Blake Matheny']
+  gem.files.exclude "spec/**/*"
+  gem.files.exclude '.gitignore'
+  gem.files.exclude '.rspec'
+  gem.add_runtime_dependency 'collins_client',  '~> 0.2.7'
+  gem.add_runtime_dependency 'highline',        '~> 1.6.15'
+  gem.add_runtime_dependency 'mustache',        '~> 0.99.4'
+  gem.add_runtime_dependency 'pry',             '~> 0.9.9.6'
+  gem.add_runtime_dependency 'rubygems-update', '~> 1.8.24'
+  gem.add_runtime_dependency 'terminal-table',  '~> 1.4.5'
+  gem.add_runtime_dependency 'thor',            '~> 0.16.0'
+end
+
+task :help do
+  puts("rake -T                  # See available rake tasks")
+  puts("rake publish             # generate gemspec, build it, push it to repo")
+  puts("rake version:bump:patch  # Bump patch number")
+  puts("rake all                 # bump patch and publish")
+  puts("rake                     # Run tests")
+end
+
+task :publish => [:gemspec, :build] do
+  package_abs = jeweler.jeweler.gemspec_helper.gem_path
+  package_name = File.basename(package_abs)
+
+  ["repo.tumblr.net","repo.ewr01.tumblr.net"].each do |host|
+    puts("Copying #{package_abs} to #{host} and installing, you may be prompted for your password")
+    system "scp #{package_abs} #{host}:"
+    system "ssh -t #{host} 'sudo tumblr_gem install #{package_name}'"
+  end
+end
+
+task :all => ["version:bump:patch", :publish] do
+  puts("Done!")
+end
+
+task :default => :yard
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+  t.options = ['--markup', 'markdown']
+end