xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-05-21 19:22:05 +00:00
Code Issues Releases Wiki Activity

add doc about Set Up Web Service for REST API and Mixed Cluster

Browse Source
This commit is contained in:
penguhyang 2015-09-01 01:44:07 -04:00
parent 43ee273074
commit 9a7c05c0b6
6 changed files with 340 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/advanced/index.rst
View File

@ -5,7 +5,7 @@ Advanced Topics
:maxdepth: 2
restapi/index.rst
mixed_cluster.rst
mixed_cluster/index.rst
hierarchy_cluster.rst
hamn/index.rst
change_mn_ip.rst

87
docs/source/advanced/mixed_cluster.rst
View File

@ -1,87 +0,0 @@
Mixed Cluster Management
========================
ppc64 mgmt node
---------------
Provision x86_64 (bare metal)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to provision x86_64 ipmi-based machines from xCAT management node (ppc64), there are a few required xCAT dependency RPMs that must be installed:
* ``elilo-xcat``
* ``xnba-undi``
* ``syslinux-xcat``
Install these RPMs using the following command: ::
yum install elilo-xcat xnba-undi syslinux-xcat
On the ppc64 management node, obtain an x86_64 operating system ISO and add it into the xCAT osimage table by using the copycds command: ::
copycds /tmp/RHEL-6.6-20140926.0-Server-x86_64-dvd1.iso
Create a node definition for the x86_64 compute node, here is a sample: ::
lsdef -z c910f04x42
# <xCAT data object stanza file>
c910f04x42:
objtype=node
arch=x86_64
bmc=10.4.42.254
bmcpassword=PASSW0RD
bmcusername=USERID
chain=runcmd=bmcsetup,shell
cons=ipmi
groups=all
initrd=xcat/osimage/rhels6.6-x86_64-install-compute/initrd.img
installnic=mac
kcmdline=quiet repo=http://!myipfn!:80/install/rhels6.6/x86_64 ks=http://!myipfn!:80/install/autoinst/c910f04x42 ksdevice=34:40:b5:b9:c0:18 cmdline console=tty0 console=ttyS0,115200n8r
kernel=xcat/osimage/rhels6.6-x86_64-install-compute/vmlinuz
mac=34:40:b5:b9:c0:18
mgt=ipmi
netboot=xnba
nodetype=osi
os=rhels6.6
profile=compute
provmethod=rhels6.6-x86_64-install-compute
serialflow=hard
serialport=0
serialspeed=115200
Provision the node using the following commands: ::
# The following prepares the kickstart file in /install/autoinst
nodeset c910f04x42 osimage=rhels6.6-x86_64-install-compute
# Tells the BIOS to network boot on the next power on
rsetboot c910f04x42 net
# Reboots the node
rpower c910f04x42 boot
Provision x86_64 (diskless)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Troubleshooting
^^^^^^^^^^^^^^^
**Error:** The following Error message comes out when running nodeset: ::
Error: Unable to find pxelinux.0 at /opt/xcat/share/xcat/netboot/syslinux/pxelinux.0
**Resolution:**
The syslinux network booting files are missing.
Install the sylinux-xcat package provided in the xcat-deps repository: ``yum -y install syslinux-xcat``
x86_64 mgmt node
----------------
Provision ppc64 compute nodes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

8
docs/source/advanced/mixed_cluster/index.rst Normal file
View File

@ -0,0 +1,8 @@
Mixed Cluster
=============
.. toctree::
:maxdepth: 2
mixed_cluster_support_matrix.rst
mixed_cluster_mgt.rst

120
docs/source/advanced/mixed_cluster/mixed_cluster_mgt.rst Normal file
View File

