Working With DMS

Logging Into the DMS Service

The following command will connect to the DMS service running on base-url:

This will return you a JWT that you can use to access /api/v1/ on DMS service.

The result of this command will sign you into the DMS service and will update the ~/.local/dms/dms-cli.yaml file with a valid idToken to be consumed by the DMS API. example file:

Attaching/Detaching Lightbits Clusters

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

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

Attaching a Lightbits Cluster

Attaching a Lightbits cluster is a three-step procedure.

Step 1: Retrieve the DMS service credentials.

Output Example:

The information in this file will be needed in the next step.

Step 2: Update the credentials on a Lightbits cluster.

To authorize the DMS service to interact with the cluster you want to use, we now want to upload the publicKey/credentials to the Lightbits cluster:

1. Save the decoded DMS pubKey to a file, and upload them to the Lightbits server:

2. Run the lbcli create credential command on the Lightbits server. The pubKeyId, specified in the filename 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 (note that this requires system-admin privileges):

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

Step 3: Invoke the attach cluster operation.

To attach a Lightbits cluster, run the following command:

The output for this action will be a workflowId, describing the attach-cluster workflow state enabling monitoring of the attach operation. The result of this action, on the DMS service side, would be adding a cluster entry to the /etc/dms/clusters.yamlfile.

Listing a Lightbits Cluster

Run the following command to list the attached clusters:

Example of list cluster response:

Detaching a Lightbits Cluster

Detaching a cluster can be done by specifying its ID.

Run the following command to detach a cluster:

Thick-Clone Commands

Thick-Clone Volume

Use this to generate a thick-cloned volume in a different project.

This operation will copy all of the data from a snapshot to a newly created volume. src parameters identify the source snapshot to copy from, and dst parameters specify attributes of the new volume. dst name/project/cluster parameters are mandatory to uniquely identify parameters. All other parameters' size/replica-count can either be optionally specified or inherited from the source snapshot.

--unencrypted (optional, default false): Create the destination volume unencrypted. The value is passed straight through to the volume create exactly as lbcli create volume --unencrypted does. There is no inheritance from the source snapshot. Omit it (the default) to get an encrypted volume. It applies to clusters running encryption in hybrid mode; the destination cluster decides whether it is supported and may reject the request (e.g.; a cluster with unencryptedVolumesAllowed=false, or one without cluster-level encryption).

For example, keep a library of generic images as unencrypted golden snapshots, and clone each into a per-tenant volume left encrypted (the default, no flag):

--placement-affinity (optional): Steer where the destination volume lands, mirroring lbcli create volume. Pass key:value pairs joined by | (keys: fd, primaryfd), For example, primaryfd:server0 or fd:Server0|fd:rack1. If omitted, standard cluster placement is used.

PrimaryFD applies to 2–3 replica volumes; plain FD applies only to single-replica volumes with dynamic rebalance disabled. PrimaryFD governs the initial placement only. If dynamic rebalance is enabled and later triggers, it may move the volume without honoring the affinity.

Thick-Clone Snapshot

Use this to generate a thick-cloned snapshot in a different project.

This operation will copy all the data from a snapshot to a newly created snapshot. src parameters identify the source snapshot to copy from, and dst parameters specify attributes of the new snapshot. dst name/project/cluster parameters are mandatory to uniquely identify parameters. All other parameters' size/replica-count can either be optionally specified or inherited from the source snapshot.

--unencrypted (optional, default false): Create the destination snapshot's volume unencrypted, passed through to the underlying volume create (no inheritance from the source). Hybrid-mode encryption clusters only; omit for the encrypted default.

--placement-affinity (optional): Behaves the same as for thick-clone volume above (destination placement hint; PrimaryFD applies to 2–3 replica volumes; standard placement if omitted).

Inspecting a Workflow State

A DMS operation is called a workflow. DMS operations can be long-running, so to best track the state, status, and progress of both running and completed workflows, Lightbits' DMS exposes list and get workflow APIs.

List All Workflows

To fetch next items in list, you should add the next-page flag:

In case you want to get the next page, pass the token to the command:

Get a Workflow By ID

Cancel a Workflow By ID

Some workflows could have an extended execution time. The DMS service provides support for a canceling a specified workflow.