IBM Storage Ceph as a Service CLI

The IBM Storage Ceph as a Service plug-in extends the IBM Cloud command-line interface (CLI) to give you the ability to run commands that perform various operations for the service that includ but not limited to managing volumes, hosts, mappings, object credentials, and certificates.

Prerequisites

Before you can use the IBM Storage Ceph as a Service CLI plug-in, you must first install the IBM Cloud CLI, login to the CLI and then install the software-defined-storage CLI plug-in. For instruction on how to install the IBM Cloud CLI, see Getting started with the IBM Cloud CLI.

The plug-in is compatible with linux64, Windows®, and macOS® platforms that run on 64-bit processors.

Install the plug-in by using the plugin install command:

ibmcloud plugin install software-defined-storage

Once the plug-in is installed, you can verify the installation by running the software-defined-storage plugin which will display the help:

ibmcloud software-defined-storage --help

The output lists the USAGE instructions and the supported commands.

Updating the plug-in

Update the plug-in by using the plugin update command.

ibmcloud plugin update software-defined-storage

The latest plug-in version is downloaded and replaces your current plug-in service commands. If there are no new updates available, the message No updates are available is displayed.

You're notified on the command-line when updates to the IBM Cloud CLI and plug-ins are available. Be sure to keep your CLI up to date so that you can use the latest commands. You can view the current version of all installed plug-ins by running ibmcloud plugin list.

Command index

Each operation has an explanation of what it does, how to use it, and any optional or required parameters. Unless specified as optional, any listed parameters are mandatory.

The CLI plug-in doesn't yet support the full suite of features available in Software Defined Storage.

software-defined-storage

software-defined-storage - an OpenAPI definition for the IBM Storage Ceph as a Service CLI on the IBM Cloud platform.

ibmcloud software-defined-storage [command] [options]

Aliases of software-defined-storage: sds

Block storage

`ibmcloud sds volume-create`

Use this command to create a new volume with the specified capacity.

ibmcloud sds volume-create --capacity CAPACITY [--name NAME] [--source-snapshot (SOURCE-SNAPSHOT | @SOURCE-SNAPSHOT-FILE) | --source-snapshot-id SOURCE-SNAPSHOT-ID]

Aliases of volume-create: volc

Example: Creating a new volume

ibmcloud sds volume-create \
    --capacity 10 \
    --name my-volume \
    --url $sds_endpoint

Example: Restoring a volume from a snapshot

ibmcloud sds volume-create \
    --name test-volume-restored \
    --source-snapshot-id r134-eda57df4-41f2-48d8-812d-3d81955b6a1a \
    --capacity 10 \
    --url $sds_endpoint

When restoring a volume from a snapshot, the capacity must be equal to or greater than the original volume's capacity.

The $sds_endpoint is an environment variable that points to the endpoint provided to you when IBM Storage Ceph as a Service was configured. It is in the URL form. For example, https://sds-cephaas.<cephaas-instance-id>.software-defined-storage.appdomain.cloud:{port number}/v1. You can set the URL once and then not have to add it for every command. For guidance on how to set the URL, see Config commands.

Parameters to provide:

Capacity of the volume (in gigabytes).
- Flag: --capacity CAPACITY
Name of the volume.
- Flag: --name NAME
If you do not specify a name for the new volume, the system generates a name that is a hyphenated list of randomly selected words.
API Endpoint in the URL form.
- Flag: --url string
The source snapshot this volume was created from.
- Flag: --source-snapshot
Use this option if you are creating the volume from a snapshot.
Unique snapshot identifier of the resource.
- Flag: --source-snapshot-id
Use this option if you are creating the volume from a snapshot.

`ibmcloud sds volume`

Use this command to retrieve details for a single volume.

ibmcloud sds volume --volume-id VOLUME-ID --url string

Aliases of volume: vol

Example command:

ibmcloud sds volume \
    --volume-id r134-f24710c4-d5f4-4881-ab78-7bfXX6281f39 \
    --url $sds_endpoint

The $sds_endpoint is an environment variable that points to the endpoint provided to you when IBM Storage Ceph as a Servicewas configured. It is in the URL form. For example, https://sds-cephaas.<cephaas-instance-id>.software-defined-storage.appdomain.cloud:{port number}/v1. You can set the URL once and then not have to add it for every command. For guidance on how to set the URL, see Config commands.

Parameters to provide:

The volume identifier.
- Flag: --volume-id VOLUME-ID
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds volume-update`

Use this command along with the new information provided in volume patch parameter to update the volume capacity or the volume name.

You can change only one parameter value at a time in the command. More than one change in the same command is not supported.

ibmcloud sds volume-update --volume-id VOLUME-ID [--volume-patch VOLUME-PATCH | @VOLUME-PATCH-FILE] --url string

Aliases of volume-update: volu

Example command:

ibmcloud sds volume-update \
    --volume-id r134-f24710c4-d5f4-4881-ab78-7bfXX6281f39 \
    --capacity 38 \
    --name my-volume-updated \
    --url $sds_endpoint

Parameters to provide:

The volume identifier.
- Flag:--volume-id VOLUME-ID
Capacity of the volume (in gigabytes).
- Flag: --capacity CAPACITY
Name of the volume.
- Flag: --name NAME
[Optional] JSON object that contains the volume information such as a path to a JSON file.
- Flag: --volume-patch VOLUME-PATCH
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds volume-delete`

Use this command to delete a single volume.

ibmcloud sds volume-delete --volume-id VOLUME-ID --url string

Aliases of volume-delete: vold

Example command:

ibmcloud sds volume-delete \
    --volume-id r134-f24710c4-d5f4-4881-ab78-7bfXX6281f39 \
    --url $sds_endpoint

Parameters to provide:

The volume identifier.
- Flag:--volume-id VOLUME-ID
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds volumes`

Use this command to list all volumes.

ibmcloud sds volumes --help [--limit LIMIT] [--name NAME] --url string

Aliases of volumes: vols

Example command:

ibmcloud sds volumes --help \
    --limit 10 \
    --name my-volume \
    --url $sds_endpoint

Parameters to provide:

The number of resources to return on a page. The default value is 1. The maximum limit value is 1000.
- Flag: --limit int
Filter by name from the resource collection. You can specify 0 to 200 characters in string length.
- Flag: --name string

Hosts

`ibmcloud sds host-create`

Use this command to create a new host.

ibmcloud sds host-create --name NAME --nqn NQN [--volume-mappings VOLUME-MAPPINGS | @VOLUME-MAPPINGS-FILE] --url string --psk string

Aliases of host-create: hstc

Example command:

ibmcloud sds host-create \
    --name my-host \
    --nqn nqn.2014-06.org:9345 \
    --volume-mappings '[{"volume": {"id": "1a6b7274-678d-4dfb-8981-c71dd9d4daa5"}}]' \
    --url $sds_endpoint

Parameters to provide:

NVMe Qualified Name (NQN) of the host configured in the customer's environment. The maximum supported length is 223 bytes.
- Flag: --nqn NQN
Name for the new host. Ensure that the new name is unique.
- Flag: --name NAME
If you do not specify a name for the new host, the system generates a name that is a hyphenated list of randomly selected words.
PSK for the new host. Transport Layer Security pre-shared key ciphersuites (TLS-PSK) is a set of cryptographic protocols that provide secure communication based on pre-shared keys (PSKs).
- Flag: --psk string
The unique identifier of the volume to be mapped to this host. Must be in the form [{"volume": {"id": "1a6b7274-678d-4dfb-8981-c71dd9d4daa5"}}].
- Flag: --volume-mappings VOLUME-MAPPINGS
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds host`

Use this command to retrieve details for a single host.

ibmcloud sds host --host-id HOST-ID --url string

Example command:

ibmcloud sds host \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --url $sds_endpoint

Parameters to provide:

Host ID whose details you want to view
- Flag: --host-id HOST-ID
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds hosts`

Use this command to list all hosts.

ibmcloud sds hosts [--limit LIMIT] --url string

Aliases of hosts: hsts

Example command:

ibmcloud sds hosts \
    --limit 10 \
    --url $sds_endpoint

Parameters to provide:

Number of resources to return on a page.
- Flag: --limit LIMIT
Including this option filters the collection of resources by name.
- Flag: --name NAME
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds host-update`

Use this command to update a host.

ibmcloud sds host-update --host-id HOST-ID [--host-patch HOST-PATCH | @HOST-PATCH-FILE] --url string

Aliases of host-update: hstu

Example command:

ibmcloud sds host-update \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --name my-host
    --url $sds_endpoint

Parameters to provide:

