View block volumes

View details about a block storage volume or summary information about all volumes for the deployment.

View list of all volumes in the UI

To view the list of all the volumes, in the IBM Cloud console External link icon, go to IBM Storage Ceph as a Service > Block Storage > Volumes.

By default, all IBM Storage Ceph as a Service volumes for the chosen deployment are displayed. In the list of all Volumes, you see the following information.

Details about all volumes
Field Description
Name Click the name of the volume to see individual volume details.
Status Status of the volume
Provisioned size Size of the volume you specified, in GBs.
Mapped hosts Shows the count of number of hosts mapped to the volume.

By default, 10 volumes are shown in the list of all volumes. Change this default by clicking the Page Control down arrow and increase the list to 25, 50 or 100 volumes. Use the Page Control arrows after the list to go to the following page or return to the current page.

Row actions menu on the Volume list page provides you with options to manage the volume information.

Table 2 describes the Actions menu options.

Row actions menu options for volumes.
Action Description
View volume details Click to open the detailed view of the Volume.
Rename volume Click to change the volume name.
Map to host Click to map the volume to one or more hosts.
Expand volume Allows you to increase the capacity of the volume.
Delete Delete the volume.

View details of a single volume

To view details of a single volume, go to the list of all volumes and click the volume name.

The volumes details page shows the details of the chosen volume and all its mapped hosts. Table 3 describes this information.

Volume details
Field Description
Volume details
Name Name of the volume you specified when you created the volume. Click the pencil icon to edit the volume name. The volume name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-), and must begin with a lowercase letter. Volume names must be unique for the deployment.
volume ID System-generated volume ID.
Provisioned size Size of the volume you specified, in GBs.
Created date System-generated date when the volume was created.
Deployment Name of the instance in the region.
IOPS Current IOPS value for a predefined IOPS tier which is based on the default profile.
Throughput The performance a disk can deliver, measured in Gigabytes/second (Gbps). Based on your volume profile, throughput is calculated as the amount of IOPS * 16 K block size.
Mapped hosts Displays a list of all hosts present in the system. You can also create a new host mapping or create a new host to map using the Map host + option. See Creating a host.

The Actions menu on the volume details page shows the actions that you can take. Table 4 shows Actions menu options from the volume details page.

Actions menu options from the volume details page.
Action Description
Expand volume Allows you to increase the capacity of the volume.
Delete Delete the volume.

View single volume details from the CLI

Run the following command to show volume details for a specific volume ID along with the endpoint url.

ibmcloud software-defined-storage volume --volume-id VOLUME-ID --url string

See the following example.

$ ibmcloud sds volume --url $sds_endpoint --volume-id r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd
...

Volume_ID     r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd
Volume_Name   magma-agreeably-groovy-hardwood
Status        available
Bandwidth     19
Capacity_GB   1
Created       2025-02-27T09:49:02.000Z
IOPS          150
Hosts
              Gateways
                                  IP_Address   xxx.xx.x.xx
                                  Port         8009

                                  IP_Address   xxx.xx.x.xx
                                  Port         8009

                                  IP_Address   xxx.xx.x.xx
                                  Port         8009

                                  IP_Address   xxx.xx.x.xx
                                  Port         8009

              Host_ID             r134-886f1457-7bee-4893-b3b8-0a75b0076a85
              Host_NQN            nqn.2014-08.org.nvmexpress:uuid:29181642-300c-a1e2-497a-172017002145
              Host_Name           groovey-hardwood
              Namespace_ID        1
              Namespace_UUID      ff5e44ffdeb15e1d9d134f6f0a2dc4bf
              Status              mapped
              Subsystem_NQN       nqn.2014-08.com.ibm:nvmeof-f538f202-2907-4061-8463-6a40dbe6b69f
              Volume_Mapping_ID   r134-b561e8f8-cea4-4934-8527-726a5ccc309f

The $sds_endpoint is an environment variable that points to the endpoint provided to you when IBM CephaaS 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.

You can also use the alias sds as an alternative to software-defined-storage and vol as an alternative to volume for the CLI actions.

For more information about available command options, run ibmcloud sds volume --help.

View list of all volumes from the CLI

Run this command to list summary information about all volumes:

ibmcloud software-defined-storage volumes [--limit LIMIT] [--name NAME] --url string

Specify the endpoint url since it is used to filter the list of volumes that belong to the specified deployment.

The following example shows all volumes for the endpoint url specified in your availability zone.

ibmcloud software-defined-storage volumes --url $sds_endpoint

Volume_ID                                   Volume_Name                       Status      Capacity_GB   Hosts
r134-b05d91af-6393-4652-aada-13fd4fdbd065   seventy-banked-pry-punt           available   150           -
r134-601e431b-22ab-47a1-b0c1-411049b432a0   grain-snooper-blank-gyration      available   15            -
r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd   magma-agreeably-groovy-hardwood   available   1             [r134-886f1457-7bee-4893-b3b8-0a75b0076a85]

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.

You can also use the alias sds as an alternative to software-defined-storage and vols as an alternative to volumes for the CLI actions.