@ -0,0 +1,120 @@
Mixed Cluster Management
========================
PPC64 MN deploying a System x86_64
----------------------------------
Provision x86_64 (bare metal)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to provision x86_64 ipmi-based machines from xCAT management node (ppc64), there are a few required xCAT dependency RPMs that must be installed:
* ``elilo-xcat``
* ``xnba-undi``
* ``syslinux-xcat``
Install these RPMs using the following command: ::
yum install elilo-xcat xnba-undi syslinux-xcat
On the ppc64 management node, obtain an x86_64 operating system ISO and add it into the xCAT osimage table by using the copycds command: ::
copycds /tmp/RHEL-6.6-20140926.0-Server-x86_64-dvd1.iso
Create a node definition for the x86_64 compute node, here is a sample: ::
lsdef -z c910f04x42
# <xCAT data object stanza file>
c910f04x42:
objtype=node
arch=x86_64
bmc=10.4.42.254
bmcpassword=PASSW0RD
bmcusername=USERID
chain=runcmd=bmcsetup,shell
cons=ipmi
groups=all
initrd=xcat/osimage/rhels6.6-x86_64-install-compute/initrd.img
installnic=mac
kcmdline=quiet repo=http://!myipfn!:80/install/rhels6.6/x86_64 ks=http://!myipfn!:80/install/autoinst/c910f04x42 ksdevice=34:40:b5:b9:c0:18 cmdline console=tty0 console=ttyS0,115200n8r
kernel=xcat/osimage/rhels6.6-x86_64-install-compute/vmlinuz
mac=34:40:b5:b9:c0:18
mgt=ipmi
netboot=xnba
nodetype=osi
os=rhels6.6
profile=compute
provmethod=rhels6.6-x86_64-install-compute
serialflow=hard
serialport=0
serialspeed=115200
Provision the node using the following commands: ::
# The following prepares the kickstart file in /install/autoinst
nodeset c910f04x42 osimage=rhels6.6-x86_64-install-compute
# Tells the BIOS to network boot on the next power on
rsetboot c910f04x42 net
# Reboots the node
rpower c910f04x42 boot
Provision x86_64 (diskless)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Troubleshooting
^^^^^^^^^^^^^^^
**Error:** The following Error message comes out when running nodeset: ::
Error: Unable to find pxelinux.0 at /opt/xcat/share/xcat/netboot/syslinux/pxelinux.0
**Resolution:**
The syslinux network booting files are missing.
Install the sylinux-xcat package provided in the xcat-deps repository: ``yum -y install syslinux-xcat``
Building a Stateless Image of a Different Architecture of OS
------------------------------------------------------------
**Note: The procedure below only works with xCAT 2.8.1 and later.**
The genimage command that builds a stateless image needs to be run on a node of the same architecture and OS major release level as the nodes that will ultimately be booted with this image. Usually the management node is running the same architecture and OS as the compute nodes, so you can run genimage directly on the management node.
However, there are times when you may want to provision a different version of the OS or even a different OS. In this case, you would need to run genimage on a node installed with the target OS you want to provision.
The following example is for creating a stateless image of the same OS but different architecture. The management node is "xcatmn". It is assumed that the osimage objects are already defined on the management node for the compute profile. Also any pkglist files have already been created and are configured correctly in the osimage definition.
On xCAT management node, select the osimage you want to create. Although it is optional, we recommend you make a copy of the osimage, changing its name to a simpler name. For example: ::
lsdef -t osimage -z rhels6.3-x86_64-netboot-compute | sed 's/^[^ ]\+:/mycomputeimage:/' | mkdef -z
Then dry-run the image to get the syntax for generating the image from another machine. ::
genimage --dryrun mycomputeimage
The result will look like this: ::
Generating image:
cd /opt/xcat/share/xcat/netboot/rh
./genimage -a x86_64 -o rhels6.3 -p compute --permission 755 --srcdir /install/rhels6.3/x86_64 --pkglist /opt/xcat/share/xcat/netboot/rh/compute.rhels6.x86_64.pkglist --otherpkgdir /install/post/otherpkgs/rhels6.3/x86_64 --postinstall /opt/xcat/share/xcat/netboot/rh/compute.rhels6.x86_64.postinstall --rootimgdir /install/netboot/rhels6.3/x86_64/compute mycomputeimage
Login to a target node matching the correct architecture for the image we want to create and mount the /install directory from the xCAT management node: ::
ssh <node>
mkdir /install
mount xcatmn:/install /install # the mount needs to have read-write permission
Copy the executable and files in the netboot directory from the xCAT Management node: ::
mkdir -p /opt/xcat/share/xcat/
cd /opt/xcat/share/xcat/
scp -r xcatmn:/opt/xcat/share/xcat/netboot .
If there is any osimage configuration file that is not in directory /opt/xcat/share/xcat or /install, copy the file from the management node to the same directory on this node. You could use lsdef -t osimage to check if there is any osimage configuration file that is not in directory /opt/xcat/share/xcat or /install.
Generate the image using the command printed out from the --dryrun. This is required since executing from a non xCAT management node will not be able to access the xCAT database to obtain the osimage information.
Now return to the management node and execute "packimage <osimage>" and continue provisioning your nodes.

67
docs/source/advanced/mixed_cluster/mixed_cluster_support_matrix.rst Normal file
View File

