Migrating an existing IBM Storage Scale cluster management to the IBM Storage Scale native REST API

You can migrate an existing IBM Storage Scale cluster from mm-commands CLI-based management to the IBM Storage Scale native REST API.

The native REST API cluster management includes a modern administrative interfaces into the classic IBM Storage Scale infrastructure. You can enable the native REST API cluster management function in the following two ways:
  • Create a new cluster by using the native REST API through the scalectl CLI or REST API.
  • Migrate each of the existing classic IBM Storage Scale cluster by using the native REST API migration tool.
The native REST API migration tool automates the required tasks to migrate each node in a cluster. This process aggregates all the needed function for each node in the cluster to handle as a single-step operation. This method supports both CLI (scalectl cluster migrate) and REST API interfaces for migration.
Before running the migration, ensure the following requirements are met:
  • You can do the native REST API cluster migration as an online operation to a production cluster. However, as a best practice, run the migration within a maintenance window to allow for post-migration testing before full production use.
  • Install the native REST API RPM on each of the existing classic IBM Storage Scale cluster nodes before running the cluster migration. The native REST API RPM installation migrates the directory structures and files that are owned by the IBM Storage Scale software. These updates set a new specific native REST API user and group where needed. Specifically, the /var/mmfs directory is modified for native non-root scaleadmd server access.
  • Create a native REST API nodeId ahead of time for each existing classic IBM Storage Scale cluster node. This requirement is similar to requiring passwordless SSH keys to be configured with the classic IBM Storage Scale setup.
  • Make sure that the all nodes in the classic IBM Storage Scale cluster, regardless of its starting software version, have the same native REST API generally available (GA) level of code (RPMs) installed. Also, set the minReleaseLevel to the GA level that introduces the native REST API (5.2.3.0) or later.
  • Make sure that all existing IBM Storage Scale file systems in the classic IBM Storage Scale cluster are at the same GA level that introduces the native REST API (5.2.3.0) or later.
The native REST API migration function runs cluster-level and node-level checks before applying the required native REST API updates. It validates each known node in the classic IBM Storage Scale cluster and then migrates them. If all nodes pass the local node validation and migration steps, it applies cluster-level checks and activities to complete the migration. After the command completes successfully and all nodes are reported as successful, the cluster is migrated. You do not need to run the command again from any other nodes in the cluster.
Note: Restart the I/O daemons on each node in the cluster managed by the native REST API to ensure proper communication with the newly migrated administration daemons.

Use the optional --precheck option to validate each node and the cluster requirements before making any updates during the migration. It is recommended that you run the --precheck option before the full migration to identify potential issues early. If any issues arise during the --precheck, address them and rerun the --precheck until no further issues are identified. Then, run the full migration without supplying the --precheck option.

Since all nodes in a cluster are required to pass individual migration before the cluster will be committed for use with native REST API management, some node failures might occur. Error information is reported per node or at the cluster level if this occurs. Once the concerns are addressed on the failing nodes or at the cluster level, you can re-run the node migration.

The function migrates an existing classic IBM Storage Scale cluster and each of its nodes. A local IBM Storage Scale cluster node must exist on the node where the native REST API CLI is invoked for migration. There is no minimum or maximum number of IBM Storage Scale nodes for the existing cluster; all nodes will be migrated. The migration method uses the existing cluster configuration data to identify the list of classic IBM Storage Scale nodes that need to be migrated.
Remember: After the native REST API migration is complete, the new native REST API management function and the existing legacy mm-command management function will coexist consistently, unless otherwise specified.

For more information about the scalectl cluster migrate command, see scalectl cluster command.

For more information, see Coexistence with mm-commands CLI.