Chapter 11. 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.

Note

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

Table 11.1. Storage domain elements

Element Type Description Properties
link rel="permissions" relationship A link to the sub-collection for storage domain permissions. See Section 7.3.7, “ Permissions ”.
link rel="files" relationship A link to the files sub-collection for this storage domains.
link rel="vms" relationship A link to the vms sub-collection for a storage domain with type set to export.
link rel="templates" relationship A link to the templates sub-collection for a storage domain with type set to export.
type enumerated The storage domain type. A list of enumerated values are available in capabilities. See Section 6.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 11.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 6.1.20, “Storage Formats”.

Example 11.1.  An XML representation of a storage domain

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>data0</name>
    <link rel="permissions"
      href="/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/permissions"/>
    <link rel="files"
      href="/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>

Creation of a new storage domain requires the name, type, host and storage elements. Identify the host element with the id attribute or name element. See Section 7.2.4, “ Creating a Resource in a Collection ” for more information.

Example 11.2.  Creating a storage domain

POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data1</name>
    <type>data</type>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
</storage_domain>

Only the name element is updatable post-creation. See Section 7.3.2, “ Updating a Resource ” for more information.

Example 11.3.  Updating a storage domain

PUT /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data2</name>
    ...
</storage_domain>

Removal of a storage domain requires a DELETE request.

Example 11.4. Removing a storage domain

DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1

HTTP/1.1 204 No Content

The API user attaches the storage domain to a data center after creation. See Section 8.1.1, “Attaching a Storage Domain” for instructions.

Important

The API as documented in this chapter is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 6, “Backwards Compatibility Statement”.

11.1.  Storage types

The storage element contains a type element, which is an enumerated value found under the capabilities collection. See Section 6.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.

11.1.1.  NFS

The following table contains nfs specific elements in a storage description.

Table 11.2. NFS specific elements

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.

11.1.2.  iSCSI and FCP

The following table contains iscsi and fcp specific elements in a storage description.

Table 11.3. iSCSI and FCP specific elements

Element Type Description Properties
logical_unit id= complex The id of the logical unit. A storage domain also accepts multiple iSCSI or FCP logical units.

The logical_unit contains a set of sub-elements.

Table 11.4. Logical unit elements

Element Type Description Properties
address string The address of the server containing the storage device.
port integer The port number of the server.
target string The target IQN for the storage device.
username string A CHAP user name for logging into a target.
password string A CHAP password for logging into a target.
serial string The serial ID for the target.
vendor_id string The vendor name for the target.
product_id string The product code for the target.
lun_mapping integer The Logical Unit Number device mapping for the target.

In the case of iSCSI, if a logical_unit description also contains details of the iSCSI target with the LUN in question, the target performs an automatic login when the storage domain is created.

11.1.3.  LocalFS

The localfs specific elements in a storage description are:

Table 11.5. Localfs specific elements

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

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