Host ID whose details you want to update
- Flag: --host-id HOST-ID
[Optional] Specify the JSON Merge-Patch content for host_update.
- Flag: --host-patch HOST-PATCH
Name for the new host. Ensure that the new name is unique.
- Flag: --name NAME
If you do not specify a name for the new host, the system generates a name that is a hyphenated list of randomly-selected words.
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds host-mapping-create`

Use this command to map a volume to a host.

ibmcloud sds host-mapping-create --host-id HOST-ID [--volume (VOLUME | @VOLUME-FILE) | --volume-id VOLUME-ID]

Aliases of host-mapping-create: hstmc

Example command:

ibmcloud sds host-mapping-create \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --volume '{"id": "r134-f24710c4-d5f4-4881-ab78-7bfXX6281f39"}' \
    --url $sds_endpoint

ibmcloud sds host-mapping-create \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --volume-id r134-f24710c4-d5f4-4881-ab78-7bfXX6281f39 \
    --url $sds_endpoint

Parameters to provide:

Specify the host ID whose details you want to view
- Flag: --host-id HOST-ID
Specify the unique volume identifier.
- Flag: --volume-id VOLUME-ID
The unique identifier of the volume to be mapped to this host. Must be in the form [{"volume": {"id": "1a6b7274-678d-4dfb-8981-c71dd9d4daa5"}}].
- Flag: --volume VOLUME-ID
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds host-mappings`

Use this command to view all host-mappings for a host.

ibmcloud sds host-mappings --host-id HOST-ID

Aliases of host-mappings: hstms

Example command:

ibmcloud sds host-mappings \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --url $sds_endpoint

Parameters to provide:

Host ID whose details you want to view
- Flag: --host-id HOST-ID
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds host-mapping`

Use this command to view a single host mapping for a host.

ibmcloud sds host-mapping --host-id HOST-ID --volume-mapping-id VOLUME-MAPPING-ID

Aliases of host-mapping: hstm

Example command:

ibmcloud sds host-mapping \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --volume-mapping-id r134-f24710c4-d5f4-4881-ab78-7bfXX6281f39 \
    --url $sds_endpoint

Parameters to provide:

Host ID whose details you want to view
- Flag: --host-id HOST-ID
Unique volume-mapping identifier. This ID can be found by viewing either the associated volume or host you'd like to complete this operation against.
- Flag: --volume-mapping-id VOLUME-MAPPING_ID
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds host-delete`

Use this command to delete a host.

ibmcloud sds host-delete --host-id HOST-ID --url string

Aliases of host-delete: hstd

Example command:

ibmcloud sds host-delete \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --url $sds_endpoint

Parameters to provide:

Host ID whose details you want to view
- Flag: --host-id HOST-ID
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds host-mapping-delete`

Use this command to delete a single volume mapping from a host.

ibmcloud sds host-mapping-delete --host-id HOST-ID --volume-mapping-id VOLUME-MAPPING-ID

Aliases of host-mapping-delete: hstmd

Example command:

ibmcloud sds host-mapping-delete \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --volume-mapping-id r134-f24710c4-d5f4-4881-ab78-7bfXX6281f39 \
    --url $sds_endpoint

Parameters to provide:

Host ID whose details you want to view
- Flag: --host-id HOST-ID
Unique volume-mapping identifier. This ID can be found by viewing either the associated volume or host you'd like to complete this operation against.
- Flag: --volume-mapping-id VOLUME-MAPPING_ID
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds host-mapping-delete-all`

Use this command to delete all volume mappings associated with a host.

ibmcloud sds host-mapping-delete-all --host-id HOST-ID

Aliases of host-vol-delete-all: hstmda

Example command:

ibmcloud sds host-mapping-delete-all \
    --host-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --url $sds_endpoint

Parameters to provide:

Host ID whose details you want to view
- Flag: --host-id HOST-ID
API Endpoint in the URL form.
- Flag: --url string

Object storage

`ibmcloud sds cred-create`

Use this command to update credentials for a storage account or create them if they do not exist.

ibmcloud sds cred-create --access-key ACCESS-KEY --url string

Aliases of cred-create: crc

Example command:

ibmcloud sds cred-create \
    --access-key mytestkey
    --url $sds_endpoint

Parameters to provide:

Sets the access key for the service instance.
- Flag: --access-key ACCESS-KEY
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds cred-delete`

Use this command to delete a service credential.

ibmcloud sds cred-delete --access-key ACCESS-KEY --url string

Aliases of cred-delete: crd

Example command:

ibmcloud sds cred-delete \
    --access-key mytestkey
    --url $sds_endpoint

Parameters to provide:

Sets the access key for the service instance.
- Flag: --access-key ACCESS-KEY
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds creds`