@ -0,0 +1,67 @@
Mixed Cluster Support Matrix
============================
Supported xCAT cross-distribution hardware control and OS installation environments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Notes:
* All the "yes" and "no" statements in the table are referring to hardware control and os provisioning, for the general purpose management like file sync and parallel commands, we do not see any obvious problem with any of the combination.
* The "yes" means should work but may or may not have been verified by the xCAT development/testing team.
* For diskless node, need another node that has the same os version and arch with the compute nodes to create diskless image, see TODO:Building_a_Stateless_Image_of_a_Different_Architecture_or_OS for more details
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| | RedHat | SLES | RedHat | SLES | Ubuntu | RedHat | SLES | Ubuntu | AIX |
| | ppc64 | ppc64 | x86_64 | x86_64 | x86_64 | ppc64le | ppc64le | ppc64el | CN |
| | CN | CN | CN | CN | CN | CN | CN | CN | |
+=========+=========+=========+=========+=========+=========+=========+=========+=========+======+
| RedHat | | | | | | | | | |
| ppc64 | yes | yes | yes | yes | yes | yes | yes | yes | no |
| MN/SN | | | :sup:`1`| :sup:`1`| :sup:`1`| | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| SLES | | | | | | | | | |
| ppc64 | yes | yes | yes | yes | yes | yes | yes | yes | no |
| MN/SN | | | :sup:`1`| :sup:`1`| :sup:`1`| | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| RedHat | | | | | | | | | |
| x86_64 | yes | yes | yes | yes | yes | yes | yes | yes | no |
| MN/SN | :sup:`4`| :sup:`4`| | | | | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| SLES | | | | | | | | | |
| x86_64 | yes | yes | yes | yes | yes | yes | yes | yes | no |
| MN/SN | :sup:`4`| :sup:`4`| | | | | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| Ubuntu | | | | | | | | | |
| x86_64 | yes | yes | yes | yes | yes | yes | yes | yes | no |
| MN/SN | :sup:`5`| :sup:`5`| | | | | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| RedHat | | | | | | | | | |
| ppc64le | yes | yes | yes | yes | yes | yes | yes | yes | no |
| MN/SN | :sup:`2`| :sup:`2`| | | | | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| SLES | | | | | | | | | |
| ppc64le | no | no | yes | yes | yes | yes | yes | yes | no |
| MN/SN | | | | | | | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| Ubuntu | | | | | | | | | |
| ppc64el | yes | yes | yes | yes | yes | yes | yes | yes | no |
| MN/SN | :sup:`3`| :sup:`3`| | | | | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
| AIX | no | no | no | no | no | no | no | no | yes |
| MN/SN | | | | | | | | | |
+---------+---------+---------+---------+---------+---------+---------+---------+---------+------+
Notes:
#. To manage x86_64 servers from ppc64/ppc64le nodes, will need to install the packages **xnba-undi elilo-xcat** and **syslinux-xcat** manually on the management node. And manually run command "cp /opt/xcat/share/xcat/netboot/syslinux/pxelinux.0 /tftpboot/"
#. If the compute nodes are DFM managed systems, will need xCAT 2.9.1 or high versions and the ppc64le DFM and ppc64le hardware server on the management node.
#. If the compute nodes are DFM managed systems, will need xCAT 2.10 or high versions and the ppc64le DFM and ppc64le hardware server on the management node.
#. If the compute nodes are DFM managed systems, will need the ppc64le DFM and ppc64le hardware server on the management node.
#. Does not support DFM managed compute nodes, hardware control does not work.

144
docs/source/advanced/restapi/set_up_ws.rst
View File

