HP CloudSystem Matrix/Matrix Operating Environment 7.0 Integration Interfaces API and CLI Operations Reference Guide Abstract This document describes the rich set of Matrix OE’s infrastructure orchestration (IO) interfaces available to HP customers, partners, and integrators. These interfaces allow customers to integrate Matrix OE into their business and IT operations processes. Partners and Integrators can use the interfaces in combination with their own offerings to provide new, rich capabilities.
© Copyright 2012 Hewlett-Packard Development Company, L.P. Warranty The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
Contents 1 Introduction...............................................................................................7 Integration Interface Overview....................................................................................................8 New Features in 7.0..................................................................................................................9 2 Accessing the Web Service Interfaces.........................................................11 Accessing WSDL............
createServerPool................................................................................................................22 deleteServerPool................................................................................................................22 moveServerToServerPool......................................................................................................22 assignUsersToServerPool....................................................................................................
LogicalServerDetails................................................................................................................34 LogicalServerGroupDetails.......................................................................................................34 LogicalServerGroupInfo...........................................................................................................34 LogicalServerInfo.................................................................................................
Workflow..............................................................................................................................46 WwnConnection....................................................................................................................46 5 Exceptions...............................................................................................47 IOSoapException...................................................................................................................
1 Introduction HP CloudSystem Matrix is the industry’s first Converged Infrastructure platform that doubles administrator productivity and reduces total cost of ownership (TCO) versus traditional infrastructures. HP CloudSystem Matrix integrates silos of compute, storage, network, and facilities resources with unified management to deliver a virtualized, highly automated environment.
Integration Interface Overview Figure 1 HP Matrix Operating Environment Integration Interfaces Figure 1 (page 8) depicts the set of integration interfaces allowing customers and partners to integrate Matrix OE capabilities into their environment and products. The integration interfaces include: • Web Service Interfaces to initiate lifecycle operations on infrastructure services including creation and deletion of services, and to view or modify an existing service.
New Features in 7.0 The HP Matrix Operating Environment 7.0 release includes a new v3 service endpoint with interface extensions. The v1 and v2 endpoints continue to be served, so clients of these interfaces remain compatible with the 7.0 release.
◦ LogicalSoftware.resourceBindingId ◦ RequestInfo.organizationId ◦ ServerPool.cloudCapacityPoolIds ◦ ServerPool.esxCapacityPoolIds ◦ ServerPool.organizationId ◦ ServiceInfo.id ◦ ServiceInfo.organizationId The introduction of support for organizations makes it possible for a user to be a member of multiple organizations. In this case, the organization context used in processing an API operation is chosen arbitrarily.
2 Accessing the Web Service Interfaces Accessing WSDL The Web Service Description Language or WSDL (See Reference [1]) definition of IO operations can be accessed from any installed IO system using a web browser. For example, if the software is installed on a server with IP address 192.168.0.25, then to access the WSDL type into the web browser: https://192.168.0.25:51443/hpio/controller/soap/v3?wsdl The browser will show the formal XML definition of the Web Service Interface.
3 Operations The supported operations are specified in the following sections, grouped by target data type. Version getVersion Name getVersion Parameters none Returns String version Exceptions IOSoapException Gets the IO product version Product version string (e.g., “6.0.0”) or “Unknown” if the version cannot be determined Template listTemplates Name listTemplates Parameters none Returns List templates Exceptions IOSoapException Gets a list of templates. If the template.
TemplateNotFoundException IOSoapException deleteTemplate Name deleteTemplate Deletes an existing template. This operation may be performed only by an infrastructure orchestration Administrator or Architect. Parameters String templateName The name of the template to delete Returns none Exceptions InvalidParameterException TemplateNotFoundException IOSoapException Service listServices Name listServices Gets a list of services owned by the requester.
List serverPoolNames Optional list of server pools used to create the service. If null, the pools currently available to the requesting user are used. String ownerEmailAddress Optional email address of the service owner (the user performing the operation). If specified, the value replaces the user’s email address on record. If the value is an empty string, any existing email address is removed with no replacement.
List serverPoolNames Optional list of server pools from which to allocate physical servers, if necessary. If null, the pools currently available to the requesting user are used.
ServiceNotFoundException IOSoapException Request listRequests Name listRequests Parameters none Returns List requests Exceptions IOSoapException Gets a list of requests initiated by the requester. For Administrator users, the list contains all requests.
RequestNotFoundException IOSoapException continueRequest Name continueRequest Continues a paused request. This operation may be performed only by an infrastructure orchestration Administrator.
addServersToLogicalServerGroup Name addServersToLogicalServerGroup Adds logical servers to a logical server group to achieve the specified target count (flex up) Parameters String serviceName The ID or name of service containing the logical server group String The name of the logical server group to adjust logicalServerGroupName int targetServerCount The target number of logical servers in the group. List serverPoolNames Optional list of server pools used to fulfill the request.
String The name of the logical server group logicalServerGroupName int targetServerCount The target number of active logical servers boolean acceptPartialResult Accept a partial result when too few logical servers are available to achieve the target count. If false, an error is returned in this case and the operation is not partially performed. List serverPoolNames Optional list of server pools from which to allocate physical servers, if necessary.
LogicalServerNotFoundException ServiceNotFoundException IOSoapException deactivateLogicalServers Name deactivateLogicalServers Deactivates selected logical servers in an infrastructure service Parameters String serviceName The ID or name of the service containing the logical servers to deactivate List logicalServerNames A list of names of logical servers to deactivate.
ServiceNotFoundException IOSoapException powerOnLogicalServers Name powerOnLogicalServers Powers on one or more logical servers Parameters String serviceName The ID or name of service containing the logical servers List logicalServerNames A list of names of logical servers to power on Returns String requestId Request ID for the operation Exceptions InvalidParameterException LogicalServerNotFoundException ServiceNotFoundException IOSoapException syncLogicalServers Name syncLogicalServe
createServerPool Name createServerPool Creates an empty server pool. This operation may be performed only by an infrastructure orchestration Administrator or Organization Administrator. Parameters String serverPoolName The name of the server pool to create. It is limited to 64 characters (alphanumeric, hyphen, underscore, and space).
List userNames Returns none Exceptions InvalidParameterException A list of the names of users and Active Directory groups for which to allow server pool access ServerPoolNotFoundException UserNotFoundException IOSoapException unassignUsersFromServerPool Name unassignUsersFromServerPool Removes user access to a server pool. This operation may be performed only by an infrastructure orchestration Administrator or Organization Administrator.
Subnet listSubnets Name listSubnets Gets a list of subnets available to the user. This operation may be performed only by an infrastructure orchestration Administrator or Architect or an Organization Administrator. Parameters none Returns List subnets List of SubnetInfo objects containing information about network resources Exceptions IOSoapException getSubnet Name getSubnet Gets details of a specified subnet.
Storage listSanVolumes Name listSanVolumes Parameters none Returns List sanVolumes Exceptions IOSoapException Gets a list of SAN volume resources. This operation may be performed only by an infrastructure orchestration Administrator. List of SanVolume objects containing information about storage resources getSanVolume Name getSanVolume Gets information about a specified SAN volume. This operation may be performed only by an infrastructure orchestration Administrator.
Organization listOrganizations Name listOrganizations Parameters none Returns List organizations Exceptions IOSoapException Gets a list of existing organizations. This operation may be performed only by a Service Provider Administrator. A list of Organization objects representing the organizations defined. getOrganization Name getOrganization Gets information about a specified organization. This operation may be performed only by a Service Provider Administrator.
Returns none Exceptions InvalidParameterException TemplateNotFoundException No template exists with given template name OrganizationNotFoundException IOSoapException assignServerToOrganization Name assignServerToOrganization Assigns a compute resource to an organization. The compute resource must be in the Service Provider Unassigned pool and must not be in use. It is moved out of the Service Provider Unassigned pool and into the organization Unassigned pool.
organization. This operation may be performed only by a Service Provider Administrator. Parameters String subnetId The subnet to be assigned to an organization. String organizationName The ID or name of the organization to which to assign the subnet.
Returns none Exceptions InvalidParameterException IOSoapException endCmsMaintenance Name endCmsMaintenance Takes a CMS out of maintenance mode in a federated environment. This operation may be performed only by an infrastructure orchestration Administrator. Parameters String cmsName The fully-qualified domain name of the CMS to take out of maintenance mode.
4 Data Model The complex data types that are used in the API operation definitions are defined here. The Service data model incorporates many of the data types defined here. Figure 2 (page 30) shows the relationships between the major data types from a Service perspective, using Unified Modeling Language (UML) notation. Some of the data classes are separated into “Info” and “Details” classes, where the Details class extends the Info class.
ByteSize ByteSizeEnum enumValue (Required) The value as an enumerated type String otherValue A more specific value not defined in the enumerated type, when the enumValue is OTHER ByteSizeEnum Possible values: MB, GB, OTHER ComputeServer Extends String domainGroupId VirtualConnect domain group ID for blades, or compute actual name for other servers Boolean inUse Indicates whether a server profile is assigned to the server List localDisks Disk resources attached directly to t
ImageType imageType Only applicable when the type is IMAGE VirtualizationType virtualizationType Only applicable when the type is VM_TEMPLATE DeploymentService String name Name of the deployment server String ipAddress IP address of the deployment server DeploymentServiceType type List osTypes Operating system types supported by the deployment service DeploymentServiceType DeploymentServiceTypeEnum enumValue (Required) The value as an enumerated type String otherValue A more sp
UNSPECIFIED No assignment type specified OTHER A value other than above, possibly introduced by an extension in a subsequent release IPTypeEnum enumValue (Required) The value as an enumerated type String otherValue A more specific value not defined in the enumerated type, when the enumValue is OTHER IPType IPTypeEnum Possible values: IPV4, IPV6, UNSPECIFIED, OTHER LeasePeriod Long startEpoch (Required) The beginning of the lease term, in milliseconds since the epoch Long endEpoch The end of the
LogicalIPAddress String address The IP address, or a logical representation for DHCP assigned addresses IPAddressAssignmentType assignmentType Manner in which the IP address is assigned Cost cost Cost associated with the IP address Long createEpoch Time at which the logical object was created, in milliseconds since the epoch Long lastModifiedEpoch Time at which the logical object was last modified, in milliseconds since the epoch LogicalNetworkInterface String name Name assigned to the network in
Integer bootSequenceOrdinal Indicates the sequence in which the logical server group is booted relative to others, or 0 if no sequence is defined ServiceEntityStatus status Status of operation/automation for the logical server group String notes Logical server group notes specified in the template Long createEpoch Time at which the logical object was created, in milliseconds since the epoch Long lastModifiedEpoch Time at which the logical object was last modified, in milliseconds since the epoch L
String osCustomizationFileName The name of a file containing customization data needed to prepare a system (virtual servers only) VirtualizationType virtualizationType The virtualization technology used by a VM (virtual servers only) Integer ordinal Indicates the sequence in which the software is deployed to a server relative to others String resourceBindingId A unique identifier for the resource that is allocated to the logical software. A null value indicates that no resource is currently allocated.
OperatingSystemType OperatingSystemTypeEnum enumValue (Required) The value as an enumerated type String otherValue A more specific value not defined in the enumerated type, when the enumValue is OTHER OperatingSystemTypeEnum Possible values: WINDOWS, WINDOWS_2008, LINUX, HP_UX, VMWARE, HYPER_V, CITRIX_XEN, SOLARIS, AIX, UNKNOWN, UNSPECIFIED, OTHER Organization String name Name of the organization String id Unique identifier for the organization.
RequestHistoryItem Long occurEpoch Time at which the history item event occurred, in milliseconds since the epoch String message A message describing the event MessageSeverity messageSeverity Severity of the event RequestHistoryItemLevel level Detail level of the message RequestHistoryItemLevel RequestHistoryItemLevelEnum (Required) The value as an enumerated type enumValue String otherValue A more specific value not defined in the enumerated type, when the enumValue is OTHER RequestHistoryItemLev
RequestStatusEnum Possible values: PENDING, ALLOCATING, ALLOCATING_DATA_DISKS, ALLOCATED, ALLOCATED_DATA_DISKS, PAUSED_FOR_APPROVAL, APPROVED, SCHEDULING, SCHEDULED, PROVISIONING, SAN_VOLUME_PROVISIONING, SAN_VOLUME_PROVISIONED, SAN_VOLUME_DATA_DISK_PROVISIONING, PAUSED_FOR_MANUAL_STORAGE_ZONING, PAUSED_FOR_MANUAL_DATA_STORAGE_ZONING, PROVISIONED, PAUSED_FOR_OS_DEPLOYMENT, OS_DEPLOY, OS_DEPLOYED, RUNNING_SERVICE_BEGIN_ACTION, RUNNING_SERVICE_END_ACTION, RUNNING_GLOBAL_END_ACTION, RUNNING_LOGICAL_SERVER_GROU
String storageEntryId Storage pool entry ID. Only applicable when the state is CONFIGURED. String storageEntryName Storage pool entry name. Only applicable when the state is CONFIGURED. Boolean multiMemberSet Indicates whether the storage pool entry has multiple members. Only applicable when the state is CONFIGURED. Integer availableConnectionCount Number of storage pool entry connections available. Only applicable when the state is CONFIGURED.
Long maxSizeMB Maximum size of SAN volumes provisioned from the template, in megabytes List allowedRaidLevels RAID levels allowed for SAN volumes provisioned from the template List allowedOsTypes Operating system types allowed for SAN volumes provisioned from the template List requiredTags Storage tags that must be matched when allocating storage for the template List excludedTags Storage tags that must not be matched when allocating storage for the t
Integer processorCoreCount Number of physical processor cores in the server Integer processorSpeedMHz Speed of the server’s processors, in megahertz Integer processorLoadPercent Percentage of the server’s processor cycles being consumed, if the server is running a managed operating system String enclosure Blade enclosure name or rack name depending on server model String bay Blade enclosure bay name or rack position depending on server model Boolean validTarget False when errors are detected that
RESERVED Resources required for the entity have been reserved UP The entity is up and running OFF The entity is powered off DEACTIVATED The entity has been deactivated DOWN A failure has occurred on the entity PARTIAL The entity represents an aggregation of entities with different status values, none of which are IN_PROGRESS FAILED Processing of a request on the entity has failed CANCELING Processing of a request on the entity is being canceled UNKNOWN The entity status cannot be determined
Integer addressCount Number of addresses in the range Integer addressesInUse Number of addresses in the range that are allocated to a service Integer addressesInMaintenance Number of addresses in the range that are assigned to a server currently in maintenance, and are therefore unavailable StorageProvisioningType StorageProvisioningTypeEnum enumValue (Required) The value as an enumerated type String otherValue A more specific value not defined in the enumerated type, when the enumValue is OTHER St
SubnetInfo String id The subnet ID, usually discovered from the managed environment String address Network address for the subnet String mask Subnet mask List sources The source types from which the network was discovered/defined IPType ipType Primary IP type for the subnet Boolean bootNetwork Indicates whether the subnet serves as a boot network Boolean isPublic Indicates whether the subnet is publicly addressable Boolean shareable Indicates whether the subnet may be shared ac
VirtualSwitch String name Name of the virtual switch List subnetIds IDs of the subnets served by the virtual switch VmHost Extends ServerResource VirtualizationType virtualizationType Virtualization type used by the VM host String hostname Network hostname of the VM host String dnsDomain Network domain of the VM host String ipAddress Network IP address of the VM host String clusterName Name of the cluster containing the VM host Boolean haEnabled Indicates whether the VM host supports
5 Exceptions IOSoapException An error occurred while processing the operation. This is the base class for all the API exception. This exception is returned for general errors, where the more specific exceptions do not apply. String message A string describing the error InvalidParameterException An interface parameter value was not valid LogicalServerGroupNotFoundException A specified logical server group name was not found in a specified service.
SanVolumeNotFoundException A specified SAN volume ID was not recognized. String sanVolumeId The SAN volume ID that was not recognized SanVolumeTemplateNotFoundException A specified SAN volume template ID was not recognized. String sanVolumeTemplateId The SAN volume template ID that was not recognized ServerInUseException A specified compute resource is in use and cannot be un/assigned from/to an organization.
TemplateNotFoundException A specified template name was not recognized. String templateName The template name that was not recognized UserNotFoundException A specified user name was not recognized.
6 Example Usage The web service operations may be called individually for targeted purposes or they may be sequenced to perform more complex actions. Physical Server Maintenance Example If a physical server in use by an infrastructure service experiences a hardware failure, one may wish to move it to the Maintenance pool in IO and use another server in the infrastructure service. The following sequence of operations may be used for that purpose. (Note: Error handling is not considered in this example.
7 Sample Java Client The Web Service Interfaces may be accessed from a Java client program by using one of the generally available tools to create Java language bindings from the WSDL. This sample uses the wsdl2java utility provided with Apache CXF (cxf.apache.org).
Sample Code IO_IOSoapServicePort_Client.java: package com.hp.io.soap.v3; import com.hp.io.soap.v1.*; import import import import java.util.EnumSet; java.util.HashMap; java.util.Map; java.util.Set; import javax.net.ssl.TrustManager; import javax.xml.namespace.QName; import import import import import import import import org.apache.cxf.configuration.jsse.TLSClientParameters; org.apache.cxf.endpoint.Client; org.apache.cxf.endpoint.Endpoint; org.apache.cxf.frontend.ClientProxy; org.apache.cxf.transport.
new LeasePeriod(), "hostx", null, null, "Service Purpose", "MyBillingCode"); // // // // // Start now and never expire Hostname completion text Use all available server pools Do not set user's email address Annotation for the new service RequestStatus requestStatus = waitForTerminalStatus(port, requestId); System.out.println("Operation completed with status: " + requestStatus.getEnumValue()); } catch (Exception e) { System.out.println("Operation failed with exception: " + e.getMessage()); } System.out.
// Configure TLS client parameters HTTPConduit conduit = (HTTPConduit) proxy.getConduit(); TLSClientParameters tcp = new TLSClientParameters(); tcp.setTrustManagers( new TrustManager[] { new TrustAllX509TrustManager() }); tcp.setDisableCNCheck(true); conduit.setTlsClientParameters(tcp); } /** * Waits until the specified request is no longer active, and * returns the terminal status.
import javax.net.ssl.X509TrustManager; /** * This class allow any X509 certificates to be used to authenticate the * remote side of a secure socket, including self-signed certificates. */ public class TrustAllX509TrustManager implements X509TrustManager { /** Empty array of certificate authority certificates. */ private static final X509Certificate[] acceptedIssuers = new X509Certificate[] {}; /** * Always trust for client SSL chain peer certificate chain with any * authType authentication types.
8 Sample VisualStudio/.NET/C# Client The Web Service Interfaces may be accessed from a .NET client program by using Microsoft VisualStudio® to create C# language bindings from the WSDL: • In VisualStudio®, create (for example) a consoled application • Add a Service Reference, and enter the IO web service endpoint URL (See the Accessing WSDL section) • Enter a service name (e.g., “IOService”) as the Namespace value • Add these namespaces: using System.Net; using System.Net.Security; using System.
//get the security node XmlNode securityNode = headersNode.ChildNodes[1]; //change the timestamp token securityNode.FirstChild.FirstChild.InnerText = String.Format("{0:s}", DateTime.Now); securityNode.FirstChild.LastChild.InnerText = String.Format("{0:s}", DateTime.Now.AddMinutes(30)); //change the username token with username and password securityNode.LastChild.FirstChild.InnerText = "administrator"; securityNode.LastChild.ChildNodes[1].
NOTE: The Timestamp and UsernameToken values are intentionally left blank here. They are set dynamically by the C# code. 58 • Modify the wsa:To value inserted in the previous step to specify the target system IP address or hostname. • Compile and run. Sample VisualStudio/.
9 References 1. Web Services Description Language (WSDL) 1.1 W3C Note 15 March 2001 http://www.w3.org/TR/wsdl 2. Fully Qualified Domain Name See RFC 1035 Section 2.3.1 http://tools.ietf.org/html/rfc1035 3. W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes See 3.3.8 Date & Time representation http://www.w3.
10 For more information To read more about the HP Matrix Operating Environment, go to www.hp.