Merge pull request #4914 from immarvin/xcat-inventory

add usercase for xcat-inventory

docs/source/advanced/index.rst

@@ -26,3 +26,4 @@ Advanced Topics
    softlayer/index.rst
    sysclone/index.rst
    zones/index.rst
+   xcat-inventory/index.rst

docs/source/advanced/xcat-inventory/define_create_cluster.rst

@@ -0,0 +1,28 @@
+Define and create your first xCAT cluster easily
+================================================
+
+The inventory templates for 2 kinds of typical xCAT cluster is shipped. You can create your first xCAT cluster easily by making several modifications on the template. The templates can be found under ``/opt/xcat/share/xcat/inventory_templates`` on management node with ``xcat-inventory`` installed.
+
+Currently, the inventory templates includes:
+
+1. flat_cluster_template.yaml:  
+   
+   a flat baremetal cluster, including **openbmc controlled PowerLE servers**, **IPMI controlled Power servers(commented out)**, **X86_64 servers(commented out)**
+
+2. flat_kvm_cluster_template.yaml: a flat KVM based Virtual Machine cluster, including **PowerKVM based VM nodes**, **KVM based X86_64 VM nodes(commented out)**
+
+The steps to create your first xCAT cluster is:
+
+1. create a customized cluster inventory file "mycluster.yaml" based on ``flat_cluster_template.yaml`` ::
+   
+    cp /opt/xcat/share/xcat/inventory_templates/flat_cluster_template.yaml /git/cluster/mycluster.yaml
+
+2. custmize the cluster inventory file "mycluster.yaml" by modifying the attributs in the line under token ``#CHANGEME`` according to the setup of your phisical cluster. You can create new node definition by duplicating and modifying the node definition in the template.
+
+3. import the cluster inventory file ::
+   
+    xcat-inventory import -f /git/cluster/mycluster.yaml
+   
+Now you have your 1st xCAT cluster, you can start bring up the cluster by provision nodes.      
+
+

docs/source/advanced/xcat-inventory/index.rst

@@ -0,0 +1,21 @@
+xcat-inventory
+==============
+
+`xcat-inventory <https://github.com/xcat2/xcat-inventory>`_ is an inventory tool for the cluster managed by xCAT. Its features includes:
+
+* a object based view of the cluster inventory, which is flexible, extensible and well formatted
+
+* interfaces to export/import the cluster inventory data in yaml/json format, which can be then managed under source control
+
+* inventory templates for typical clusters, which help user to defines a cluster easily
+
+* ability to intergrate with Ansible(Comming Soon)
+
+
+This section presents 2 typical user case of ``xcat-inventory`` 
+
+.. toctree::
+   :maxdepth: 2
+
+   version_control_inventory.rst
+   define_create_cluster.rst 

docs/source/advanced/xcat-inventory/version_control_inventory.rst

@@ -0,0 +1,50 @@
+Manage the xCAT Cluster Definition under Source Control
+=======================================================
+
+The xCAT cluster inventory data, including global configuration and object definitions(node/osimage/passwd/policy/network/router), and the relationship of the objects, can be exported to a YAML/JSON file(**inventory file**) from xCAT Database, or be imported to xCAT Database from the inventory file. 
+
+By managing the inventory file under source control system, you can manage the xCAT cluster definition under source control. This section presents a typical step-by-step scenario on how to manage cluster inventory data under ``git``.
+
+
+1. create a directory ``/git/cluster`` under git directory to hold the cluster inventory ::
+
+    mkdir -p /git/cluster
+    cd /git/cluster
+    git init
+
+2. export the current cluster configuration to a inventory file "mycluster.yaml" under the git directory created above ::
+
+    xcat-inventory export --format=yaml >/git/cluster/mycluster.yaml
+
+3. check diff and commit the cluster inventory file(commit no: c95673) ::
+
+    cd /git/cluster
+    git diff
+    git add /git/cluster/mycluster.yaml
+    git commit /git/cluster/mycluster.yaml -m "$(date "+%Y_%m_%d_%H_%M_%S"): initial cluster inventory data; blah-blah"
+
+4. ordinary cluster maintenance and operation: replaced bad nodes, turn on xcatdebugmode...
+
+5. cluster setup is stable now, export and commit the cluster configuration(commit no: c95673) ::
+
+    xcat-inventory export --format=yaml >/git/cluster/mycluster.yaml
+    cd /git/cluster
+    git diff
+    git add xcat-inventory export --format=yaml >/git/cluster/mycluster.yaml
+    git commit /git/cluster/mycluster.yaml -m "$(date "+%Y_%m_%d_%H_%M_%S"): replaced bad nodes; turn on xcatdebugmode; blah-blah"
+
+6. ordinary cluster maintenance and operation, some issues are founded in current cluster, need to restore the current cluster configuration to commit no c95673 [1]_ ::
+   
+    cd /git/cluster
+    git checkout c95673
+    xcat-inventory import -f /git/cluster/mycluster.yaml
+
+*Notice:*
+
+1. The cluster inventory data exported by ``xcat-inventory`` does not include intermidiate data, transiate data and historical data in xCAT DataBase, such as node status, auditlog table
+
+2.  We suggest you backup your xCAT database by ``dumpxCATdb`` before your trial on this feature, although we have run sufficient test on this 
+
+.. [1] When you import the inventory data to xCAT Database in step 6, there are 2 modes: ``clean mode`` and ``update mode``. If you choose the ``clean mode`` by ``xcat-inventory import -c|--clean``, all the objects definitions that are not included in the inventory file will be removed; Otherwise, only the objects included in the inventory file will be updated or inserted. Please choose the proper mode according to your need
+
+