For more information about available command options, run ibmcloud sds volumes --help.

View list of all volumes with the API

Make a GET /volumes request to retrieve and view a list of all volumes within your deployment.

See the following example.

curl -X GET $sds_endpoint/volumes\
	-H 'accept: application/json'\
	-H "Authorization: Bearer $IAM_TOKEN"\
	-H 'IBM-API-Version: 2025-02-01'

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.

A successful response looks like the following example. This example shows the first volume mapped to a host.

{
  "volumes": [
    {
      "id": "r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd",
      "name": "magma-agreeably-groovy-hardwood",
      "capacity": 1,
      "iops": 150,
      "status": "available",
      "created_at": "2025-02-27T09:49:02Z",
      "status_reasons": [],
      "bandwidth": 19,
      "resource_type": "volume",
      "href": "$sds_endpoint/volumes/r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd",
      "volume_mappings": [
        {
          "id": "r134-b561e8f8-cea4-4934-8527-726a5ccc309f",
          "status": "mapped",
          "href": "$sds_endpoint/hosts/r134-886f1457-7bee-4893-b3b8-0a75b0076a85/volume_mappings/r134-b561e8f8-cea4-4934-8527-726a5ccc309f",
          "volume": {
            "name": "magma-agreeably-groovy-hardwood",
            "id": "r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd"
          },
          "host": {
            "name": "groovey-hardwood",
            "nqn": "nqn.2014-08.org.nvmexpress:uuid:29181642-300c-a1e2-497a-172017002145",
            "id": "r134-886f1457-7bee-4893-b3b8-0a75b0076a85"
          },
          "subsystem_nqn": "nqn.2014-08.com.ibm:nvmeof-f538f202-2907-4061-8463-6a40dbe6b69f",
          "namespace": {
            "id": 1,
            "uuid": "ff5e44ffdeb15e1d9d134f6f0a2dc4bf"
          },
          "gateways": [
            {
              "ip_address": "xxx.xx.x.xx",
              "port": 8009
            },
            {
              "ip_address": "xxx.xx.x.xx",
              "port": 8009
            },
            {
              "ip_address": "xxx.xx.x.xx",
              "port": 8009
            },
            {
              "ip_address": "xxx.xx.x.xx",
              "port": 8009
            }
          ]
        }
      ]
    }
  ],
  "first": {
    "href": "$sds_endpoint/volumes?limit=1000"
  },
  "limit": 1000,
  "total_count": 1
}

Viewing volume details with the API

Make a GET /volumes/{id} request to see details of a volume. See the following example.

curl -X GET $sds_endpoint/volumes/r134-04f0e415-3c70-43a8-a98d-a0160e50cc88\
  -H 'accept: application/json'\
  -H "Authorization: Bearer $IAM_TOKEN"\
  -H 'IBM-API-Version: 2025-02-01'

The $sds_endpoint is an environment variable that points to the endpoint provided to you when IBM CephaaS 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.

A successful response provides details of the volume, including capacity and IOPS, the volume status, and the host to which the volume is mapped.

{
  "id": "r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd",
  "name": "magma-agreeably-groovy-hardwood",
  "capacity": 1,
  "iops": 150,
  "status": "available",
  "created_at": "2025-02-27T09:49:02Z",
  "status_reasons": [],
  "bandwidth": 19,
  "resource_type": "volume",
  "href": "$sds_endpoint/volumes/r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd",
  "volume_mappings": [
    {
      "id": "r134-b561e8f8-cea4-4934-8527-726a5ccc309f",
      "status": "mapped",
      "href": "$sds_endpoint/hosts/r134-886f1457-7bee-4893-b3b8-0a75b0076a85/volume_mappings/r134-b561e8f8-cea4-4934-8527-726a5ccc309f",
      "volume": {
        "name": "magma-agreeably-groovy-hardwood",
        "id": "r134-1dee2264-a3c2-415d-bc86-dd05ad4f06dd"
      },
      "host": {
        "name": "groovey-hardwood",
        "nqn": "nqn.2014-08.org.nvmexpress:uuid:29181642-300c-a1e2-497a-172017002145",
        "id": "r134-886f1457-7bee-4893-b3b8-0a75b0076a85"
      },
      "subsystem_nqn": "nqn.2014-08.com.ibm:nvmeof-f538f202-2907-4061-8463-6a40dbe6b69f",
      "namespace": {
        "id": 1,
        "uuid": "ff5e44ffdeb15e1d9d134f6f0a2dc4bf"
      },
      "gateways": [
        {
          "ip_address": "xxx.xx.x.xx",
          "port": 8009
        },
        {
          "ip_address": "xxx.xx.x.xx",
          "port": 8009
        },
        {
          "ip_address": "xxx.xx.x.xx",
          "port": 8009
        },
        {
          "ip_address": "xxx.xx.x.xx",
          "port": 8009
        }
      ]
    }
  ]
}

View volume details using Terraform

To view Terraform objects

terraform state list

To target a volume resource, run the following command:

terraform state show ibm_sds_volume.<ibm_sds_volume_name>

Next steps

Create more volumes, map volume to hosts or manage your existing volumes.