Chapter 12. Storage Domains

The storagedomains collection provides information about the storage domains in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="storagedomains" link obtained from the entry point URI (see Chapter 4, Entry Point).

The following table shows specific elements contained in a storage domain resource representation.

Element property icons

The icons used in the properties column of this table are described in Table 8.1, “Element property icons”

Element	Type	Description
`name`	string	A user-supplied human readable name for the storage domain. The `name` is unique across all storage domain resources.
`link rel="permissions"`	string	A link to the sub-collection for storage domain permissions. See Section 8.3.9, “ Permissions ”
`link rel="files"`	string	A link to the files sub-collection for this storage domains
`type`	enumerated	The storage domain type. A list of enumerated values are available in `capabilities`. See Section 7.1.7, “Storage Domain Types”.
`master`	boolean: true or false	`true` if this is the master storage domain of a data center
`host`	complex	A reference to the host on which this storage domain should be initialized. The only restriction on this host is that it should have access to the physical storage specified.
`storage`	complex	Describes the underlying storage of the storage domain. For more information see Section 12.1, “ Storage types ”.
`available`	integer	Space available in bytes
`used`	integer	Space used in bytes
`committed`	integer	Space committed in bytes
`storage_format`	enumerated	Describes the storage format version for the storage domain. A list of enumerated values are available in `capabilities`. See Section 7.1.19, “Storage Formats”

Example 12.1. An XML representation of a storage domain

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/rhevm-api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>data0</name>
    <link rel="permissions"
      href="/rhevm-api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/permissions"/>
    <link rel="files"
      href="/rhevm-api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/files"/>
    <type>data</type>
    <master>true</master>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
    <available>156766306304</available>
    <used>433791696896</used>
    <committed>617401548800</committed>
    <storage_format>v1</storage_format>
</storage_domain>

When creating a new storage domain, the name, type and storage elements are required. See Section 8.3.2, “ Creating a Resource ” for more information.

Example 12.2. Creating a storage domain

POST /rhevm-api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data1</name>
    <type>data</type>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
</storage_domain>

Only the name element may be updated post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.

Example 12.3. Updating a storage domain

PUT /rhevm-api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data1</name>
    <type>data</type>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
</storage_domain>

The API user attaches the storage domain to a data center after creation. See Section 9.1, “ Storage Domains Sub-Collection ” for instructions.

12.1. Storage types

The storage element contains a type element, which is an enumerated value found under the capabilities collection. See Section 7.1.6, “Storage Types”.

The storage element also contains additional elements specific to each storage type. The next few section examine these additional storage type elements.

12.1.1. NFS

The nfs specific elements in a storage description are:

Element	Type	Description	Properties
`address`	string	The host name or IP address of the NFS server
`path`	string	The path of NFS mountable directory on the server

12.1.2. iSCSI and FCP

The iscsi and fcp specific elements in a storage description are:

Element	Type	Description	Properties
`logical_unit id`	complex	A storage domain may be composed of multiple iSCSI or FCP logical units
`volume_group id`	complex	Alternatively, a storage domain may be based on a single LVM Volume Group which, in turn, may be composed of multiple iSCSI or FCP logical units

See Section 13.4, “ Storage Sub-Collection ” for more details.

In the case of iSCSI, if a logical_unit description also contains details of the iSCSI target containing the LUN in question, the target will be automatically logged into when the storage domain is created.

12.1.3. LOCAL

The local specific elements in a storage description are:

Element	Type	Description	Properties
`path`	string	The path of local storage domain on the host

A local storage domain requires a data center with storage_type set to LOCAL (see Chapter 9, Data Centers). This data center only contains a single host cluster, and the host cluster only contains a single host.