Working With ICM

Logging Into the ICM Service

Running commands using the icmcli tool requires login. Use the following command to log in (connect) to the ICM service running on baseUrl:

The result of this command will sign you into the ICM service and update the ~/.local/intelligent-cluster-management/icm-cli.yaml file with a valid idToken to be consumed by the ICM API.

Example file:

Attaching/Detaching Lightbits Clusters

Once the ICM service is running and an ICM client is configured to consume it, you can attach the Lightbits clusters to the ICM service.

The ICM service can manage multiple Lightbits clusters. A cluster attach operation will update the ICM service with a Lightbits cluster's information.

Attaching a Lightbits Cluster

Attaching a Lightbits cluster involves the following:

1. Retrieve the ICM service credentials.

2. Update these credentials on the Lightbits cluster.

3. Invoke the attach cluster operation.

Step 1: Retrieving the ICM Service Credentials

The information from this step will be needed in the next step for updating the credentials on the Lightbits cluster.

Run the following command on the ICM host:

Output example:

The generated .pem file is used in the next step.

Step 2: Updating the Credentials on a Lightbits Cluster

To authorize the ICM service to interact with the Lightbits cluster you want to use, upload the publicKey/credentials to the Lightbits cluster.

1. Upload the ICM-decoded public key to the Lightbits server. In the previous step, there was an indication for the pubkey file path to upload ~/.local/intelligent-cluster-management/<pubKeyId>.pem. Here, you will upload this file to the Lightbits server:

   scp ~/.local/intelligent-cluster-management/<pubKeyId>.pem <user>@<LightbitsServer>:/tmp/

2. Run lbcli create credential command on the Lightbits server:

   The pubKeyId, specified in the file name from the previous step, will be used here as the id of the credential. SSH to the Lightbits server that the credentials were uploaded to, and execute the following (requires system-admin privileges):

   lbcli create credential --project-name=system --type=rsa256pubkey --id=<pubKeyId> /tmp/<pubKeyId>.pem

Once the credentials have been added, the ICM service that generated the credentials is authorized to operate with this Lightbits cluster.

Invoking the Attach Cluster Operation

It is possible to attach a Lightbits cluster using any of the Cluster's API endpoints.

To attach a Lightbits cluster, run the following command:

The output for this action is a workflowId, describing the attach-cluster workflow state and enabling you to monitor the attach operation.

On the ICM service side, the attached cluster is recorded in the ICM etcd registry (under /icm/clusters/<uuid>), so the attachment survives service restarts. The registry has no host port; inspect it with the etcd tooling on the ICM host if needed.

Listing Lightbits Clusters

Run the following command to list the attached Lightbits clusters:

Example of list cluster response:

Detaching a Cluster

Detaching a cluster can be done by specifying its id. Run the following command to detach a Lightbits cluster:

Preparing the Project

ICM manages a single Lightbits project (set at install time via ICM_PROJECT_NAME, default default). Before creating volumes or snapshots, that project must exist on every attached cluster. Create it on each cluster with lbcli:

Volume Commands

Create a volume (ICM places it across the attached clusters):

Common optional flags: --compression=<true|false>, --sector-size=<512|4096>, --source-snapshot-name/--source-snapshot-uuid (create from a snapshot), --placement-affinity=<key:value|key:value>.

List, get, update, and delete volumes:

Snapshots Commands

Create a snapshot from a volume, and then list/get/delete:

Thick Clone Commands (Data Mobility)

A thick clone block-copies a source snapshot into a new, independent volume or snapshot on any attached cluster - including a different cluster from the source. The command returns a workflowId immediately; the copy runs as a workflow that you can monitor.

Prerequisite: storage-network reachability:

Thick clone copies data by attaching the source and destination volumes to the ICM host over NVMe/TCP (handled by the bundled discovery-client). The ICM host must therefore have a route to every attached cluster's data (NVMe) network; each cluster's nvmeEndpoint addresses both the discovery service (port 8009) and the I/O controllers (port 4420). Management-network connectivity alone is not sufficient. If you add or configure the ICM host's data-network interface after deploying ICM, restart the discovery-client so that it re-establishes its cluster connections.

A clone that fails at the detectVolumeAttached stage with no local block device for volume ... means that the volume's block device did not appear on the ICM host within the retry window. Possible causes include the device taking longer than the retry window to attach and an unavailable primary node on the source cluster; on a standalone deploy the most common cause is that the ICM host cannot reach a cluster's NVMe network, or that discovery-client started before the data interface existed.

Clone a snapshot into a new volume on a destination cluster:

Clone a snapshot into a new snapshot (add --description):

Any of --dst-proj-name, --size, --replica-count, --sector-size, --compression, --unencrypted, --dst-qos-policy-name, and --placement-affinity may be set on the destination; unset optional flags inherit from the source snapshot.

Inspecting the Workflow State

ICM attach and detach operations are called a workflow. To track the state, status, and progress of both running and completed workflows, Lightbits' ICM exposes list and get workflow APIs.

Listing All Workflows

By default the page-size is set to 100, a list workflows command will hence fetch the latest 100 workflows. To fetch a more limited list or a larger number of items in a list (the max is limited to 250), you should add the page-size flag.

Getting a Workflow by ID

Cancelling a Workflow by ID

A running thick-clone workflow can be cancelled by its workflow ID. Cancellation runs the workflow's compensation/cleanup; it applies to thick-clone workflows only.