@ -1,2 +1,146 @@
Set Up Web Service for REST API
===============================
The following steps describe how to setup the WEB Service to use the REST API
Enable the HTTPS service for REST API
-------------------------------------
To improve the security between the REST API client and server, enabling the HTTPS service on the xCAT management is recommended. And the REST API client should use the 'https' to access web server instead of the 'http'.
* RHEL 6 (x86_64/ppc64) and RHEL 5 (x86_64) ::
yum install mod_ssl
service httpd restart
yum install perl-JSON
* RHEL 5 (ppc64) ::
Uninstall httpd.ppc64 and install httpd.ppc: ::
rpm -e --nodeps httpd.ppc64
rpm -i httpd.ppc mod_ssl.ppc
* SLES 10/11 (x86_64/ppc64) ::
a2enmod ssl
a2enflag SSL
/usr/bin/gensslcert
cp /etc/apache2/vhosts.d/vhost-ssl.template /etc/apache2/vhosts.d/vhost-ssl.conf
Insert line 'NameVirtualHost *:443' before the line '## SSL Virtual Host Context'
/etc/init.d/apache2 restart
zypper install perl-JSON
* Ubuntu ::
sudo a2enmod ssl
ln -s ../sites-available/default-ssl.conf /etc/apache2/sites-enabled/ssl.conf
sudo service apache2 restart
verify it is loaded: ::
sudo apache2ctl -t -D DUMP_MODULES | grep ssl
apt-get install libjson-perl
Enable the Certificate of HTTPs Server (Optional)
-------------------------------------------------
Enabling the certificate functionality of https server is useful for the Rest API client to authenticate the server.
Since a certificate for xcatd has already been generated when installing xCAT, it can be reused by the https server. To enable the server certificate authentication, the hostname of xCAT MN must be a fully qualified domain name (FQDN) that the REST API client must use when accessing the https server. If the hostname of the xCAT MN is not a FQDN, you need to change the hostname. Also, typically the hostname of the xCAT MN is initially set to correspond to the NIC that faces the cluster, which is usually an internal/private NIC. If you want to be able to use the REST API from a remote client, you should make the xCAT MN hostname correspond to the public NIC. To change the hostname, edit /etc/sysconfig/network (RHEL) or /etc/HOSTNAME (SLES) and run: ::
hostname <newFQDN>
Rerun xcatconfig to generate a new server certificate with the correct hostname. ::
xcatconfig -c
Notes: If you had previously generated a certificate for non-root userids to use xCAT, you must regenerate them using: /opt/xcat/share/xcat/scripts/setup-local-client.sh<username>
The steps to configure the certificate for https server: ::
export sslcfgfile=/etc/httpd/conf.d/ssl.conf # rhel
export sslcfgfile=/etc/apache2/vhosts.d/vhost-ssl.conf # sles
export sslcfgfile=/etc/apache2/sites-enabled/ssl.conf # ubuntu
sed -i 's/^\(\s*\)SSLCertificateFile.*$/\1SSLCertificateFile \/etc\/xcat\/cert\/server-cred.pem/' $sslcfgfile
sed -i 's/^\(\s*\)SSLCertificateKeyFile.*$/\1SSLCertificateKeyFile \/etc\/xcat\/cert\/server-cred.pem/' $sslcfgfile
service httpd restart # rhel
service apache2 restart # sles/ubuntu
The REST API client needs to download the xCAT certificate CA from the xCAT http server to authenticate the certificate of the server. ::
cd /root
wget http://<xcat MN>/install/postscripts/ca/ca-cert.pem
When accessing using the REST API, the certificate CA must be specified and the FQDN of the https server hostname must be used. For example: ::
curl -X GET --cacert /root/ca-cert.pem 'https://<FQDN of xCAT MN>/xcatws/nodes?userName=root& \
userPW=cluster'
Extend the Timeout of Web Server
--------------------------------
Some operations like 'create osimage' (copycds) need a long time (longer than 3 minutes sometimes) to complete. It would fail with a timeout (504 Gateway Time-out) if the timeout setting in the web server is not extended: ::
For rhel
sed -i 's/^Timeout.*/Timeout 600/' /etc/httpd/conf/httpd.conf
service htttd restart
For sles
echo "Timeout 600" >> /etc/apache2/httpd.conf
service apache2 restart
Set Up an Account for Web Service Access
----------------------------------------
The REST API calls need to provide a username and password. When this request is passed to xcatd, it will first verify that this user/pw is in the xCAT TODO:passwd table, and then xcatd will look in the TODO:policy table to see if that user is allowed to do the requested operation.
The account which key is **xcat** will be used for the REST API authentication. The username and password should be passed in with the attirbutes:
userName: Pass the username of the account
userPW: Pass the password of the account (xCAT 2.10)
password: Pass the password of the account (xCAT earlier than 2.10)
You can use the root userid for your API calls, but we recommend you create a new userid (for example wsuser) for the API calls and give it the specific privileges you want it to have.
Use root Account
~~~~~~~~~~~~~~~
Since the certificate and ssh keys for **root** account has been created during the install of xCAT. And the public ssh key has been uploaded to computer node so that xCAT MN can ssh to CN without password. Then the only thing needs to do is to add the password for the **root** in the passwd table. ::
tabch key=xcat,username=root passwd.password=<root-pw>
Use non-root Account
~~~~~~~~~~~~~~~~~~~
Create new user and setup the password and policy rules. ::
useradd wsuser
passwd wsuser # set the password
tabch key=xcat,username=wsuser passwd.password=cluster
mkdef -t policy 6 name=wsuser rule=allow
Note: in the tabch command above you can put the salted password (from /etc/shadow) in the xCAT passwd table instead of the clear text password, if you prefer.
Create the SSL certificate under that user's home directory so that user can be authenticated to xCAT. This is done by running the following command on the Management node as root: ::
/opt/xcat/share/xcat/scripts/setup-local-client.sh <username>
When running this command you'll see SSL certificates created. Enter "y" where prompted and take the defaults.
To enable the POST method of resources like nodeshell,nodecopy,updating,filesyncing for the non-root user, you need to enable the ssh communication between xCAT MN and CN without password. Log in as <username> and run following command: ::
xdsh <noderange> -K
Refer to the doc to TODO:[Granting_Users_xCAT_privileges] for details.
Run a test request to see if everything is working: ::
curl -X GET --cacert /root/ca-cert.pem \
'https://<xcat-mn-host>/xcatws/nodes?userName=<user>&userPW=<password>'
or if you did not set up the certificate: ::
curl -X GET -k 'https://<xcat-mn-host>/xcatws/nodes?userName=<user>&userPW=<password>'
You should see some output that includes your list of nodes.