moose-inventory 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9406c59a0185749227febf07cb62cb0e3d273955
-  data.tar.gz: 063fba0f37a46d48ce9f4be6aee93ba3cd3d32e4
+  metadata.gz: a74c387f707f28fecdfe36ce2e7a11f8e94ba110
+  data.tar.gz: ba4e95aa06b584b7d85c6bde61b1c17bac7ff12b
 SHA512:
-  metadata.gz: 756f88cac996b96406384956ae9c70508fe4cbdf80565a188fab545a4cf5d52ee92fbef20acde57565f2bfa42b1d8ddaf0bb4a5e238ab232398be93376402d30
-  data.tar.gz: d696b2bfba34799daba4181d21c028785a97ff020367efa8e2b4b5fc857e2c453947802a63e52db3d23fb4cbf05b79f5d63fb189c3635a83da567e137e337afb
+  metadata.gz: 73a32a18f9c11cf4a9537f8368a457cb9167437b7abccd630d0ade37ec0a16978df3541c725c1ab1cc96958267e413e87b3a06131852795987c561daf406bd0c
+  data.tar.gz: f0e56af87553103d042b8bb057ca2ce06c78adacb06add897154ef9e9fb6f41a043e008e3396c13182e1a01e8f39ef926b8fbf29c9886c16000be72eaa860f8e

data/.gitignore

@@ -16,3 +16,4 @@ mkmf.log
 .project
 /coverage/
 *.gem
+/gems/

data/README.md

@@ -1,8 +1,8 @@
-# Moose::Inventory
+# 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). 
 
-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. 
+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
 
@@ -16,30 +16,32 @@ And then execute:
 
     $ bundle
 Or install it yourself as:
