moose-inventory 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f7a05c05e173698bcbc3b5bcce29ea2c0c7c3bd
-  data.tar.gz: ea46d916c9a5776ce8e3119821ef009fea2e7d4a
+  metadata.gz: 5b88c60df4ba175770a974076cf92e3c1c130d1e
+  data.tar.gz: d7c7481e41f66ff8ea49ed8e64593d3221eb3fcf
 SHA512:
-  metadata.gz: 3437c73ddf392819163040737720441e436a86714d4a682f0d5013e7799668ab19533bd1610d9f25b1d5a8c01dd0b8df77b49d4a9accd13b227e4312602848a3
-  data.tar.gz: f405d9fbc5c6f7415abf9cc0f96762a96c50d0439971be527faee5918d89cce9bc099fc0173c7c7fcae8f83a5e587203353b63e687f3cf1ec35062c83cf3b68b
+  metadata.gz: f3447e95438f00cfbcfb9c14553c5fd68cad6c9d263f4eb00d2f9e61498fd8139d6dff4a6401480d384e5e91e4fc655f9f674582080eff77fd671da6245e16b0
+  data.tar.gz: 5bf036761787ba2ea318dd65f0462d5dffaa7e36bbf63cb0e451c39b7b7e77fc2567adbcb0a4937569469bef5600123b6d2f52c7879909a45abfc5570dc06128

data/README.md

@@ -1,27 +1,21 @@
 # moose-inventory
 
