Merge pull request #3905 from whowutwut/coral_reference_doc

CORAL Reference Documentation, initial skeleton

docs/source/guides/install-guides/apt/index.rst

@@ -1,3 +1,5 @@
+.. _ubuntu_install_guide:
+
 Installation Guide for Ubuntu Server LTS
 ========================================
 

docs/source/guides/install-guides/yum/index.rst

@@ -1,3 +1,5 @@
+.. _rhel_install_guide:
+
 Installation Guide for Red Hat Enterprise Linux
 ===============================================
 

docs/source/guides/install-guides/zypper/index.rst

@@ -1,3 +1,5 @@
+.. _sles_install_guide:
+
 Installation Guide for SUSE Linux Enterprise Server
 ===================================================
 

docs/source/index.rst

@@ -32,6 +32,7 @@ Table of Contents
    guides/install-guides/index.rst
    guides/admin-guides/index.rst
    advanced/index.rst
+   references/index.rst
    troubleshooting/index.rst
    developers/index.rst
    help.rst

docs/source/references/coral/discovery/compute/index.rst

@@ -0,0 +1,9 @@
+Compute Nodes
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   discover.rst
+   validation.rst 
+

docs/source/references/coral/discovery/core_sw/discover.rst

@@ -0,0 +1,3 @@
+Discover Switches
+=================
+

docs/source/references/coral/discovery/core_sw/index.rst

@@ -0,0 +1,11 @@
+Core Switches
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   pre.rst
+   discover.rst
+   vlan.rst
+   known_issues.rst
+

docs/source/references/coral/discovery/core_sw/known_issues.rst

@@ -0,0 +1,2 @@
+Known Issues
+============

docs/source/references/coral/discovery/core_sw/pre.rst

@@ -0,0 +1,4 @@
+Prerequisites
+=============
+
+

docs/source/references/coral/discovery/core_sw/vlan.rst

@@ -0,0 +1,2 @@
+VLAN Configuration
+==================

docs/source/references/coral/discovery/edge_sw/discover.rst

@@ -0,0 +1,3 @@
+Discover Switches
+=================
+

docs/source/references/coral/discovery/edge_sw/index.rst

@@ -0,0 +1,10 @@
+Edge Switches
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   pre.rst
+   discover.rst
+   vlan.rst
+   known_issues.rst

docs/source/references/coral/discovery/edge_sw/known_issues.rst

@@ -0,0 +1,2 @@
+Known Issues
+============

docs/source/references/coral/discovery/edge_sw/pre.rst

@@ -0,0 +1,4 @@
+Prerequisites
+=============
+
+

docs/source/references/coral/discovery/edge_sw/vlan.rst

@@ -0,0 +1,2 @@
+VLAN Configuration
+==================

docs/source/references/coral/discovery/index.rst

@@ -0,0 +1,13 @@
+Discovery
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   core_sw/index.rst
+   mgmt_sw/index.rst
+   mid_sw/index.rst
+   servicenode/index.rst
+   edge_sw/index.rst
+   compute/index.rst 
+   

docs/source/references/coral/discovery/mgmt_sw/discover.rst

@@ -0,0 +1,3 @@
+Discover Switches
+=================
+

docs/source/references/coral/discovery/mgmt_sw/index.rst

@@ -0,0 +1,11 @@
+Management Switches
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   pre.rst
+   discover.rst
+   vlan.rst
+   known_issues.rst
+

docs/source/references/coral/discovery/mgmt_sw/known_issues.rst

@@ -0,0 +1,2 @@
+Known Issues
+============

docs/source/references/coral/discovery/mgmt_sw/pre.rst

@@ -0,0 +1,4 @@
+Prerequisites
+=============
+
+

docs/source/references/coral/discovery/mgmt_sw/vlan.rst

@@ -0,0 +1,2 @@
+VLAN Configuration
+==================

docs/source/references/coral/discovery/mid_sw/discover.rst

@@ -0,0 +1,3 @@
+Discover Switches
+=================
+

docs/source/references/coral/discovery/mid_sw/index.rst

@@ -0,0 +1,11 @@
+Mid Switches
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   pre.rst
+   discover.rst
+   vlan.rst
+   known_issues.rst
+

