ViPR 2.1 - Add Hosts and Clusters with the ViPR REST API

Table of Contents

Overview

Learn how to add Linux, Windows, HP-UX, and other types of hosts using the ViPR REST API. Also includes examples of adding host initiators and adding the host to a ViPR cluster. Lists some of the important REST APIs used to manage hosts and clusters.

Hosts are computers that use software including WIndows, Linus, and VMware for their operating system. In ViPR, hosts are tenant resources like volumes, file systems, and buckets. Unlike those resources, however, hosts are imported and discovered rather than provisioned by ViPR.

Hosts must be imported into ViPR by a Tenant Administrator before storage may be exported and attached to them. By default, hosts are not assigned to a project which means only the Tenant Administrator may see them and export/attach storage to them. If further delegation is required, the Tenant Administrator may assign a host to a project. Anyone who has privileges to manage resources in that project may then see and export/attach storage to that host.

Hosts are not explicitly associated with virtual arrays. The host-to-virtual array association is implied based on network connectivity.

This article is part of a series

Hosts can be added to ViPR at anytime. If, however, you are setting up the ViPR Controller virtual data center for the first time, before you continue to provision storage, complete the following steps.

  1. Authenticate with the ViPR REST API
  2. Add physical assets to ViPR:
  3. Create ViPR virtual assets:
    1. Create and configure a virtual array
    2. Create virtual pools:

Back to Top

Add and discover a LINUX host

To manage a LINUX host in ViPR, use POST /tenants/{Tenant_URN}/hosts to add the host to ViPR and discover the host, and its initiator ports.

Before you begin

The following steps describe how to add a LINUX host to ViPR using the REST API. To use the ViPR UI to add a LINUX host to ViPR see the Add LINUX Hosts and Clusters to ViPR article.

Procedure

  1. Get the URN of your tenant.
    GET https://<ViPR_VIP>:4443/tenant
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
  2. Use the tenant URN to create a host. The POST /tenants/{Tenant_URN}/hosts method also initiates discovery of the host and its initiator ports.
    Request
    POST https://<ViPR_VIP>:4443/tenants/{Tenant_URN}/hosts
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    
    <host_create>  
      <type>Linux</type>
      <host_name>lglw7141.lss.emc.com</host_name>
      <name>lglw7141</name>
      <port_number>22</port_number>
      <user_name>root</user_name>
      <password>Password1</password>
      <use_ssl>No</use_ssl>
    </host_create>
    
    Response
    HTTP 202 Accepted
    Content-Type: application/xml
    <task>
      <associated_resources/>
      <description>DISCOVER_HOST</description>
      <op_id>90827e3a-ce0f-42b3-9499-d43986dba44b</op_id>
      <resource>
        <id>urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:vdc1</id>
        <link href="/compute/hosts/urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:vdc1" rel="self"/>
        <name>lglw7141</name>
      </resource>
      <link rel="self" href="/compute/hosts/urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:vdc1/tasks/90827e3a-ce0f-42b3-9499-d43986dba44b"/>
      <state>ready</state>
    </task>
    
    You will not be able to fully manage the host until you discover it.
  3. Check the user interface to see if the host has completed discovery, or check the host resource. It should contain the information shown in the following example.
    Request
    GET https://<ViPR_VIP>:4443/compute/hosts/urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    Response
    HTTP 200 OK
    Content-Type: application/xml
    <host>
      <creation_time>1386618442154</creation_time>
      <global>false</global>
      <id>urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:vdc1</id>
      <inactive>false</inactive>
      <internal>false</internal>
      <link href="/compute/hosts/urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:vdc1" rel="self"/>
      <name>lglw7141</name>
      <remote>false</remote>
      <tags/>
      <vdc>
           <id>urn:storageos:VirtualDataCenter:248f48d0-6e37-4357-ab42-0ee2174e783b:vdc1</id>
           <link rel="self" href="/vdc/urn:storageos:VirtualDataCenter:248f48d0-6e37-4357-ab42-0ee2174e783b:vdc1" />
      </vdc>
      <native_guid/>
      <compatibility_status>COMPATIBLE</compatibility_status>
      <job_discovery_status>COMPLETE</job_discovery_status>
      <last_discovery_run_time>1386619685871</last_discovery_run_time>
      <last_discovery_status_message/>
      <last_metering_run_time>0</last_metering_run_time>
      <job_metering_status>CREATED</job_metering_status>
      <next_discovery_run_time>0</next_discovery_run_time>
      <next_metering_run_time>0</next_metering_run_time>
      <registration_status>REGISTERED</registration_status>
      <success_discovery_time>1410195850197</success_discovery_time>
      <success_metering_time>0</success_metering_time>
      <tenant>
        <id>urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:global</id>
        <link href="/tenants/urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:global" rel="self"/>
      </tenant>
      <discoverable>true</discoverable>
      <host_name>lglw7141.lss.emc.com</host_name>
      <os_version>RHEL 5.9.0.2</os_version>
      <port_number>22</port_number>
      <type>Linux</type>
      <use_ssl>false</use_ssl>
      <user_name>root</user_name>
    </host>
    
    