-
-    $ gem install moose-inventory
+```ruby
+$ gem install moose-inventory
+```
 
 ## Configuration
 The [moose-inventory](https://github.com/RusDavies/moose-inventory) tool makes use of a simple YAML configuration file.  
 
 
-###Location
+###File Location
  
 The following locations, in descending order of precedence, are  searched for a configuration file:
- 1. location passed via the *config* CLI option
+
+ 1. location passed via the *-<sp>-config* CLI 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 contains 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:
   defaultenv: moose_dev
 
-moose_dev:
+moose_dev: 
   db:
     adapter: "sqlite3"
     file:    "~/.moose/db/dev.db"
@@ -62,29 +64,303 @@ another_example_section:
 
 ```
 
-###The 'general' section
-The general section is mandatory, and contains a single parameter **defaultenv**, which points to the name of the default environment section.   This is used in the case when no target environment is specified via the command line. 
+###The *general* section
+The general section is mandatory, and contains a single parameter **defaultenv**, which points to the name of the default environment section.   
 
 ###Environment sections
 You may add as many environment sections as you desire. The intention is to enable the user to easily manage multiple environments, such as development, staging, production, etc., via a single configuration file.  The name of each environment section must be unique, but can otherwise be any valid YAML tag.
 
-At present,  each environment section contains only a **db** subsection, describing the database connection parameters.  Additional subsections may be added in the future, as functionality increases. 
+At present,  each environment section contains only a **db** subsection, describing database connection parameters.  Additional subsections may be added in the future, as functionality increases. 
 
-Each **db** section must include an **adapter** parameter. Currently supported adapter types are sqlite3, mysql, and postresql.  Note, as a matter of portability, only sqlite3 has been exercised via the test suite. 
+Each **db** section must include an **adapter** parameter. Currently supported adapter types are *sqlite3*, *mysql*, and *postresql*.  Note, as a matter of portability, only *sqlite3* is exercised via the test suite. 
 
-Additional parameters are also required in the **db** subsection, depending on the adapter type.   For the sqlite3 adapter only a **file** parameter is required.  For both mysql and postgresql, then **host**, **database**, **user**, and **password** parameters are required. 
+Additional parameters are also required in the **db** subsection, depending on the adapter type.   For the *sqlite3* adapter only a **file** parameter is required.  For both *mysql* and *postgresql*, then **host**, **database**, **user**, and **password** are the required parameters. 
 
 
 ## Usage
+### The help system
+The tool itself provides a convenient help feature.  For example, 
+
+    > moose-inventory help
+    Commands:
+      moose-inventory group ACTION    # Manipulate groups in…
+      moose-inventory help [COMMAND]  # Describe available c…
+      ⋮
+
+and, 
+
+    > moose-inventory help group
+    Commands:
+      moose-inventory group add NAME  # Add a group NAME to …
+      moose-inventory group list      # List the groups, tog…
+      ⋮
+
+and,
+
+    > moose-inventory group help add
+    Usage:
+      moose-inventory add NAME
+    
+    Options:
+      [--hosts=HOSTS]  
+    
+    Add a group NAME to the inventory
+
+###Global switches
+Not described in the built-in help system are a handful of top-level switches, as follows. 
+
+#### - -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 see in standard locations, see later.
+
+For example, 
+
+    > moose-inventory --config ./my_conf host list
+
+#### - -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. 
+
+For example, 
+
+    > moose-inventory --env my_section host list
+
+#### - - 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. 
+
+For example,
+
+    > moose-inventory --format yaml host list
+    ---
+    :test1:
+      :groups:
+        - ungrouped
+
+###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
+In this example, we will walk through the process of creating two hosts and two groups, assigning variables to each, and then then associating hosts with groups.  Once done, we will then remove each association, variable, group and host.  
+
+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
+    Add host 'host1':
+      - creating host 'host1'...
+        - OK
+      - add automatic association {host:host1 <-> group:ungrouped}...
+        - OK
+      - all OK
+    Add host 'host2':
+      - creating host 'host2'...
+        - OK
+      - add automatic association {host:host2 <-> group:ungrouped}...
+        - OK
+      - all OK
+    Add host 'host3':
+      - creating host 'host3'...
+        - OK
+      - add automatic association {host:host3 <-> group:ungrouped}...
+        - OK
+      - all OK
+    Succeeded.
+
+Notice that each host is initially associated with an automatic group, *ungrouped*.   
+
+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
+    {
+      "host1": {
+        "groups": [
+          "ungrouped"
+        ]
+      },
+      "host2": {
+        "groups": [
+          "ungrouped"
+        ]
+      },
+      "host3": {
+        "groups": [
+          "ungrouped"
+        ]
+      }
+    }
+
+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
+    ---
+    :host3:
+      :groups:
+      - ungrouped
+    :host1:
+      :groups:
+      - ungrouped
+
+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
+    Add variables 'owner=russell,id=12345' to host 'host1':
+      - retrieve host 'host1'...
+        - OK
+      - add variable 'owner=russell'...
+        - OK
+      - add variable 'id=12345'...
+        - OK
+      - all OK
+    Succeeded.
+    
+    > moose-inventory host addvar host2 owner=caroline id=54321
+    Add variables 'owner=caroline,id=54321' to host 'host2':
+      - retrieve host 'host2'...
+        - OK
+      - add variable 'owner=caroline'...
+        - OK
+      - add variable 'id=54321'...
+        - OK
+      - all OK
+    Succeeded.
+
+Let's list our hosts again, to see what that looks like.
+
+    > moose-inventory host list --format yaml
+    ---
+    :host1:
+      :groups:
+      - ungrouped
+      :hostvars:
+        :owner: russell
+        :id: '12345'
+    :host2:
+      :groups:
+      - ungrouped
+      :hostvars:
+        :owner: caroline
+        :id: '54321'
+    :host3:
+      :groups:
+      - ungrouped
+
+As you can see, the hosts with variables each have a new section, hostvars, in which those variables are listed.  Try also with *--format pjson*.
+
+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
+
+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 
+    Associate group 'group1' with host(s) 'host1,host2':
+      - retrieve group 'group1'...
+        - OK
+      - add association {group:group1 <-> host:host1}...
+        - OK
+      - remove automatic association {group:ungrouped <-> host:host1}...
+        - OK
+      - add association {group:group1 <-> host:host2}...
+        - OK
+      - remove automatic association {group:ungrouped <-> host:host2}...
+        - OK
+      - all OK
+    Succeeded.
+
+or one or more groups with a host,
+
+    > moose-inventory host addgroup host3 group2 group3 
+    Associate host 'host3' with groups 'group2,group3':
+      - Retrieve host 'host3'...
+        - OK
+      - Add association {host:host3 <-> group:group2}...
+        - OK
+      - Add association {host:host3 <-> group:group3}...
+        - OK
+      - Remove automatic association {host:host3 <-> group:ungrouped}...
+        - OK
+      - All OK
+    Succeeded
+
+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
+    ---
+    :ungrouped: {}
+    :group1:
+      :hosts:
+      - host1
+      - host2
+      :groupvars:
+        :location: usa
+    :group2:
+      :hosts:
+      - host3
+    :group3:
+      :hosts:
+      - host3
+
+We can also list hosts, to get the host-centric view.
+
+    ---
+    :host1:
+      :groups:
+      - group1
+      :hostvars:
+        :owner: russell
+        :id: '12345'
+    :host2:
+      :groups:
+      - group1
+      :hostvars:
+        :owner: caroline
+        :id: '54321'
+    :host3:
+      :groups:
+      - group2
+      - group3
+
+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
+
+### Using moose-inventory with Ansible
+For integration with Ansible, a shim script should be used, in order to set the correct configuration file, environment, etc.  
+
+A trivial shim script, to be provided to Ansible as the [external inventory script](http://docs.ansible.com/intro_dynamic_inventory.html), may look like this, 
+```bash
+#!/bin/bash
+
+CONF='./example.conf'
+ENV='dev'
+
+moose-inventory --config $CONF --env $ENV $@
+
+exit $?
+```
+When Ansible calls the external inventory script, it does so using the certain parameters, which *moose-inventory* recognises.  The Ansible parameters, and their equivalent *moose-inventory* native parameters are shown below. 
+
+Ansible params   | moose-inventory params
+---------------- |-------------
+-<sp>-hosts      | host list    
+-<sp>-hosts HOST | host get HOST
+--groups         | group list      
+
+Note, the above conversions are done automatically by the tool, and are included here only for reference. 
+
+With *moose-inventory* installed and configured, and a shim script (e.g. shim.sh) in place, then using Ansible would be a bit like this: 
+
+    ansible -i shim.sh -u ubuntu us-east-1d -m ping
 
 ##Missing features
 The following desired features are yet to be implemented:
-1. Groups as children of groups:
--- Group model shall provide a many-to-many relationship to self.
--- CLI:Group shall provided an addchild method.
--- CLI:Group shall provided a rmchild method.
--- CLI:Group.get method shall display child group relationships.
--- CLI:Group.list method shall display child group relationships.
+
+1. Groups of groups
 
 ## Contributing
 1. Fork it (https://github.com/RusDavies/moose-inventory/fork )
@@ -92,3 +368,14 @@ The following desired features are yet to be implemented:
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+
+    
+
+
+
+
+
+
+
+

data/config/dotfiles/gitignore

@@ -16,3 +16,4 @@ mkmf.log
 .project
 /coverage/
 *.gem
+/gems/

data/lib/moose_inventory/config/config.rb

@@ -23,8 +23,9 @@ module Moose
       def self.init(args)
         @_argv = args.dup
 
+        top_level_help
         top_level_args
-        # ansible_args
+        ansible_args
         resolve_config_file
         load
       end
@@ -65,28 +66,44 @@ module Moose
         
       end
 
+      #----------------------
+      def self.top_level_help
+        if @_argv[0] == 'help'
+          puts "Global flags:"
+          printf "  %-31s %-10s", "--config FILE", "# Specified configuration file to use\n"
+          printf "  %-31s %-10s", "--config FILE", "# Specifies a configuration file to use\n"
+          printf "  %-31s %-10s", "--env ENV", "# Specifies the environment section of the config to use\n"
+          printf "  %-31s %-10s", "--format yaml|json|pjson", "# Format for the output of 'get' and 'list'\n"
+          puts "\nAnsible flags:"
+          printf "  %-31s %-10s", "--hosts", "# Retrieves the list of hosts (alias for 'host list'\n"
+          printf "  %-31s %-10s", "--hosts HOST", "# Retrieves the specified host (alias for 'host get HOST')\n"
+          printf "  %-31s %-10s", "--groups", "# Retrieves the list of groups (alias for 'group list')\n\n"
+        end
+      end
+      
       #----------------------
       def self.ansible_args  # rubocop:disable Metrics/AbcSize
         # Handle Ansible flags
-        # --hosts           => list all hosts
-        # --hosts HOSTNAME  => get host name
-        # --groups          => list all groups
+        # --hosts           => host list
+        # --hosts HOSTNAME  => host get HOSTNAME
+        # --groups          => lgroup list
 
         if @_argv[0] == '--hosts'
           host = @_argv[1]
           if !host.nil?
             @_argv.clear
-            ['host', 'get', "#{host}", '--ansiblestyle'].each do |arg|
+            ['host', 'get', "#{host}"].each do |arg|
               @_argv << arg
             end
           else
             @_argv.clear
-            ['host', 'list', '--ansiblestyle'].each do |arg|
+            ['host', 'list'].each do |arg|
               @_argv << arg
             end
           end
         elsif @_argv[0] == '--groups'
-          ['group', 'list', '--ansiblestyle'].each do |arg|
+          @_argv.clear
+          ['group', 'list'].each do |arg|
             @_argv << arg
           end
         end

data/lib/moose_inventory/version.rb

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

data/scripts/work-through.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+moose-inventory help
+moose-inventory help group
+moose-inventory group help add
+moose-inventory host add host1 host2 host3
+moose-inventory host list --format pjson
+moose-inventory host get host3 host1 --format yaml
+moose-inventory host addvar owner=russell
+moose-inventory host addvar host1 owner=russell id=12345
+moose-inventory host addvar host2 owner=caroline id=54321
+moose-inventory host list --format yaml
+moose-inventory group add group1 group2 group3
+moose-inventory group list --format yaml
+moose-inventory group get ungrouped group3 --format yaml
+moose-inventory group addvar location=usa
+moose-inventory group addvar group1 location=usa
+moose-inventory group addhost group1 host1 host2 
+moose-inventory host addgroup host3 group2 group3 
+moose-inventory group list --format yaml
+moose-inventory host list --format yaml
+moose-inventory group rmvar group1 location
+moose-inventory group list --format y
+moose-inventory group rm group1 group2 group3
+moose-inventory host rmvar host1 owner id
+moose-inventory host rm host1 host2 host3
+moose-inventory host list
+moose-inventory group list

data/spec/lib/moose_inventory/cli/group_list_spec.rb

@@ -21,6 +21,7 @@ RSpec.describe Moose::Inventory::Cli::Group do
     @db = Moose::Inventory::DB
     @db.init if @db.db.nil?
 
+    @console = Moose::Inventory::Cli::Formatter
     @group = Moose::Inventory::Cli::Group
     @app = Moose::Inventory::Cli::Application
   end
@@ -70,10 +71,32 @@ RSpec.describe Moose::Inventory::Cli::Group do
 
       expected(actual, desired)
     end
-#    #---------------------
-#    it 'host list ... should display hostvars, if any are set' do
-#       Covered by 'should get a list of hosts from the db'
-#    end
+
+    #---------------------
+    it 'should be an alias of --groups (i.e. Ansible parameter)' do
+      
+      host_name = 'test_host'
+
+      mock = {}
+      groups = %w(group1 group2 group3)
+      groups.each do |name|
+        runner { @app.start(%W(group add #{name})) }
+        mock[name.to_sym] = {}
+      end
+    
+      args = @mockargs.clone
+      args << "--groups"
+      cli = Moose::Inventory::Cli 
+    
+      actual = runner{ cli.start(args) }
+        
+      #@console.out(actual, 'y')
+       
+      desired = { aborted: false, STDOUT: '', STDERR: '' }
+      desired[:STDOUT] = mock.to_yaml
+    
+      expected(actual, desired)
+    end    
     
   end
 end

data/spec/lib/moose_inventory/cli/host_get_spec.rb

@@ -101,6 +101,33 @@ RSpec.describe Moose::Inventory::Cli::Host do
        
       expected(actual, desired)
     end
+    
+    #---------------------
+    it 'should be an alias of --hosts HOST (i.e. Ansible parameter)' do
+      
+      mock = {}
+      host = 'host1'
+
+      runner { @app.start(%W(host add #{host})) }
+      mock[host.to_sym] = {}
+      mock[host.to_sym][:groups] = ['ungrouped']
+    
+      args = @mockargs.clone
+      args << '--hosts'
+      args << "#{host}"
+      cli = Moose::Inventory::Cli 
+    
+      # items should now be in the db
+      actual = runner{ cli.start(args) }
+        
+      #@console.out(actual, 'y')
+      
+      desired = { aborted: false, STDOUT: '', STDERR: '' }
+      desired[:STDOUT] = mock.to_yaml
+    
+      expected(actual, desired)
+    end
+    
         
   end
 end

data/spec/lib/moose_inventory/cli/host_list_spec.rb

@@ -16,7 +16,7 @@ RSpec.describe Moose::Inventory::Cli::Host do
     @mockarg_parts.each do |key, val|
       @mockargs << "--#{key}"
       @mockargs << val
-    end
+    end 
 
     @config = Moose::Inventory::Config
     @config.init(@mockargs)
@@ -24,6 +24,7 @@ RSpec.describe Moose::Inventory::Cli::Host do
     @db = Moose::Inventory::DB
     @db.init if @db.db.nil?
 
+    @console = Moose::Inventory::Cli::Formatter
     @host = Moose::Inventory::Cli::Host
     @app = Moose::Inventory::Cli::Application
   end
@@ -75,9 +76,30 @@ RSpec.describe Moose::Inventory::Cli::Host do
       expected(actual, desired)
     end
     #---------------------
-    #it 'host list ... should display hostvars, if any are set' do
-    # Covered by 'should get a list of hosts from the db'
-    #end
+    it 'should be an alias of --hosts (i.e. Ansible parameter)' do
+      
+      mock = {}
+      hosts = %w(host1 host2)
+      hosts.each do |name|
+        runner { @app.start(%W(host add #{name})) }
+        mock[name.to_sym] = {}
+        mock[name.to_sym][:groups] = ['ungrouped']
+      end
+
+      args = @mockargs.clone
+      args << "--hosts"
+      cli = Moose::Inventory::Cli 
+
+      # items should now be in the db
+      actual = runner{ cli.start(args) }
+        
+      #@console.out(actual, 'y')
+      
+      desired = { aborted: false, STDOUT: '', STDERR: '' }
+      desired[:STDOUT] = mock.to_yaml
+
+      expected(actual, desired)
+    end
     
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moose-inventory
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Russell Davies
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-07 00:00:00.000000000 Z
+date: 2015-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: indentation
@@ -263,7 +263,6 @@ files:
 - Guardfile
 - LICENSE.txt
 - README.md
-- README.md.orig
 - Rakefile
 - bin/moose-inventory
 - config/dotfiles/coveralls.yml
@@ -302,6 +301,7 @@ files:
 - scripts/guard_quality.sh
 - scripts/guard_test.sh
 - scripts/reports.sh
+- scripts/work-through.sh
 - spec/config/config.yml
 - spec/lib/moose_inventory/cli/application_spec.rb
 - spec/lib/moose_inventory/cli/cli_spec.rb

data/README.md.orig

@@ -1,35 +0,0 @@
-<<<<<<< HEAD
-# Moose::Inventory
-
-TODO: Write a gem description
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'moose-inventory'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install moose-inventory
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Contributing
-
-1. Fork it ( https://github.com/[my-github-username]/moose-inventory/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
-=======
-# TODO
->>>>>>> ce0f5f71b122cc7b740560e875f2fc0a452da107