Use this command to retrieve credentials for a specific storage account.

ibmcloud sds creds --url string

Aliases of creds: crl

Example command:

ibmcloud sds creds \
    --url $sds_endpoint

Parameters to provide:

API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds cert-types`

Use this command to retrieve the list of configured SSL certificate types.

ibmcloud sds cert-types --url string

Aliases of cert-types: crtt

Example command:

ibmcloud sds cert-types \
    --url $sds_endpoint

Parameters to provide:

API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds cert-create`

Use this command to create a new SSL certificate if one does not exist.

ibmcloud sds cert-create --cert CERT --body BODY --url string

Aliases of cert-create: crtc

Example command:

ibmcloud sds cert-create \
    --cert s3 \
    --body tempdir/test-file.txt \
    --url $sds_endpoint

Parameters to provide:

The request body that contains the TLS certificate. The CLI accepts certificate file in .pem format.
- Flag: --body BODY
The certificate type that is to be used in the request. Acceptable values include - s3.
- Flag: --cert CERT
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds cert-update`

Use this command to update an existing SSL certificate.

ibmcloud sds cert-update --cert CERT --body BODY --url string

Aliases of cert-update: crtu

Example command:

ibmcloud sds cert-update \
    --cert s3 \
    --body tempdir/test-file.pem \
    --url $sds_endpoint

Parameters to provide:

The request body that contains the TLS certificate. The CLI accepts certificate file in .pem format.
- Flag: --body BODY
The certificate type that is to be used in the request. Acceptable values include - s3.
- Flag: --cert CERT
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds cert`

Use this command to retrieve the SSL certificate expiration date and status.

ibmcloud sds cert --cert CERT --url string

Example command:

ibmcloud sds cert \
    --cert s3
    --url $sds_endpoint

Parameters to provide:

The certificate type that is to be used in the request. Acceptable values include - s3.
- Flag: --cert CERT
API Endpoint in the URL form.
- Flag: --url string

`ibmcloud sds cert-delete`

Use this command to delete an SSL certificate.

ibmcloud sds cert-delete --cert CERT --url string

Aliases of cert-delete: crtd

Example command:

ibmcloud sds cert-delete \
    --cert s3
    --url $sds_endpoint

Parameters to provide:

The certificate type that is to be used in the request. Acceptable values include - s3.
- Flag: --cert CERT
API Endpoint in the URL form.
- Flag: --url string

Snapshot commands

`ibmcloud sds volume-snapshot-create`

Use this command to create a snapshot of a volume.

ibmcloud sds volume-snapshot-create [--source-volume (SOURCE-VOLUME | @SOURCE-VOLUME-FILE) | --source-volume-id SOURCE-VOLUME-ID] [--name NAME]

Aliases of volume-snapshot-create: vsnapc

Example command:

ic sds volume-snapshot-create --source-volume-id r134-87a59338-a801-4090-a657-72867fc9ba44

Parameters to provide:

The block volume id where the new snapshot needs to be created.
- Flag: --source-volume-id
Unique name for the snapshot. Optional parameter.
- Flag: --name

`ibmcloud sds volume-snapshot`

Use this command to retrieve details for a single snapshot.

ibmcloud sds volume-snapshot --snap-id SNAP-ID

Aliases of volume-snapshot: vsnap

Example command:

ibmcloud sds volume-snapshot \
    --snap-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --url $sds_endpoint

Parameters to provide:

Snapshot identifier for which you want to retrieve the details.
- Flag: --snap-id

`ibmcloud sds volume-snapshots`

Use this command to list all snapshots.

ibmcloud sds volume-snapshots [--start START] [--limit LIMIT] [--name NAME] [--source-volume-id SOURCE-VOLUME-ID]

Aliases of volume-snapshots: vsnaps

Example command:

ibmcloud sds volume-snapshots \
    --start r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --limit 20 \
    --name my-host \
    --source-volume-id exampleString \
    --url $sds_endpoint

Parameters to provide:

The following parameters are optional.

Specifies the resource ID to start the page of results from. Useful for paginating through large collections.
- Flag: --start
Sets the maximum number of resources (snapshots) to return per page..
- Flag: --limit
Filters the results to only include snapshots with a name matching the provided string.
- Flag: --name
Filters the results to only include snapshots that belong to the specified source volume ID.
- Flag: source-volume-id
When listing volume snapshots, this option will automatically make multiple requests to retrieve and display all pages of results, so you see the entire collection without manually paging through results.
- Flag: all-pages

