diff --git a/docs/source/references/coral/known_issues/genesis_base.rst b/docs/source/references/coral/known_issues/genesis_base.rst index 43181f732..80d616651 100644 --- a/docs/source/references/coral/known_issues/genesis_base.rst +++ b/docs/source/references/coral/known_issues/genesis_base.rst @@ -1,26 +1,22 @@ xCAT Genesis Base ================= -.. note:: Ensure that you rebuild ``xCAT-genesis-base`` with ``xCAT-genesis-builder`` version >= to *2.13.10* before updating xCAT to *2.13.10* or higher. +xCAT ships a ``xCAT-genesis-base`` package as part of xcat-deps. This is a light-weight diskless linux image based currently on Fedora34, that is used by xCAT to do hardware discovery. -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 ------------ - -.. note:: The genesis-base must be compiled on the Power9 hardware, running RHEL8. If the management node is not Power9 hardware, manually provision a RHEL8 compute node, build the genesis-base RPM, then install it on the management node. - -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 8. Building ``xCAT-genesis-base`` on a server running Red Hat Enterprise Linux 7 is no longer supported. +To build your own version of the ``xCAT-genesis-base`` on-site using a server running OS other than Fedora34, like Red Hat Enterprise Linux 8, follow the steps below. Building ``xCAT-genesis-base`` on a server running Red Hat Enterprise Linux 7 or earlier, is no longer supported. 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 8. +2. Install the ``xCAT-genesis-builder`` RPM on a node installed with desired OS (currently verified with Fedora34 and Red Hat Enterprise Linux 8). For more details: https://github.com/xcat2/xcat-core/tree/master/xCAT-genesis-builder#readme 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`` +To use the generated RPM from the step above for node discovery: + +1. Install the generated ``xCAT-genesis-base`` RPM on the xCAT Management node +2. Execute: ``mknb ppc64`` + +3. Follow :doc:`discover nodes ` diff --git a/xCAT-genesis-builder/README.md b/xCAT-genesis-builder/README.md index f5ab3e17d..58a52c1a7 100644 --- a/xCAT-genesis-builder/README.md +++ b/xCAT-genesis-builder/README.md @@ -1,29 +1,43 @@ # xCAT-genesis-builder -xCAT-genesis-builder is a utility for building base initrd images for deploying -diskless nodes in your cluster. This tool is required only if you have the -intention of deploying diskless nodes within your xCAT cluster. +`xCAT-genesis-builder` is a utility for building base initrd images for deploying diskless nodes in your cluster for discovery. This tool is required only if you have the intention of building your own version of `xCAT-genesis-base` RPM which is available in `xcat-dep` (latest version was built on Fedora34). # Background -For every architecture in your cluster, be it x86_64, ppc64, or arm, you need to have a default -initrd image for performing the initial boot and deploying the diskless operating system. +For every architecture in your cluster, be it x86_64, or ppc64, you need to have a default +`initrd` image for performing the initial boot and deploying the diskless operating system. -If for some reason, the versions included in the xCAT repository are insufficient, you can simply -run this utility on the target architecture which will build an RPM designed for the target -architecture. You can then transfer that RPM to your xCAT servers, install it, and then rebuild +If for some reason, the versions included in the xCAT `xcat-dep` repository are insufficient, you can simply +run this utility on the target architecture which will build a `xCAT-genesis-base` RPM designed for the target +architecture. You can then transfer that RPM to your xCAT Management Node, install it, and then rebuild the various netboot images. # Pre-requisites -The xCAT-genesis-builder package is designed to be run from a Red Hat compatible operating system +The `xCAT-genesis-builder` package is designed to be run from a Red Hat compatible operating system that support the Red Hat Package Manager (rpm) development tools. The script `buildrpm` will attempt to install some of these core packages if they are not already present. -## Instructions +## Instructions for buiding `xCAT-genesis-builder` RPM +Latest version 2.16.3 of `xCAT-genesis-builder` RPM available at https://www.xcat.org/files/xcat/xcat-dep/2.x_Linux/beta and was verified to install and run on Fedora34 and Red Hat 8. Earlier version 2.14.5 of `xCAT-genesis-builder` RPM available at https://www.xcat.org/files/xcat/xcat-dep/2.x_Linux/beta and was verified to install and run on Fedora26 and Red Hat 7. +If a new version of `xCAT-genesis-builder` RPM needs to be built: -First, you need to clone the xcat-core repo to the target architecture using the following -command: +1. Clone `xcat-core` git repository: + +```sh +git clone -b master https://github.com/xcat2/xcat-core.git +``` + +2. Build new `xCAT-genesis-builder` RPM: + +```sh +cd xcat-core +./makerpm-genesisbuilder +``` + +## Instructions for buiding `xCAT-genesis-base` RPM + +First, you need to clone the `xcat-core` repo to the target architecture using the following command: ```sh git clone -b master https://github.com/xcat2/xcat-core.git @@ -38,12 +52,11 @@ sed -i 's/%%REPLACE_CURRENT_VERSION%%/2.16.10/g' xCAT-genesis-base.spec buildrpm ``` -If this command is successful, runs error free, it will generate an RPM that you can transfer +If this command is successful, runs error free, it will generate a `xCAT-genesis-base` RPM that you can transfer to your xCAT server and install and then rebuild your netboot images prior to deploying the netboot images to your nodes. -The RPM will be placed into the following directory `/root/rpmbuild/RPMS/noarch` if the build -is successful. +The RPM will be placed into the following directory `/root/rpmbuild/RPMS/noarch` if the build is successful. When running the `buildrpm` the output should look similar to the following: @@ -132,31 +145,14 @@ To install the new RPM, issue the following command, using the 2.16.10 example f rpm -ivh xCAT-genesis-base*.rpm ``` -Now, assuming that the architecture that you have built the xCAT-genesis-base for was ppc64, +Now, assuming that the architecture that you have built the `xCAT-genesis-base` for was `ppc64`, you would then, on the xCAT server run the following command: ```sh mknb ppc64 ``` -At this point in time, you can re-generate your netboot images by running the following -commands: - -```sh -rmimage rhels8.4.0-ppc64le-netboot-image -genimage rhels8.4.0-ppc64le-netboot-image -packimage rhels8.4.0-ppc64le-netboot-image -``` - -Finally, attempt a re-imaging of a host using the following command: - -```sh -rinstall hostname -rcons hostname -``` - -If you rcons into the hosts, you can watch the actual initilization of the operating -system with the resulting netboot image. +At this point in time, you can discover nodes by following https://xcat-docs.readthedocs.io/en/stable/guides/admin-guides/manage_clusters/ppc64le/discovery/mtms/discovery.html # Open Source License