Back to Top

Add and discover a Windows host

To manage a Windows host in ViPR, use POST /tenants/{Tenant_URN}/hosts to add the host to ViPR and discover the host, and its initiator ports

Before you begin

The following steps describe how to add a Windows host to ViPR using the REST API. To use the ViPR UI to add a Windows host to ViPR see the Add Windows Hosts and Clusters to ViPR article.

Procedure

  1. Get the URN of your tenant.
    GET https://<ViPR_VIP>:4443/tenant
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
  2. Use the tenant URN to create a host. The POST /tenants/{Tenant_URN}/hosts method also initiates discovery of the host and its initiator ports.
    Request
    POST https://<ViPR_VIP>:4443/tenants/{Tenant_URN}/hosts
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    
    <host_create>
         <type>Windows</type>
         <host_name>lgloa219</host_name>
         <name>host219</name>
         <port_number>5985</port_number>
         <user_name>host219_admin</user_name>
         <password>Password1</password>
         <use_ssl>false</use_ssl>
    </host_create>
    
    Response
    HTTP 202 Accepted
    Content-Type: application/xml
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <task>
        <associated_resources/>
        <description>DISCOVER_HOST</description>
        <op_id>1e5f3757-8eef-41cc-92bc-132d1ea4b70f</op_id>
        <resource>
            <id>urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1</id>
            <link rel="self" href="/compute/hosts/urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1"/>
            <name>host219</name>
        </resource>
        <link rel="self" href="/compute/hosts/urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1/tasks/1e5f3757-8eef-41cc-92bc-132d1ea4b70f"/>
        <state>pending</state>
    </task>
    
    You will not be able to fully manage the host until discovery of the host, and its initiator ports has completed.
  3. Check the user interface to see if the host has completed discovery, or check the host resource. The host should contain the status shown in the following example.
    Request
    GET https://<ViPR_VIP>:4443/compute/hosts/urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    Response
    HTTP 200 OK
    Content-Type: application/xml
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <host>
        <creation_time>1399747448456</creation_time>
        <global>false</global>
        <id>urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1</id>
        <inactive>false</inactive>
        <internal>false</internal>
        <link rel="self" href="/compute/hosts/urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1"/>
        <name>host219</name>
        <remote>false</remote>
        <tags/>
        <vdc>
            <id>urn:storageos:VirtualDataCenter:440b70de-fd36-4361-a455-b6ca65fb8228:vdc1</id>
            <link rel="self" href="/vdc/urn:storageos:VirtualDataCenter:440b70de-fd36-4361-a455-b6ca65fb8228:vdc1"/>
        </vdc>
        <native_guid></native_guid>
        <compatibility_status>COMPATIBLE</compatibility_status>
        <job_discovery_status>COMPLETE</job_discovery_status>
        <last_discovery_run_time>1399747450309</last_discovery_run_time>
        <last_discovery_status_message/>
        <last_metering_run_time>0</last_metering_run_time>
        <job_metering_status>CREATED</job_metering_status>
        <next_discovery_run_time>1399751048561</next_discovery_run_time>
        <next_metering_run_time>0</next_metering_run_time>
        <registration_status>REGISTERED</registration_status>
        <success_discovery_time>0</success_discovery_time>
        <success_metering_time>0</success_metering_time>
        <tenant>
            <id>urn:storageos:TenantOrg:6c7dde31-ec48-4028-8672-5e74f5754656:global</id>
            <link rel="self" href="/tenants/urn:storageos:TenantOrg:6c7dde31-ec48-4028-8672-5e74f5754656:global"/>
        </tenant>
        <discoverable>true</discoverable>
        <host_name>lgloa219</host_name>
        <port_number>5985</port_number>
        <type>Windows</type>
        <use_ssl>false</use_ssl>
        <user_name>host219_admin</user_name>
    </host>
    
