Manage Existing Volumes

The manage existing volumes APIs provide the capability to specify the existing storage volumes that must be managed by the IBM® Cloud Infrastructure Center Management System. The capabilities include listing volumes that exist in the environment, managing individual volumes, and unmanaging volumes that are currently being managed.

Managing existing volumes options

Table 1. Options for managing existing volumes API

Method URI Description
GET /v3/{tenant_id}/os-hosts/{host_name}/all-volumes Lists existing volumes on storage provider.
POST /v3/{tenant_id}/os-hosts/{host_name}/onboard Manages existing volumes from a storage provider.
GET /v3/{tenant_id}/os-hosts/{host_name}/onboard/{task_id} Queries the asynchronous volume-managing task status.
POST /v3/{tenant_id}/os-hosts/{host_name}/unmanage Unmanages volumes that are currently managed by IBM Cloud Infrastructure Center.

Listing existing volumes

The operation lists all the volumes that exist on the storage provider independent of whether IBM Cloud Infrastructure Center is managing them. This API takes the name of the storage provider in the URI as input does not take any request body. The API returns the list of volumes on the storage provider in the response body. The list includes the names, status, whether the volumes are currently managed by IBM Cloud Infrastructure Center, and whether the volumes are supported to be managed by IBM Cloud Infrastructure Center.

Response codes

  • Normal response code: OK (200)

  • Error Response Codes: Not Found (404), Server Error (500)

Response body

Table 2. Parameters in the response for viewing existing volumes

Name Style Type Description
ID body string Internally generated identifier that is used to look up the task results of the manage action.
name body string Name of the storage provider.
size body integer Size of the volume in gigabytes.
managed body boolean Whether the volume is managed by IBM Cloud Infrastructure Center.
storage_pool body string Name of the storage pool that contains the volume.
mapped_wwpns body list of strings List of WWPNs that are mapped to the volume on the storage provider.
support body object Whether the volume is supported to be managed by IBM Cloud Infrastructure Center. The status key in the object can be either supported or not_supported and an additional reasons key is returned in the object for the not_supported volume.

Example:

    {"volumes": [

     {"id": "2c6da352-...",

      "name": "IPLNSS49",

      "status": "available",

      "size": 14,

      "managed": False,

      "storage_pool": "SVC-MEGA-III",

      "mapped_wwpns": ["C050...", "C051..."],

      "support": { "status": "supported" }

     },

     {"id": "1b87d2dc-...",

      "support": { "status": "not_supported", "reasons": [ "A reason",

        "Another reason" ] }...

Managing existing volumes

The operation asks IBM Cloud Infrastructure Center to start managing specific volumes that exist on the storage provider. This API takes the name of the storage provider in the URI and the list of UUIDs of the volumes in the body as input. The API then returns the URI of the task that can be used to look up results for the asynchronous operation in the response body.

Note: The special keyword all can be used instead of the UUID to specify that all volumes should be managed.

Response codes

  • Normal response code: OK (200)

  • Error Response Codes: Bad Request (400), Not Found (404), Server Error (500)

Request parameters

{"volumes": [ "2c6da352-...", "1b87d2dc-..."] }

Response body

Table 3. Parameters in the response for managing existing volumes

Name Style Type Description
ID body string Internally generated identifier that is used to look up the task results of the manage action.
links body list of strings URI that can be used to look up the task results.

Information about task URI can be used to retrieve progress and results of the onboarding.

Example:

{"task": {

  "id": "44fde213...",

  "links": [ { "href": "https://..../os-hosts/storage1/onboard/5555-222..." } ]

Query the asynchronous volume-managing task status

The operation queries the results of the volume manage tasks. This API takes URI link returned in the response of onboarding request. The API returns the information of the onboarding task, including the status, progress, volumes, the start and end time of this task.

Response codes

  • Normal response code: OK (200)

  • Error Response Codes: Not Found (404), Server Error (500)

Response body

Table 4. Parameters in the response for querying volume manage task status

Name Style Type Description
ID body integer Ths task ID of the manage action.
links body list of strings The URI of the task.
volumes body list of objects The list of volumes that are requested to be managed in the task. If the volume is already managed by the IBM Cloud Infrastructure Center before the task, the volume is not listed. For each volume in the list, the id, name and status are included. The status value can be imported or not_supported and an additional fault keyword is returned for the not_supported volume stating the reason.
status body string The status of the task, possible value is completed and waiting.
progress body integer The progress of the task.
started body string The start date of the task.
ended body string The end date of the task. The value is null for the not completed task.

Example 1: a sample response for a completed task

  {
      "task": {
          "id": 1,
          "links": [
              {
                  "href": "http://localhost:9000/v3/9bef770f0b32473584ec9251438a8ef5/os-hosts/v7k60/onboard/1"
              }
          ],
          "volumes": [
              {
                  "id": "ebdf754d-eea4-3969-9139-cf56032fc4f3",
                  "name": "test-tmp",
                  "status": "imported"
              }
          ],
          "status": "completed",
          "progress": 100,
          "started": "2021-11-19T04:04:32.000000",
          "ended": "2021-11-19T04:07:16.000000"
      }
  }

Example 2: a sample response before the task is complete

  {
      "task": {
          "id": 3,
          "links": [
              {
                  "href": "http://localhost:9000/v3/9bef770f0b32473584ec9251438a8ef5/os-hosts/v7k60/onboard/3"
              }
          ],
          "volumes": [],
          "status": "waiting",
          "progress": 0,
          "started": "2021-11-19T05:15:00.000000",
          "ended": null
      }
  }

Example 3: a sample response if a volume already managed by the IBM Cloud Infrastructure Center is requested to be managed again

  {
      "task": {
          "id": 2,
          "links": [
              {
                  "href": "http://localhost:9000/v3/9bef770f0b32473584ec9251438a8ef5/os-hosts/v7k60/onboard/2"
              }
          ],
          "volumes": [],
          "status": "completed",
          "progress": 100,
          "started": "2021-11-19T04:19:39.000000",
          "ended": "2021-11-19T04:20:52.000000"
      }
  }

Example 4: a sample response if a not_supported volume is requested to be managed by the IBM Cloud Infrastructure Center

  {
      "task": {
          "id": 3,
          "links": [
              {
                  "href": "http://localhost:9000/v3/9bef770f0b32473584ec9251438a8ef5/os-hosts/v7k60/onboard/3"
              }
          ],
          "volumes": [
              {
                  "id": "f4f9109a-186e-3c60-8262-e115e276c201",
                  "name": "volume-v7kdata-2-97e2e4e4-4e7e",
                  "status": "not_supported",
                  "fault": "This volume is not a candidate for management because it is already attached to a virtual machine and its status is \"in-use\"."
              }
          ],
          "status": "completed",
          "progress": 100,
          "started": "2021-11-19T05:15:00.000000",
          "ended": "2021-11-19T05:16:10.000000"
      }
  }

Unmanaging volumes

The operation asks IBM Cloud Infrastructure Center to stop managing specific volumes that exist on the storage provider. This API takes the name of the storage provider in the URI and the list of UUIDs of the volumes in the body as input and removes the volumes from the IBM Cloud Infrastructure Center database. The API does not return response body, if successful.

Note: The special keyword all can be used instead of the UUID to specify that all volumes should be unmanaged.

Response codes

  • Normal response code: No Content (204)

  • Error Response Codes: Bad Request (400), Not Found (404), Server Error (500)

Request parameters

{"volumes": [ "1234-789...", "3333-444..."] }