Chapter 9. Data Centers

9.1.1. Activate Action
9.1.2. Deactivate Action
9.1.3. Export Storage Domains

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

The following table shows specific elements contained in a data center 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 data center. The `name` is unique across all data center resources.
`description`	string	A free-form user-supplied human readable description of the data center
`link rel="storagedomains"`	string	A link to the sub-collection for storage domains attached to this data center
`link rel="permissions"`	string	A link to the sub-collection for data center permissions. See Section 8.3.9, “ Permissions ”
`storage_type`	enumerated	Describes the storage type in this datacenter. A list of enumerated values is available in `capabilities`. See Section 7.1.6, “Storage Types”
`storage_format`	enumerated	Describes the storage format version for the data center. A list of enumerated values are available in `capabilities`. See Section 7.1.19, “Storage Formats”
`version`	complex	The compatibility level of the data center. See Chapter 6, Compatibility Level Versions
`supported_versions`	complex	A list of possible `version` levels for the data center. See Chapter 6, Compatibility Level Versions
`status`	see below	The data center status

The status contains one of the following enumerative values: DOWN, ERROR, INITIALIZING, INSTALLING, INSTALL_FAILED, MAINTENANCE, NON_OPERATIONAL, NON_RESPONSIVE, PENDING_APPROVAL, PREPARING_FOR_MAINTENANCE, PROBLEMATIC, REBOOT, UNASSIGNED or UP.

Example 9.1. An XML representation of a data center

<data_centers>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
      href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988">
        <name>Default</name>
        <description>The default Data Center</description>
        <link rel="storagedomains"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/
          storagedomains"/>
        <link rel="permissions"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/permissions"/>
        <storage_type>nfs</storage_type>
        <storage_format>v1</storage_format>
        <version minor="0" major="3"/>
        <supported_versions>
            <version minor="0" major="3"/>
        </supported_versions>
        <status>UP</status>
    </data_center>
</data_centers>

When creating a new data center, the name, storage_type and version elements are required. See Section 8.3.2, “ Creating a Resource ” for more information.

Example 9.2. Creating a data center

POST /rhevm-api/datacenters HTTP/1.1
Accept: application/xml
Content-type: application/xml

<data_center>
    <name>NewDatacenter</name>
    <storage_type>nfs</storage_type>
    <version minor="0" major="3"/>
</data_centers>

The name and description elements are updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.

Example 9.3. Updating a data center

PUT /rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<data_center>
    <name>UpdatedName</name>
    <description>An updated description for the data center</description>
</data_centers>

9.1. Storage Domains Sub-Collection

Each data center contains a sub-collection for attached storages domain. A data center is only ready for use when at least one storage domain is attached, which an API user accomplishes when POSTing a representation of the desired storage domain to the data center's storage domains sub-collection.

An attached storage domain has a similar representation to a top-level storage domain, with the exception that it has a data center specific status and set of actions.

When attaching a storage domain, its ID or name must be supplied. An example of attaching a storage domain to a data center:

Example 9.4. Attach a storage domain to a data center

POST /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains HTTP/1.1
Content-type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>

HTTP/1.1 201 Created
Location: /datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed
Content-Type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
  fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>images0</name>
    <type>data</type>
    <status>INACTIVE</status>
    <master>true</master>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <actions>
        <link rel="activate"
          href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate"/>
        <link rel="deactivate"
          href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate"/>
    </actions>
</storage_domain>

There are two possible actions for attached storage domains: activate and deactivate.

9.1.1. Activate Action

An attached storage domain is activated on a data center before use. The activate action does not take any action specific parameters.

Example 9.5. Action to active a storage domain on a datacenter

POST /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate HTTP/1.1
Content-type: application/xml

9.1.2. Deactivate Action

An attached storage domain is deactivated on a data center before removal. The deactivate action does not take any action specific parameters.

Example 9.6. Action to deactive a storage domain on a datacenter

  POST /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate HTTP/1.1
  Content-type: application/xml

9.1.3. Export Storage Domains

Storage domains with type set to export contain vms and templates sub-collections which list the import candidate VMs and templates stored on that particular storage domain.

VMs and templates in these collections have a similar representation to their counterparts in the top-level VMs and templates collection, except they also contain a storage_domain reference and an import action (see Section 14.6.8, “ Import Action ”).

Example 9.7. Listing the virtual machines sub-collection of an export storage domain on a datacenter

GET /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms
Accept: application/xml

<vms>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
      href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
      fabe0451-701f-4235-8f7e-e20e458819ed/vms/082c794b-771f-452f-83c9-b2b5a19c0399">
        <name>vm1</name>
        ...
        <storage_domain id="082c794b-771f-452f-83c9-b2b5a19c0399"
          href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/>
        <actions>
            <link rel="import" href="/rhevm-api/datacenters/
              d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
              fabe0451-701f-4235-8f7e-e20e458819ed/vms/
              082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
        </actions>
    </vm>
</vms>