Managing Storage Attachments

A storage attachment is an association between a storage volume and an instance. You can attach a storage volume to an instance either at launch time (by using a launch plan in an orchestration) or after an instance is running (by using UI, CLI and API). Each volume may only be attached to one instance at a time. To detach a storage volume from an instance, delete the associated storage attachment object.

Note:

The storage attachment must exist within the tenant name-space of the instance owner.

Topics:

Add Storage Attachment

This API enables you to add a storage attachment.

Method

POST

REST Resource

/storage/attachment/

URI

https://api_endpoint/storage/attachment/

Request Body Parameters

Parameter Description
index Index number for the volume. The allowed range is 1 to 10. The index determines the device name by which this volume is exposed to the instance (for example, /dev/sdal1). The index to device mapping is as follows:

  • 1—/dev/xvdb

  • 2—/dev/xvdc, and so on
instance_name Name of the instance to which the volume should be attached
storage_volume_name Name of the storage volume to which the instance should be attached

Example URI

https://api.oc.example.com/storage/attachment/

Example Request Body

{
  "instance_name": "/mytenant/public/example-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc",
  "storage_volume_name": "/mytenant/public/example-sdi-sdivm-el1-6-storagevolume-data",
  "index": 3
}

Example Response Body

{
        "index": 3, 
        "account": null, 
        "storage_volume_name": "/mytenant/public/scae09-sdi-sdivm-el1-6-storagevolume-data", 
        "hypervisor": null, 
        "uri": "https://api.oc.example.com/storage/attachment/mytenant/public/example-sdi-sdivm-el1-8-instance/\
    1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64", 
        "instance_name": "/mytenant/public/example-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc", 
        "state": "shut_down", 
        "readonly": false, 
        "name": "/mytenant/public/example-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64"
}

Delete Storage Attachment

This API enables you to delete a specific storage attachment.

If the instance is in the running state, then you must first unmount the storage volume in the instance. Log in to the instance, identify the storage volume, and unmount the storage volume using the command umount path-to-disk-mount-point.

Method

DELETE

REST Resource

/storage/attachment/name

URI

https://api_endpoint/storage/attachment/name

URI Parameter

Parameter Description
name System generated name of the storage attachment to be deleted.

Example URI

https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f6

Retrieve Storage Attachment Details

You can retrieve storage attachment details by using the REST API.

Topics:

Discover Storage Attachments

This API enables you to discover storage attachments in a specific container.

Note:

The discover API calls display the names of the objects in the specified container, not the details about the objects. To list the names of the objects, you must set the Accept header to application/oracle-compute-v3+directory+json. For all other purposes, you must set the Accept header to application/oracle-compute-v3+json.

Method

GET

REST Resource

/storage/attachment/container/

URI

https://api_endpoint/storage/attachment/container/

URI Parameter

Parameter Description
container Hierarchical namespace containing the storage attachments

Example URI

https://api.oc.example.com/storage/attachment/mytenant/public

Example Response Body

{"/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/"},

Get Storage Attachment

This API enables you to retrieve information for a specific storage attachment.

Method

GET

REST Resource

/storage/attachment/name

URI

https://api_endpoint/storage/attachment/name

URI Parameter

Parameter Description
name System generated name of the storage attachment

Example URI

https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64

Example Response Body

{
        "index": 3, 
        "account": null, 
        "storage_volume_name": "/mytenant/public/scae09-sdi-sdivm-el1-6-storagevolume-data", 
        "hypervisor": null, 
        "uri": "https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64", 
        "instance_name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc", 
        "state": "shut_down", 
        "readonly": false, 
        "name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64"
}

List Storage Attachments

This API enables you to retrieve details of storage attachments in a specific container.

Method

GET

REST Resource

/storage/attachment/container/

URI

https://api_endpoint/storage/attachment/container?name=nameValue&instance_name=instance_nameValue&storage_volume_name=storage_volume_name&state=stateValue

URI Parameter

Parameter Description
container Hierarchical namespace containing the storage attachments
name (Optional) Name of the attachment, automatically generated by the server
instance_name (Optional) Name of the instance to which the volume is attached
storage_volume_name (Optional) Name of the storage volume to which the instance is attached
state (Optional) Attachment state. The following values are supported:

  • attaching

    The storage attachment is in the process of attaching to the instance.

  • attached

    The storage attachment is attached to the instance.

  • detaching

    The storage attachment is in the process of detaching to the instance.

  • unavailable

    The storage attachment is unavailable.

  • error

    The storage attachment is in error state.

Example URI

https://api.oc.example.com/storage/attachment/mytenant/public

Example Response Body

{
        "index": 3, 
        "account": null, 
        "storage_volume_name": "/mytenant/public/scae09-sdi-sdivm-el1-6-storagevolume-data",
        "hypervisor": null, "uri": "https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64", 
        "instance_name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc", 
        "state": "shut_down", 
        "readonly": false, 
        "name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64"
}, 

{
        "index": 1, 
        "account": null,
        "storage_volume_name": "/mytenant/public/scae09-sdi-sdivm-el1-5-storagevolume-ops", 
        "hypervisor": null, "uri": "https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8d772e9e-182f-4df8-a9d9-ce58ebe68442", 
        "instance_name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc", 
        "state": "shut_down", 
        "readonly": false, 
        "name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8d772e9e-182f-4df8-a9d9-ce58ebe68442"
}