Preparing to use the installation toolkit

Before you use the installation toolkit, complete the following preparatory steps on all the nodes on which you plan to use the installation toolkit.

During the precheck phase of the installation toolkit, check the following items:

Passwordless SSH is set up.
Prerequisite kernel packages are installed.
Needed ports are open.
Supported OS and architectures are discovered on nodes.
Base OS repositories are set up.

Ensure that the following requirements are met.

Operating systems supported by the installation toolkit

For information about supported operating systems, see IBM Storage Scale FAQ in IBM® Documentation. Also, check with the operating system vendor to verify that a specific version of the operating system is supported by the vendor.

For information about how the installation toolkit can be used in a cluster that has nodes with mixed operating systems, see Mixed operating system support with the installation toolkit.

Required packages for the installation toolkit

The installation toolkit requires the following packages:

Python 3.10 or higher
Note:
- It is recommended that you install Python by using the OS package manager to avoid potential installation issues. For example, yum install python3.
- If you have Python 2.x and Python 3.x in your environment, ensure that Python 3.x is the default Python version. You can use the python --version command to check the default Python version. For example:
```
# python3 --version Python 3.10
```
net-tools
Ansible® 2.9.27

Supported Ansible version

The installation toolkit requires, at minimum, Ansible version 2.9.27. The installation toolkit also works in Ansible 2.10.x environments.

Important: The installation toolkit is not compatible with Ansible 2.19.x and later. Make sure that the ansible-core version is restricted to releases that are earlier than 2.19. The version 2.19 of ansible-core introduced changes in the Ansible core modules and dependencies that may cause compatibility issues with the installation toolkit.

The following Ansible installation considerations apply, depending on your operating system.

Operating system	Ansible installation considerations
Red Hat Enterprise Linux® 8.x, and 9.x	The installation toolkit installs the supported version of Ansible on the installer node when you run the ./spectrumscale setup -s `InstallNodeIP` command. Notes for the Ansible toolkit: For Red Hat Enterprise Linux, the Ansible toolkit automatically installs the latest version of Ansible (ansible-core) that is available in the Base OS repositories and their dependencies package. The Ansible toolkit uses the ansible.posix and community.general modules that are included in the Ansible collection packages.
SLES 15	You can use zypper install ansible to install Ansible, but ensure that the Ansible version is 2.9.1 or later.
Ubuntu 22.04, and 24.04	On Ubuntu nodes, Ansible 2.9.6 might be installed by default. You can install Ansible 2.9.x from the apt repository by using the apt install ansible-core command or the pip3 install ansible-core command. You can use the default Ansible version.

You can manually install Ansible 2.9.27 by using the following command.
```
# pip3 install ansible==2.9.27
```
You can manually install Ansible 2.10 by using the following command.
```
# pip3 install ansible==2.10
```

For more information, see Installing Ansible.

Note: If the pip3 command does not work with the installed Python version, use yum, zypper, or apt-get commands.

Optional: Ansible configuration settings to expedite Ansible tasks implementation

When the cluster to be deployed has more than 10 nodes, Ansible tasks implementation can be expedited by customizing the value for the forks parameter in the Ansible configuration file. The file is named ansible.cfg and can be saved in your home directory (~/.ansible.cfg).

The default value for forks is 5. You can change this value based on the number of nodes that the cluster is composed of. In the next example of an Ansible configuration file, the number of forks is set to 50.

[defaults]
callback_whitelist = timer, profile_tasks
forks = 50
gathering = smart
gather_subset = hardware
[ssh_connection]
pipelining = True
log_path = /var/log/ansible.log

For more information about tuning the parameters in an Ansible configuration file, see Ansible configuration settings in Ansible documentation.

Root access for the installation toolkit

The installation toolkit must be run as the root user. On Ubuntu, root login might be disabled by default. To use the installation toolkit on Ubuntu, you must enable the root login.

Call home information required for the installation toolkit

The installation toolkit requires call home data to work properly. You must have the customer name, the customer id, the customer email, and the customer country code available before installing and configuring call home with the installation toolkit.

Disable auto updates on Ubuntu nodes

On Ubuntu nodes, auto updates or unattended upgrades must be disabled, and kernel auto updates upon node reboot must also be disabled. This must be done to ensure that any updates that are not supported do not get installed. For example, a minor Ubuntu 22.04.x update that is not supported by IBM Storage Scale and installation toolkit might get installed if auto updates are not disabled.

Uninstall RPM Package Manager (RPM) on Ubuntu nodes

To use the installation toolkit on Ubuntu nodes, you must uninstall the RPM Package Manager (RPM) from these nodes.

Cluster configuration repository (CCR) is enabled

Before using the installation toolkit, ensure that CCR is enabled. For new installations, CCR is enabled by default. You can check that CCR is enabled in the cluster by using the following command.

# mmlscluster

GPFS cluster information
========================
  GPFS cluster name:         node1.example.com
  GPFS cluster id:           123412789099501234
  GPFS UID domain:           node1.example.com
  Remote shell command:      sudo wrapper in use
  Remote file copy command:  sudo wrapper in use
  Repository type:           CCR

