Add dynamic inventory description to README

Adding initial documentation covering the dynamic inventory
functionality as well as provide an easy method to allow users
to convert their CSV files to JSON documents.

Change-Id: I0730db4c2fd8355df1dfc84c5e7f1de67c1507b9

README.rst

@@ -85,10 +85,83 @@ The following requirements are installed during the Install step above:
 - openstack-infra/shade library
 - openstack-infra/os-client-config
 
-You will also need a CSV file containing information about the hardware you are enrolling.
+In order to enroll hardware, you will naturally need an inventory of your
+hardware. When utilizing the dynamic inventory module and accompanying roles
+this can be supplied in one of three ways, all of which ultimately translate
+to JSON data that Ansible parses.
 
-CSV File Format
----------------
+The original method is to utilize a CSV file.  Its format is below covered in
+the `Legacy CSV File Format` section. This has a number of limitations, but
+does allow a user to bulk load hardware from an inventory list with minimal
+data transformations.
+
+The newer method is to utilize a JSON or YAML document which the inventory
+parser will convert and provide to Ansible.
+
+In order to use, you will need to define the environment variable
+`BIFROST_INVENTORY_SOURCE` to equal a file, which then allows you to
+execute Ansible utilizing the bifrost_inventory.py file as the data source.
+
+Conversion from CSV to JSON formats
+-----------------------------------
+
+The inventory/bifrost_inventory.py program additionally features a mode that
+allows a user to convert a CSV file to the JSON data format utilizing a
+`--convertcsv` command line setting when directly invoked.
+
+Example::
+
+  export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.csv
+  inventory/bifrost_inventory.py --convertcsv >/tmp/baremetal.json
+
+JSON file format
+----------------
+
+The JSON format closely resembles the data structure that Ironic utilizes
+internally.  The name, driver_info, nics, driver, and properties fields are
+directly mapped through to Ironic.  This means that the data contained within
+can vary from host to host, such as drivers and their parameters thus allowing
+a mixed hardware environment to be defined in a single file.
+
+Example::
+
+  {
+      "testvm1": {
+        "uuid": "00000000-0000-0000-0000-000000000001",
+        "driver_info": {
+          "power": {
+            "ssh_port": 22,
+            "ssh_username": "ironic",
+            "ssh_virt_type": "virsh",
+            "ssh_address": "192.168.122.1",
+            "ssh_key_filename": "/home/ironic/.ssh/id_rsa"
+          }
+        },
+        "nics": [
+          {
+            "mac": "52:54:00:f9:32:f6"
+          }
+        ],
+        "driver": "agent_ssh",
+        "ansible_ssh_host": "192.168.122.2",
+        "ipv4_address": "192.168.122.2",
+        "properties": {
+          "cpu_arch": "x86_64",
+          "ram": "3072",
+          "disk_size": "10",
+          "cpus": "1"
+        },
+        "name": "testvm1"
+      }
+  }
+
+The additional power of this format is easy configuration parameter injection,
+which could potentially allow a user to provision different operating system
+images onto different hardware chassis by defining the appropriate settings
+in an "instance_info" variable.
+
+Legacy CSV File Format
+----------------------
 
 The CSV file has the following columns:
 
@@ -108,6 +181,7 @@ The CSV file has the following columns:
 13. ipmi_target_address - Requires: ipmi_bridging set to single
 14. ipmi_transit_channel - Requires: ipmi_bridging set to dual
 15. ipmi_transit_address - Requires: ipmi_bridging set to dual
+16. ironic driver
 
 Example definition::
 

playbooks/inventory/bifrost_inventory.py

@@ -113,6 +113,9 @@ opts = [
     cfg.BoolOpt('list',
                 default=True,
                 help='List active hosts'),
+    cfg.BoolOpt('convertcsv',
+                default=False,
+                help='Converts a CSV inventory to JSON'),
 ]
 
 
@@ -314,10 +317,13 @@ def main():
         exit(1)
 
     # General Data Conversion
-    inventory = {'_meta': {'hostvars': hostvars}}
-    inventory.update(groups)
 
-    print(json.dumps(inventory, indent=2))
+    if not config.convertcsv:
+        inventory = {'_meta': {'hostvars': hostvars}}
+        inventory.update(groups)
+        print(json.dumps(inventory, indent=2))
+    else:
+        print(json.dumps(hostvars, indent=2))
 
 if __name__ == '__main__':
     main()