-The [moose-inventory](https://github.com/RusDavies/moose-inventory) Ruby Gem is a package for managing dynamic inventories, intended for use with [Ansible](http://www.ansible.com/home). 
+The [moose-inventory](https://github.com/RusDavies/moose-inventory) software is a tool for managing dynamic inventories, intended for use with [Ansible](http://www.ansible.com/home). 
 
 Note: This software is intended for use on UNIX, Linux, or similar systems.  It will likely not work on Windows, due to some hard-wired search paths - I may fix that in the future but, for now, sorry. 
 
 ## Installation
 
-The tool is a ruby gem. 
-
-It can be install from the command line as follows.
+The tool is a ruby gem. Assuming that you have ruby on your system, then it can be installed from the command line as follows.
 
     $ gem install moose-inventory
 
-Alternatively, it can be installed by adding the following line to a Gemfile:
+It can also be installed by adding the following line to a Gemfile and then executing `bundle`:
 
 ```ruby
 gem 'moose-inventory'
 ```
 
-And then executing:
-
-    $ bundle
-    
 
 ## Configuration
 The [moose-inventory](https://github.com/RusDavies/moose-inventory) tool makes use of a simple YAML configuration file.  
@@ -31,14 +25,14 @@ The [moose-inventory](https://github.com/RusDavies/moose-inventory) tool makes u
  
 The following locations, in descending order of precedence, are  searched for a configuration file:
 
- 1. location passed via the *-<sp>-config* CLI option
+ 1. location passed via the `--config` option
  2. ./.moose-tools/inventory/config
  4. ~/.moose-tools/inventory/config
  5. ~/local/etc/moose-tools/inventory/config
  6. /etc/moose-tools/inventory/config
 
 ###Format
-The file consists of a mandatory *general* section, and at least one environment section. For example: 
+The file consists of a mandatory *general* section, and at least one *environment* section. For example: 
 ```yaml
 ---
 general:
@@ -84,32 +78,32 @@ Additional parameters are also required in the **db** subsection, depending on t
 ### The help system
 The tool itself provides a convenient help feature.  For example, try each of the following,
 
-    > moose-inventory help
-    > moose-inventory help group
-    > moose-inventory group help add
+    $ moose-inventory help
+    $ moose-inventory help group
+    $ moose-inventory group help add
 
 ###Global switches
 
 #### Option `--config <FILE>`
-The *--config* flag sets the configuration file to be used.  If specified, then the file must exist. This takes precedence over all other config files in other locations.  If not provided, then the default is to search standard locations, see later.
+The `--config` flag sets the configuration file to be used.  If specified, then the file must exist. This takes precedence over all other config files in other locations.  If not provided, then the default is to search the locations previously mentioned.
 
 For example, 
 
-    > moose-inventory --config ./my_conf host list
+    $ moose-inventory --config ./mystuff.conf host list
 
 #### Option `--env <SECTION>`
-The *--env* flag sets the section in the configuration file to be used as the environment configuration.  If set, then the section must exist.  If not set, then what ever default is provided in the general::defaultenv parameter of the configuration file will be used. 
+The *--env* flag sets the section in the configuration file to be used as the environment configuration.  If set, then the section must exist.  If not set, then what ever default is provided by the **defaultenv** parameter will be used. 
 
 For example, 
 
-    > moose-inventory --env my_section host list
+    $ moose-inventory --env my_section host list
 
 #### Option `--format <yaml|json|pjson>`
-The *--format* switch changes the output format from *list* and *get* operations.  Valid formats are yaml, json, pjson (i.e. pretty JSON).   If the switch is not given, then the default is json. 
+The `--format` switch changes the output format for *list* and *get* operations.  Valid formats are yaml, json, pjson (i.e. pretty JSON).   If the switch is not given, then the default is json.
 
 For example,
 
-    > moose-inventory --format yaml host list
+    $ moose-inventory --format yaml host list
     ---
     :test1:
       :groups:
@@ -118,12 +112,12 @@ For example,
 ###Transactional Behaviour
 The *moose-inventory* tool performs database operations in a transactional manner.  That is to say, either all operations of a command succeed, or they are all rolled back.  
 
-###Walk-through examples
+###Walk-through example
 This walk-through goes through the process of creating three hosts and three groups, assigning variables to some of each, and then associating hosts with groups.  Once done, each association, variable, group, and host are removed.  
 
 We start by creating three hosts, in this case named *host1*,  *host2*, and *host3*.  Note, we can add as many hosts as we desire via this single command.  Also, although we have used short names here, we could equally have used fully qualified names. 
 
-    > moose-inventory add host host1 host2 host3
+    $ moose-inventory add host host1 host2 host3
     Add host 'host1':
       - creating host 'host1'...
         - OK
@@ -148,7 +142,7 @@ Notice that each host is initially associated with an automatic group, *ungroupe
 
 Now we can list our hosts, to see that they are stored as expected.  In this example, we will request the output be formatted as YAML.  If we didn't specify a format, then it would default to regular JSON.
 
-    > moose-inventory host list --format pjson
+    $ moose-inventory host list --format pjson
     {
       "host1": {
         "groups": [
@@ -169,7 +163,7 @@ Now we can list our hosts, to see that they are stored as expected.  In this exa
 
 The *host list* command simply lists all hosts, in the order that they were entered into the database.  We can also get a specific host, or hosts, by name.  In this example, we'll get only *host3* and *host1*, outputting the result in YAML.  
 
-    > moose-inventory host get host3 host1 --format yaml
+    $ moose-inventory host get host3 host1 --format yaml
     ---
     :host3:
       :groups:
@@ -180,7 +174,7 @@ The *host list* command simply lists all hosts, in the order that they were ente
 
 Now we'll add some host variables.  Again, we can add as many variables to a host as we desire.
 
-    > moose-inventory host addvar host1 owner=russell id=12345
+    $ moose-inventory host addvar host1 owner=russell id=12345
     Add variables 'owner=russell,id=12345' to host 'host1':
       - retrieve host 'host1'...
         - OK
@@ -191,7 +185,7 @@ Now we'll add some host variables.  Again, we can add as many variables to a hos
       - all OK
     Succeeded.
     
-    > moose-inventory host addvar host2 owner=caroline id=54321
+    $ moose-inventory host addvar host2 owner=caroline id=54321
     Add variables 'owner=caroline,id=54321' to host 'host2':
       - retrieve host 'host2'...
         - OK
@@ -204,7 +198,7 @@ Now we'll add some host variables.  Again, we can add as many variables to a hos
 
 Let's list our hosts again, to see what that looks like.
 
-    > moose-inventory host list --format yaml
+    $ moose-inventory host list --format yaml
     ---
     :host1:
       :groups:
@@ -226,15 +220,15 @@ As you can see, the hosts with variables each have a new section, hostvars, in w
 
 We can do the same with groups.  In the following example, the output has been omitted for compactness. Nevertheless, you will see that the form of the commands is as for hosts.  Of note, when listing the groups, you will see that the *ungrouped* group is shown.   This is an automatic group which cannot be manipulated manually. 
 
-    > moose-inventory group add group1 group2 group3
-    > moose-inventory group list --format yaml
-    > moose-inventory group get ungrouped group2 --format yaml
-    > moose-inventory group addvar group1 location=usa
-    > moose-inventory group addvar group2 location=europe
+    $ moose-inventory group add group1 group2 group3
+    $ moose-inventory group list --format yaml
+    $ moose-inventory group get ungrouped group2 --format yaml
+    $ moose-inventory group addvar group1 location=usa
+    $ moose-inventory group addvar group2 location=europe
 
 At this point, we have three hosts and three groups, some of each with variables.  Let's now associate hosts with groups.  We can either associate one or more hosts with a group,
 
-    > moose-inventory group addhost group1 host1 host2 
+    $ moose-inventory group addhost group1 host1 host2 
     Associate group 'group1' with host(s) 'host1,host2':
       - retrieve group 'group1'...
         - OK
@@ -251,7 +245,7 @@ At this point, we have three hosts and three groups, some of each with variables
 
 or one or more groups with a host,
 
-    > moose-inventory host addgroup host3 group2 group3 
+    $ moose-inventory host addgroup host3 group2 group3 
     Associate host 'host3' with groups 'group2,group3':
       - Retrieve host 'host3'...
         - OK
@@ -266,7 +260,7 @@ or one or more groups with a host,
 
 Notice in each of the two above excepts, the group *ungrouped* is automatically removed from each host, as it gains one or more group associations.  Now we can again list our groups, to see what we have.
 
-    > moose-inventory group list --format yaml
+    $ moose-inventory group list --format yaml
     ---
     :ungrouped: {}
     :group1:
@@ -304,13 +298,14 @@ We can also list hosts, to get the host-centric view.
 
 Removing variables, groups, and hosts is just as easy.  In the following examples, the output is again omitted for compactness; the reader is encouraged to work along to experience the tool.  Note, that although we show how to remove the variables, it is not strictly necessary to do so in this example, since deleting hosts and groups would delete all associated variables anyway. 
 
-    > moose-inventory group rmvar group1 location
-    > moose-inventory group rm group1 group2 group3
-    > moose-inventory host rmvar
-    > moose-inventory host rmvar host1 owner id
-    > moose-inventory host rm host1 host2 host3
+    $ moose-inventory group rmvar group1 location
+    $ moose-inventory group rm group1 group2 group3
+    $ moose-inventory host rmvar
+    $ moose-inventory host rmvar host1 owner id
+    $ moose-inventory host rm host1 host2 host3
 
 ### Using moose-inventory with Ansible
+
 The *moose-inventory* tool is compliant with the Ansible specifications for [dynamic inventory sources](http://docs.ansible.com/developing_inventory.html).
 
 However, to make use of *moose-inventory's* multiple environment and configuration file options, a shim script should be used as the target for the [external inventory script](http://docs.ansible.com/intro_dynamic_inventory.html). A trivial example may look something like this,  
@@ -325,25 +320,34 @@ moose-inventory --config $CONF --env $ENV $@
 
 exit $?
 ```
-When Ansible calls the external inventory script, it does so using certain parameters, which *moose-inventory* automatically recognises and responds to.  The Ansible parameters, and their equivalent *moose-inventory* parameters are shown below. 
+When Ansible calls the external inventory script, it passes certain parameters, which *moose-inventory* automatically recognises and responds to.  The Ansible parameters, and their equivalent *moose-inventory* parameters are shown below. 
 
 Ansible          | moose-inventory
 ---------------- |-------------
 `--list`         | `--ansible group list`    
 `--host HOSTNAME` | `--ansible host listvars HOSTNAME`
 
-Note, the above conversions are done **automatically** within *moose-inventory*. 
+Note, the above conversions are performed automatically within *moose-inventory*. 
 
-With *moose-inventory* installed and configured, and a shim script (e.g. *shim.sh*) in place, then use by Ansible can be acheived via Ansible's `-i` option.
+With *moose-inventory* installed and configured, and a shim script (e.g. *shim.sh*) in place, then integration with Ansible can be acheived via Ansible's `-i <file>` option.
 
     ansible -i shim.sh -u ubuntu us-east-1d -m ping
 
-Alternatively, if you are using an [Ansible configuration file](http://docs.ansible.com/intro_configuration.html), then you can set the [inventory](http://docs.ansible.com/intro_configuration.html#inventory) option,
+Alternatively, if using an [Ansible configuration file](http://docs.ansible.com/intro_configuration.html), then one may set the [inventory](http://docs.ansible.com/intro_configuration.html#inventory) option,
 
     inventory = ./shim.sh
     
 Yet another option is to copy the shim script to */etc/ansible/hosts* and `chmod +x` it.  However, since this would essentially fix the config file and environment used, doing so would defeat the flexibility intended for *moose-inventory*.    
 
+To persist data from Ansible to the inventory, simply call the shim script via a local_action command, for example:
+
+```shell
+- set_fact: mydata="Hello World"
+- local_action: command shim.sh host addvar {{ ansible_host }} mydata={{ mydata }} 
+```
+
+
+ 
 ## Contributing
 1. Fork it (https://github.com/RusDavies/moose-inventory/fork )
 2. Create your feature branch (git checkout -b my-new-feature`)

data/lib/moose_inventory/cli/application.rb

@@ -17,12 +17,12 @@ module Moose
 
         desc 'group ACTION',
              'Manipulate groups in the inventory. ' \
-             'ACTION can be add, rm, addhost, rmhost, addvar, rmvar'
+             'ACTION can be add, rm, get, list, addhost, rmhost, addchild, rmchild, addvar, rmvar'
         subcommand 'group', Moose::Inventory::Cli::Group
 
         desc 'host ACTION',
              'Manipulate hosts in the inventory. ' \
-             'ACTION can be add, rm, addgroup, rmgroup, addvar, rmvar'
+             'ACTION can be add, rm, get, list, addgroup, rmgroup, addvar, rmvar'
         subcommand 'host', Moose::Inventory::Cli::Host
       end
     end

data/lib/moose_inventory/version.rb

@@ -2,6 +2,6 @@ module Moose
   ##
   # The Moose-Tools dynamic inventory management library
   module Inventory
-    VERSION = '1.0.2'
+    VERSION = '1.0.3'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moose-inventory
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Russell Davies