IBM Storage Scale native REST API

The IBM Storage Scale native REST API is a new feature that provides native REST APIs for secure and remote administration of IBM Storage Scale.

With this native REST API feature, you can manage the IBM Storage Scale cluster through a new daemon that runs on each IBM Storage Scale node. This feature replaces the administrative operations that were previously done with mm-commands. It also eliminates several limitations of the mm-command design, including the dependency on SSH, the requirement for privileged users, and the need to issue commands locally on the node where IBM Storage Scale runs.

The native REST API feature includes the following functions for IBM Storage Scale:
  • New control plane daemon (administration daemon)
  • New CLI (scalectl)
  • Remote administration
  • Role-based access control (RBAC)
  • Allow non-root administration
  • No dependency on SSH
New control plane daemon
A new administration daemon (scaleadmd) is deployed on the IBM Storage Scale nodes to use native REST API functions. The purpose of this daemon is to serve the native REST API interface, process the administrative requests from users, and handle all associated authentication and authorization controls for each request.
Important: When the administration daemon starts or restarts, there might be a brief delay before it can serve requests. As a result, the first CLI or REST API request might be rejected if the daemon startup routines are still completing. This behavior is similar to the delay that occurs before the I/O daemon can serve all requests.
The administration daemon restart can introduce this delay in the following situations:
  • Immediately after installation of the native REST API rpm (the administration daemon starts at the end of the installation process).
  • After nodes are added to the cluster (the remote node administration daemon internal services restart on the added nodes).
  • After you manual start or restart the administration daemon by using the systemd or a similar command
  • After node deletion (the administration daemon restarts on the node that is deleted).

A common error status that is returned is UNAVAILABLE, but other errors might also occur. If a request fails after the administration daemon restarts under these conditions, wait briefly (a few seconds) and retry the command. Repeat this process as needed.

Remote administration
With the native REST API feature, users can now issue admin operations from outside the cluster. The new scalectl CLI can communicate with the REST API through HTTPS, which enables commands to be run from outside the IBM Storage Scale node.
Role-based access control (RBAC)
The native REST API includes RBAC, allowing the security administrator to grant granular permissions for a user. A user can be allowed or denied to run operations at the resource level. For example, a user can be granted permission to operate on a specific file system or fileset only.
Allow non-root administration
Running the existing administrative mm-commands requires elevated privileges. The native REST API feature does not require the elevated privileges. RBAC policies can determine which users have the authority to run certain administrative operations. The user does not require the elevated privileges on the system to request administrative actions to take place.
No dependency on SSH
With the native REST API feature, operations that are done by the API use secure connections between administration daemons for remote code execution, eliminating the need for SSH.

High-level architecture

The administration daemon authenticates and authorizes user requests, either granting or denying permission based on the RBAC policy rules at the time of the request. Every request goes through the authentication and authorization middleware.

When you run the scalectl, it connects to the administration daemon through HTTPS (when the scalectl --url <host> <port> option is used) or through UNIX domain socket (UDS) by default.

The scalectl binary is a lightweight client of the administration daemon. It does minimal user input checks and processing. The administration daemon handles all request processing, authentication, and authorization.

Figure 1. High-level architecture
High-level architecture

The following figure depicts the default scalectl flow, which requires running the command on the API node itself:

Figure 2. Default scalectl flow
Default scalectl flow

The following figure depicts the scalectl flow with --url option (available to run from outside the cluster):

Figure 3. scalectl flow with --url option
scalectl flow with --url option

REST API overview

The administration daemon supports a REST API that allows applications to communicate with it directly, without the use of scalectl command-line interface. For more information about the native REST API endpoints, including request and response payloads, see the OpenAPI specification. You can access this OpenAPI specification at https://x.x.x.x:46443/openapi/, where x.x.x.x is the public IP address of the API server node. Ensure that the trailing slash (/) is included in the URL.