`ibmcloud sds volume-snapshot-update`

Use this command to update a snapshot.

ibmcloud sds volume-snapshot-update --snap-id SNAP-ID [--snapshot-patch SNAPSHOT-PATCH | @SNAPSHOT-PATCH-FILE]

Aliases of volume-snapshot-update: vsnapu

Example command:

ibmcloud sds volume-snapshot-update \
    --snap-id r134-69d5c3e2-8229-45f1-89c8-e4dXXb2e126e \
    --name snap-2-updated \
    --url $sds_endpoint

Parameters to provide:

(Required) The unique identifier of the snapshot you want to update.
- Flag: --snap-id
Specifies the snapshot name which needs to be updated.
- Flag: --name
Provide the JSON Merge-Patch content for updating the snapshot. This can be a JSON string directly in the command or a path to a JSON file containing the patch data. This allows you to update specific fields of the snapshot.
- Flag: --snapshot-patch

`ibmcloud sds volume-snapshot-delete`

Use this command to delete a single snapshot.

ibmcloud sds volume-snapshot-delete --snap-id SNAP-ID

Aliases of volume-snapshot-delete: vsnapd

Example command:

ibmcloud sds volume-snapshot-delete \
    --snap-id r134-76a4e08c-aa22-4fd3-9eb5-5cae0e78a285 \
    --url $sds_endpoint
Are you sure you want to delete? [y/n]> y
...
OK

Parameters to provide:

To force the command to execute
- Flag: -f, --force
Unique snapshot identifier that you want to delete.
- Flag: --snap-id

`ibmcloud sds volume-snapshots-delete`

Use this command to delete all snapshots for a volume.

ibmcloud sds volume-snapshots-delete [--source-volume-id SOURCE-VOLUME-ID]

Aliases of volume-snapshots-delete: vsnapsd

Example command:

ibmcloud sds volume-snapshots-delete \
    --source-volume-id r134-76a4e08c-aa22-4fd3-9eb5-5cae0e78a285 \
    --url $sds_endpoint
Are you sure you want to delete? [y/n]> y
...
OK

Parameters to provide:

To force the command to execute
- Flag: -f, --force
Filters the operation to only affect resources (such as snapshots) that have a source_volume-id property matching the specified identifier. Used to target all snapshots for a specific volume.
- Flag: --source-volume-id

Config commands

Config Command can be used for controlling or viewing persistent configuration of global options.

To control or view persistent configurations, run ibmcloud sds config command along with the global options to list, set, and unset the config values.

You can set the url variable such that you do not need to use the --url flag when using with the sds command.

ibmcloud sds config

Example for setting the url option.

pc@mac ~ % ibmcloud sds config set url http://sds-endpoint.satellite.cloud.ibm.com:33189/v1
OK

Example that shows how to use the command without the config set.

pc@mac ~ % ibmcloud sds volumes --url $endpoint

Example shows how to use the command with the url configured.

pc@mac ~ % ibmcloud sds volumes

Config command options

get - Retrieves the currently set configured value of an option.
list - Retrieves all the currently set configured values.
set - Set a config value for an option.
unset - Unset the config value of an option.

`ibmcloud sds config get`

Use this command to retrieve the currently set value for a specific option.

When Get option is used together with url option, the currently set value for the 'url' option is retrieved.

ibmcloud sds config get url

See example output.

pc@mac ~ % ibmcloud sds config get url
http://sds-endpoint.satellite.cloud.ibm.com:33189/v1

`ibmcloud sds config list`

Use this command to retrieve and view all of the currently set configured values.

ibmcloud sds config list

See example output.

pc@mac ~ % ibmcloud sds config list
url
http://sds-endpoint.satellite.cloud.ibm.com:33189/v1

`ibmcloud sds config set`

Use this command to configure new values for a specific option.

ibmcloud sds config set [url]

When set option is used together with url option, the value for the 'url' option is set.

See example with url option.

pc@mac ~ % ibmcloud sds config set url http://sds-endpoint.satellite.cloud.ibm.com:33189/v1

`ibmcloud sds config unset`

Use this command to reset the current configured values for a specific option.

ibmcloud sds config unset [url]

When unset option is used together with url option, the currently configured value for the 'url' option is reset.

Next steps

Run ibmcloud sds --help for more information about which commands you could run.