docs/source/references/coral/discovery/mid_sw/known_issues.rst

@@ -0,0 +1,2 @@
+Known Issues
+============

docs/source/references/coral/discovery/mid_sw/pre.rst

@@ -0,0 +1,4 @@
+Prerequisites
+=============
+
+

docs/source/references/coral/discovery/mid_sw/vlan.rst

@@ -0,0 +1,2 @@
+VLAN Configuration
+==================

docs/source/references/coral/discovery/servicenode/index.rst

@@ -0,0 +1,9 @@
+Service Nodes
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   discover.rst
+   validation.rst 
+

docs/source/references/coral/index.rst

@@ -0,0 +1,12 @@
+CORAL
+=====
+
+CORAL stands for Collaboration of Oak Ridge, Argonne, and Livermore and is solution that IBM is building for the Department of Energy to superseed its current cluster of Supercomputers. 
+
+
+.. toctree::
+   :maxdepth: 2
+
+   known_issues/index.rst 
+..   mn/index.rst
+..   discovery/index.rst

docs/source/references/coral/known_issues/genesis_base.rst

@@ -0,0 +1,22 @@
+xCAT Genesis Base
+=================
+
+xCAT ships a ``xCAT-genesis-base`` package as part of xcat-deps.  This is a light-weight diskless linux image based on Fedora (Fedora26, currently) that is used by xCAT to do hardware discovery.
+
+To support the Power9 hardware, changes are made to the kernel in the Red Hat Enterprise distribution that are not yet available in the Fedora kernels.  Without that support, running the scripts in xCAT discovery caused segmentation faults described in this issue: https://github.com/xcat2/xcat-core/issues/3870
+
+Work-around
+-----------
+
+xCAT cannot ship a kernel based on RHEL distribution, so the customer needs to build a version of the ``xCAT-genesis-base`` on-site using a server running Red Hat Enterprise Linux.
+
+1. Download the latest timestamp version of the ``xCAT-genesis-builder`` RPM provided here: http://xcat.org/files/xcat/xcat-dep/2.x_Linux/beta/
+   
+2. Install the ``xCAT-genesis-builder`` RPM on a node that is installed with the RHEL version being deployed. 
+
+3. Build the ``xCAT-genesis-base`` RPM: ::
+
+    /opt/xcat/share/xcat/netboot/genesis/builder/buildrpm
+
+4. Install this package on top of the xCAT install and execute: ``mknb ppc64``
+

docs/source/references/coral/known_issues/index.rst

@@ -0,0 +1,7 @@
+Known Issues
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   genesis_base.rst

docs/source/references/coral/mn/configure/index.rst

@@ -0,0 +1,5 @@
+Configure
+=========
+
+.. toctree::
+   :maxdepth: 2

docs/source/references/coral/mn/index.rst

@@ -0,0 +1,12 @@
+Management Node
+===============
+
+The Management Node should be installed with a RHEL Operating System.  The following guides describe the process of installation, configuration and validation of xCAT on the Management Node. 
+
+.. toctree::
+   :maxdepth: 2
+
+   install.rst
+   configure/index.rst 
+   validate/index.rst
+

docs/source/references/coral/mn/install.rst

@@ -0,0 +1,16 @@
+Install 
+=======
+
+
+Prerequisite
+------------
+
+Install the following RPMs Management Node.  They are used by various tools xCAT provides to assist with debugging/validation: ::
+
+   yum -y install tcpdump pciutils bzip2 bind-utils
+
+
+Install xCAT
+------------
+
+See :ref:`rhel_install_guide` for detailed xCAT installation instructions. 

docs/source/references/coral/mn/validate/index.rst

@@ -0,0 +1,6 @@
+Validate
+========
+
+.. toctree::
+   :maxdepth: 2
+

docs/source/references/index.rst

@@ -0,0 +1,11 @@
+Reference Implementation
+========================
+
+Reference documentation created for management of large clusters using xCAT. 
+
+.. toctree::
+   :maxdepth: 2
+
+   coral/index.rst
+   percs/index.rst
+   

docs/source/references/percs/index.rst

@@ -0,0 +1,5 @@
+PERCS
+=====
+
+See documentation here: https://sourceforge.net/p/xcat/wiki/XCAT_Power_775_Hardware_Management/
+