Uninstall Upstream nfs-ganesha package: Before installing IBM Storage Scale 5.1.x on Ubuntu operating system, make sure that the upstream NFS Ganesha package is not installed or configured in the protocol nodes. If the NFS Ganesha package is installed or configured, then uninstall the package by using the apt purge nfs-ganesha command.

For information on prerequisites for protocols and performance monitoring, see Installation prerequisites.

Set up passwordless SSH as follows.
- From the admin node to the other nodes in the cluster.
- From protocol nodes to other nodes in the cluster.
- From every protocol node to rest of the protocol nodes in the cluster.
Note: Passwordless SSH must be set up by using the FQDN and the short name of the node.
The installation toolkit performs verification during the precheck phase to ensure that passwordless SSH is set up correctly. This verification includes:
- Check whether passwordless SSH is set up between all admin nodes and all the other nodes in the cluster. If this check fails, a fatal error occurs.
- Check whether passwordless SSH is set up between all protocol nodes and all the other nodes in the cluster. If this check fails, a warning is displayed.
- Check whether passwordless SSH is set up between all protocol nodes in the cluster. If this check fails, a fatal error occurs.
Set up the base OS repositories on your nodes so that package dependencies can be satisfied.
- These package managers must be set up depending on the operating system.
  - Red Hat Enterprise Linux: yum repository must be set up on all nodes in the cluster.
    Note: On Red Hat Enterprise Linux 8.x, two package repositories are available: BaseOS and Application Stream (AppStream). To streamline the installation and the upgrade of IBM Storage Scale packages on Red Hat Enterprise Linux 8.x nodes, it is recommended to configure the BaseOS and the Application Stream repositories.
  - SLES: zypper repository must be set up on all nodes in the cluster.
  - Ubuntu: apt repository must be set up on all nodes in the cluster.
    Note: Ensure that the apt-get update command is working without any errors.
- Configure repositories depending on whether you have internet connection or not. However, ensure that base operating system packages are available and EPEL repositories are disabled.
Ensure that the ports that are needed for installation are open.

Note: The installation toolkit checks if the firewall daemon is running and displays a warning if it is running. If the required ports are open, you can ignore the warning.
For information about the ports that need to be open, see Securing the IBM Storage Scale system using firewall.
Ensure that the required kernel packages are installed.

For more information, see Software requirements.

Note: You might have to force the installation of a specific version of these packages because a package of a version newer than the corresponding kernel might get picked up by default.
Ensure that networking is set up in one of the following ways.
- DNS is configured such that all host names, either short or long, are resolvable.
- All host names are resolvable in the /etc/hosts file. The host entries in the /etc/hosts file are required to be in the following order:
```
<IP address> <FQDN> <Short name>
```
  If the entries in the /etc/hosts file are not in this order, the installation toolkit displays a warning and continues with the rest of the procedure. The installation toolkit supports both FQDN and short name during installation, upgrade, or deployment. During fresh installations, the nodes are configured based on the entries in /etc/hosts. If /etc/hosts contains short names then the nodes are added with the short names, if the host names are reachable. For existing clusters, the installation toolkit configures the new node according to the configuration of the existing cluster. For example, if the existing cluster is configured with short names then the new node is added with the short name.
Obtain the IBM Storage Scale self-extracting installation package from IBM Fix Central.
Ensure that the LC_ALL and the LANGUAGE parameters are set to en_US.UTF-8.
You can use the locale command to check the current settings. If these parameters are set to a value different than en_US.UTF-8, use the following export statements before you issue the ./spectrumscale commands.
```
export LC_ALL=en_US.UTF-8
export LANGUAGE=en_US.UTF-8
```
You can also add these export statements in the bash_profile.
Perform pre-built/Custom Portability Layer rpm support through Installation toolkit.

Note: Prebuilt gplbin package installation is currently supported on RHEL and SLES on x86_64 architecture only.
1. Create a repository directory inside /usr/lpp/mmfs/6.0.0.0/.
```
mkdir directory_name
```
2. Copy the prebuilt generated gplbin package to the above repository directory. For example, scp gpfs.gplbin.rpm /usr/lpp/mmfs/6.0.0.0/directory_name.
3. Install createrepo utility if it does not already exist.
```
yum install createrepo
```
4. Create the repository metadata using createrepo command.
```
Createrepo .
```
5. Pass the defined rpm directory name to the install toolkit configuration file.
```
./spectrumscale config gpfs --gplbin_dir directory_name
```
  Note: Toolkit always validates the directory name and the repository data file exists inside the dedicated path /usr/lpp/mmfs/6.0.0.0/. It gives fatal error if the file and repository data does not exist.
6. Run the install/deploy process by executing the following commands:
  1. Define the rpm directory name in the configuration file.
```
./spectrumscale config gpfs --gplbin_dir directory_name
```
  2. List the defined directory from the configuration file.
```
./spectrumscale config gpfs --list
```
  3. Clear the defined directory from the configuration file.
```
./spectrumscale config clear gpfs --gplbin_dir
```