diff --git a/docs/source/advanced/index.rst b/docs/source/advanced/index.rst index 820e899d8..a951d2b77 100755 --- a/docs/source/advanced/index.rst +++ b/docs/source/advanced/index.rst @@ -25,3 +25,4 @@ Advanced Topics softlayer/index.rst sysclone/index.rst zones/index.rst + xcat-inventory/index.rst diff --git a/docs/source/advanced/xcat-inventory/define_create_cluster.rst b/docs/source/advanced/xcat-inventory/define_create_cluster.rst new file mode 100644 index 000000000..9a2dce023 --- /dev/null +++ b/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. + + diff --git a/docs/source/advanced/xcat-inventory/index.rst b/docs/source/advanced/xcat-inventory/index.rst new file mode 100644 index 000000000..5c7c4829b --- /dev/null +++ b/docs/source/advanced/xcat-inventory/index.rst @@ -0,0 +1,21 @@ +xcat-inventory +============== + +`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 diff --git a/docs/source/advanced/xcat-inventory/version_control_inventory.rst b/docs/source/advanced/xcat-inventory/version_control_inventory.rst new file mode 100644 index 000000000..adc311e01 --- /dev/null +++ b/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 + +