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
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:
---
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
pool
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.