Add Hosts and Clusters with the ViPR REST API

TOC

BacktoTop

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.

This article applies to EMC ViPR 2.0.

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:

BacktoTop

Add a Linux host to ViPR

This section provides ViPR Tenant Administrators the ViPR support requirements, and prerequisite information to prepare Linux hosts for ViPR integration, and the steps to add the host to ViPR.

BacktoTop

ViPR configuration requirements for Linux hosts

Linux hosts must be configured as follows to be discovered by ViPR, and used for ViPR provisioning.

  • SSH and LVM are enabled. ViPR uses SSH for Linux hosts.
  • EMC PowerPath or native Linux multipathing software is installed.

    Refer to the EMC PowerPath for Linux Installation and Configuration Guide and the SuSE Linux Enterprise Server (SLES): Storage Administration Guide, under "Configuring the System for Multipathing."

  • Time synchronization is configured.
  • In some cases, it may be necessary to install lsb_release. If host discovery fails due to compatibility, and logs indicate that the lsb_release command is not found, the package that includes that command must be installed.

BacktoTop

Linux host version support for ViPR discovery

Operating System Supported Versions Additional Software
Red Hat Enterprise Linux (RHEL) 5.9, 5.10, 6.3, 6.4, 6.5
  • LVM (Linux Logical Volume Manager)
  • Linux Native Multipathing or EMC PowerPath®
SUSE Linux Enterprise Server 11 SP1, 11 SP2, 11 SP3
  • LVM (Linux Logical Volume Manager)
  • Linux Native Multipathing or EMC PowerPath
BacktoTop

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

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:</id> <link href="/compute/hosts/urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:" rel="self"/> <name>lglw7141</name> </resource> <link rel="self" href="/compute/hosts/urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:/tasks/90827e3a-ce0f-42b3-9499-d43986dba44b"/> <start_time>1386618442169</start_time> <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> <id>urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:</id> <inactive>false</inactive> <link href="/compute/hosts/urn:storageos:Host:ead39b5a-07f4-4cb4-8124-35aa864fe760:" rel="self"/> <name>lglw7141</name> <tags/> <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> <tenant> <id>urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:</id> <link href="/tenants/urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:" rel="self"/> </tenant> <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>

BacktoTop

Add a Windows host to ViPR

This section provides ViPR Tenant Administrators the ViPR support requirements, and prerequisite information to prepare Windows hosts for ViPR integration, and the steps to add the host to ViPR.

BacktoTop

Windows Server version support

BacktoTop

ViPR configuration requirements for Windows hosts

Windows hosts must be configured as follows to be discovered by ViPR, and used for ViPR provisioning.

Windows Remote Management (WinRM) must be enabled.

Refer to Configuring WinRM on a Windows Host for ViPR.

Either EMC PowerPath, or Microsoft MPIO (not both) must be enabled.

For details see either the EMC PowerPath and PowerPath/VE for Microsoft Windows Installation and Administration Guide or the Windows: Microsoft Multipath I/O Step-by-Step Guide.

Time synchronization is configured.

If using LDAP or Active Directory domain account credentials, the domain user credentials must be in the same domain where the Windows host is located; otherwise the Windows host discovery will fail.

BacktoTop

Configuring WinRM on a Windows host for ViPR

Configures a Windows host to allow ViPR to run commands on it.

Before you begin

  • You must be logged in to the Windows host as administrator.
  • For the ViPR server to connect to Windows remote hosts, the host must accept remote Windows PowerShell commands. You can do this by enabling Windows remote access over HTTP.

Procedure

  1. At an administrator command prompt on the Windows host, issue the following command:
    winrm quickconfig
    This starts up a listener on port 5985. The port on which you start the listener must be consistent with the port that you configure for the host in the host asset page.
  2. You may need to make some configuration changes depending on how you want to connect to the host.
    • If you want ViPR to connect to the host as a local user, you need to:
      1. Check the winrm settings by running:

        winrm get winrm/config/service

        Basic Authentication and AllowUnencrypted must be set to true.

      2. If basic authentication is not set to true, run:

        winrm set winrm/config/service/auth @{Basic="true"}

      3. If AllowUnencrypted is not set to true, run:

        winrm set winrm/config/service @{AllowUnencrypted="true"}

      4. Add the host to the ViPR, Physical Assets > Hosts page.
    • If you want ViPR to connect to the host as a domain user, you need to:
      1. Ensure Kerberos is enabled. You can check using:

        winrm get winrm/config/service

      2. If you need to enable Kerberos, run:

        winrm set winrm/config/service/auth @{Kerberos="true"}

      3. Ensure that your domain has been configured as an authentication provider in ViPR by a System Administrator (Security > Authentication Providers).
      4. Add the host to the ViPR Physical Assets > Hosts page by a System Administrator.

        The credentials you supply for the host are of the form:

        domain\username

  3. Check that the host is displayed as valid in the table.

After you finish

After ViPR is deployed, you can check that the host is displayed as valid in the Physical Assets > Hosts page. If you receive the following message WinRM may not be enabled or configured properly, or there may be a network problem.

Failed to connect to host. Please ensure the connection details are correct. [Error connecting: Connection refused]

BacktoTop

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

  • Your Windows host must be running the correct version of Windows, and be properly configure. In particular, your ViPR installation, the Windows host, and the user name you use to authenticate must all be in the same Windows domain.
  • Authenticate with the ViPR REST API as a Tenant Administrator.
  • 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. 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"/> <start_time>1399747448483</start_time> <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>

BacktoTop

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>

BacktoTop

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.

BacktoTop

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.