Back to Top

Add a host other than Windows or Linux

Adding a host other than Windows or Linux requires you to manually register the initiators with the host after adding the host. You can also manually assign host initiators and interfaces to any host you are registering with ViPR .

Before you begin

  • Authenticate with the ViPR REST API as a Tenant Administrator.
  • Setting type equal to HPUX in the payload of POST /vdc/tenant/{Tenant_URN}/hosts sets the Volume Set Addressing (VSA) flag, which is required for exporting EMC VMAX volumes to HP-UX hosts.
  • The EMC ViPR REST API Reference provides a description and complete list of parameters for the REST API methods used in this section.
  • You need the following information:
    • The name of the host being registered.
    • The fully qualified domain name of IP address of the host.
    • The node address of an initiator
    • The port address of an initiator.

In this example, a host other than Windows or Linux is added. Once the host is added, an initiator is manually registered with the host.

Procedure

  1. Get the URN of your tenant.
    Request
    GET https://<ViPR_VIP>:4443/tenant
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
  2. Use the tenant URN to add the host to ViPR.
    • If the host will be attached to EMC VMAX volumes, use <type>HPUX</type>
    • Otherwise, use <type>Other</type>
    Note Image
    Hosts of type Other, and HPUX are not automatically discovered, therefore, set the <discoverable> flag to false.

    Request
    POST https://<ViPR_VIP>:4443/tenants/urn:storageos:TenantOrg:6c7dde31-ec48-4028-8672-5e74f5754656:global/hosts 
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    
    <host_create>
         <type>Other</type>
         <host_name>192.168.0.1</host_name>
         <name>myhost2</name>
         <discoverable>false</discoverable>
    </host_create>
     
    Response
    HTTP 202 Accepted
    Content-Type: application/xml
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <task>
        <associated_resources/>
        <description>DISCOVER_HOST</description>
        <message>Operation completed successfully</message>
        <op_id>6392a7f5-a447-4458-8dd6-ce7015bb717a</op_id>
        <resource>
            <id>urn:storageos:Host:c2fe902f-0de0-4a92-a2a9-46ba87279bd2:vdc1</id>
            <link rel="self" href="/compute/hosts/urn:storageos:Host:c2fe902f-0de0-4a92-a2a9-46ba87279bd2:vdc1"/>
            <name>myhost2</name>
        </resource>
        <link rel="self" href="/compute/hosts/urn:storageos:Host:c2fe902f-0de0-4a92-a2a9-46ba87279bd2:vdc1/tasks/6392a7f5-a447-4458-8dd6-ce7015bb717a"/>
        <state>ready</state>
    </task>
    
    If the message from the returned task is Operation completed successfully, the host is now added to ViPR.
  3. Register an initiator associated with the host by calling the following POST. The new host initiator is returned.
    Request
    POST https://<ViPR_VIP>:4443/compute/hosts/{Host_URN}/initiators
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
     
    <initiator_create>
           <protocol>FC</protocol>
           <initiator_port>10:13:27:65:60:38:68:BE</initiator_port>
    </initiator_create>
    
    Response
    HTTP 200 OK
    Content-Type: application/xml
    <initiator>
           <creation_time>1379202603661</creation_time>
           <id>urn:storageos:Initiator:07b2e71d-cb4c-49c9-94fe-1feab7878d35:vdc1</id>
           <inactive>false</inactive>
           <link
                  href="/compute/initiators/urn:storageos:Initiator:07b2e71d-cb4c-49c9-94fe-1feab7878d35:vdc1"
                  rel="self"/>
           <tags/>
           <host>
                  <id>urn:storageos:Host:c2fe902f-0de0-4a92-a2a9-46ba87279bd2:vdc1</id>
                  <link
                         href="/compute/hosts/urn:storageos:Host:c2fe902f-0de0-4a92-a2a9-46ba87279bd2:vdc1"
                         rel="self"/>
           </host>
           <protocol>FC</protocol>
           <hostname>myhost</hostname>
           <initiator_port>10:13:27:65:60:38:68:BE</initiator_port>
    </initiator>
    
Back to Top

Add a host to a cluster

Optionally, hosts can be added to ViPR clusters. Adding hosts to clusters allows service operations to be performed exclusively on a single host, or shared across all the hosts in a cluster.

Before you begin

  • Authenticate with the ViPR REST API as a Tenant Administrator.
  • Clusters can only contain the same type of hosts.
  • A host can only be used in one cluster.
  • You need the following information:
    • The URN of the tenant, if you need to create the cluster before adding the host. To get the URN of the current tenant, use GET /tenant.
    • The URN of the host being added to the cluster. To determine the ID of the host, you can use GET /compute/hosts/bulk to get the list of all hosts IDs and then GET /compute/hosts/{Host_URN} to show the details of a specific host.
    • The URN of the cluster.

The EMC ViPR REST API Reference provides a description and complete list of parameters for the REST API methods used in this section.

Procedure

  1. If the cluster does not already exist, create one with the following POST.
    Request
    POST https://<ViPR_VIP>:4443/tenants/{Tenant_URN}/clusters
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    
    <cluster_create>
          <name>Win_cluster_1</name>
    </cluster_create>
    Response
    HTTP 200 OK
    Content-Type: application/xml
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <cluster>
        <creation_time>1399748901762</creation_time>
        <global>false</global>
        <id>urn:storageos:Cluster:2f6b27f2-5eb9-4b8f-8519-050a43f3c733:vdc1</id>
        <inactive>false</inactive>
        <internal>false</internal>
        <link rel="self" href="/compute/clusters/urn:storageos:Cluster:2f6b27f2-5eb9-4b8f-8519-050a43f3c733:vdc1"/>
        <name>Win_cluster_1</name>
        <remote>false</remote>
        <tags/>
        <vdc>
            <id>urn:storageos:VirtualDataCenter:440b70de-fd36-4361-a455-b6ca65fb8228:vdc1</id>
            <link rel="self" href="/vdc/urn:storageos:VirtualDataCenter:440b70de-fd36-4361-a455-b6ca65fb8228:vdc1"/>
        </vdc>
        <tenant>
            <id>urn:storageos:TenantOrg:6c7dde31-ec48-4028-8672-5e74f5754656:global</id>
            <link rel="self" href="/tenants/urn:storageos:TenantOrg:6c7dde31-ec48-4028-8672-5e74f5754656:global"/>
        </tenant>
    </cluster>
    
    
  2. A host is added to a cluster by updating the <cluster> attribute of a host, using PUT /compute/hosts/{Host_URN}. This example uses the URN of the new cluster, from the cluster create call. A task is returned.
    Request
    PUT https://<ViPR_VIP>:4443/compute/hosts/urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    
    <host_update>
         <cluster>urn:storageos:Cluster:9a18479e-d36e-44cc-bdae-f8d44720dbe3:vdc1</cluster>
    </host_update>
    Response
    HTTP/1.1 202 Accepted
    Content-Type: application/xml
    
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <task>
        <associated_resources/>
        <description>DISCOVER_HOST</description>
        <op_id>5e7a5c9d-2a37-4f43-9534-727dc396804f</op_id>
        <resource>
            <id>urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1</id>
            <link rel="self" href="/compute/hosts/urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1"/>
            <name>host219</name>
        </resource>
        <link rel="self" href="/compute/hosts/urn:storageos:Host:24e9c36a-804d-4d05-a646-a64a47accc7e:vdc1/tasks/5e7a5c9d-2a37-4f43-9534-727dc396804f"/>
        <start_time>1399749237037</start_time>
        <state>pending</state>
    </task>

Results

If the message from the returned task is Operation completed successfully, the host is now added to the cluster.

Back to Top

Important REST API calls to manage hosts and clusters

The table shows some important APIs that are used to manage hosts, vCenters and Windows clusters.

Back to Top