HP CloudSystem Matrix/Matrix Operating Environment 7.2 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 2009 – 2013 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
Contents I Matrix API................................................................................................10 1 Introduction..........................................................................................17 Integration interface overview..............................................................................................18 New features in 7.2...........................................................................................................18 New features in 7.1 Update 1.
getLogicalServer...........................................................................................................34 deactivateLogicalServers................................................................................................34 activateLogicalServers....................................................................................................35 powerOffLogicalServers.................................................................................................
quiesceCms..................................................................................................................48 unquiesceCms..............................................................................................................49 getCmsQuiesceStatus....................................................................................................49 LoadBalancer....................................................................................................................
DeploymentServiceType......................................................................................................62 DeploymentServiceTypeEnum...............................................................................................62 DrMode...........................................................................................................................62 DrModeEnum....................................................................................................................
RequestHistoryItem.............................................................................................................72 RequestHistoryItemLevel......................................................................................................72 RequestHistoryItemLevelEnum...............................................................................................72 RequestInfo......................................................................................................................
SanVolumeTemplateNotFoundException................................................................................84 ServerInUseException.........................................................................................................84 ServerPoolNotFoundException.............................................................................................84 ServerPoolNotFoundForResourceException.............................................................................
DiskUsageDetail..............................................................................................................106 IpAddressUsageDetail......................................................................................................106 13 Exceptions........................................................................................107 AuthenticationException....................................................................................................107 AuthorizationException..
Part I Matrix API
Contents 1 Introduction.............................................................................................17 Integration interface overview...................................................................................................18 New features in 7.2................................................................................................................18 New features in 7.1 Update 1..................................................................................................
deactivateLogicalServers.....................................................................................................34 activateLogicalServers.........................................................................................................35 powerOffLogicalServers......................................................................................................35 powerOnLogicalServers......................................................................................................
unquiesceCms...................................................................................................................49 getCmsQuiesceStatus.........................................................................................................49 LoadBalancer.........................................................................................................................49 listLoadBalancers......................................................................................................
DeploymentServiceTypeEnum....................................................................................................62 DrMode................................................................................................................................62 DrModeEnum.........................................................................................................................62 DrPolicy.........................................................................................................
RequestHistoryItemLevel...........................................................................................................72 RequestHistoryItemLevelEnum....................................................................................................72 RequestInfo............................................................................................................................73 RequestStatus..................................................................................................
ServerInUseException..............................................................................................................84 ServerPoolNotFoundException..................................................................................................84 ServerPoolNotFoundForResourceException.................................................................................84 ServerResourceNotFoundException...........................................................................................
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 18) 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.
Interface extensions include: • • Import VM operations: ◦ listUnmanagedVirtualMachines ◦ importVirtualMachineAsService Modify Service operation: ◦ • • modifyService Organization lifecycle and user assignment operations: ◦ createOrganization ◦ deleteOrganization ◦ assignAdministratorsToOrganization ◦ unassignAdministratorsFromOrganization ◦ assignUsersToOrganization ◦ unassignUsersFromOrganization Added a Property class for user-defined properties to facilitate external integration.
• • • • ◦ releaseFloatingIPAddress ◦ listUnassociatedFloatingIPAddresses Server snapshot operations: ◦ createServerSnapshot ◦ deleteServerSnapshot ◦ revertServerSnapshot ◦ listServerSnapshots New Organization operations: ◦ assignSoftwareToOrganization ◦ unassignSoftwareFromOrganization New data model classes: ◦ CustomOsImageAttribute ◦ CustomStorageVolumeAttributes ◦ ServerSnapshot New attributes in the CustomTemplateAttributes class: ◦ CustomOsImageAttribute ◦ CustomStorage
• • • LoadBalancer operations: ◦ listLoadBalancers ◦ addLoadBalancer ◦ modifyLoadBalancer ◦ removeLoadBalancer ◦ addLoadBalancerCertificate ◦ removeLoadBalancerCertificate ◦ setLoadBalancerPassword ◦ unsetLoadBalancerPassword LogicalLoadBalancer operations: ◦ createLogicalLoadBalancerGroup ◦ deleteLogicalLoadBalancerGroup ◦ addLogicalLoadBalancerGroupMember ◦ removeLogicalLoadBalancerGroupMember FirewallRuleGroup operations: ◦ getFirewallRuleGroup ◦ addRuleToFirewallRuleGrou
◦ RequestInfo – ◦ ◦ manualCleanUpRequired ServiceInfo – DrPolicy – DrState TemplateInfo – isCustomizable – DrPolicy Chargeback HP Matrix OE infrastructure orchestration includes API extensions to retrieve chargeback usage data, described in Part II “Chargeback API”. Client software can connect to the chargeback server to build infrastructure resource allocation and usage reports for information on current and past services.
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 an IP address of , enter the following into the web browser to access the WSDL: https://:51443/hpio/controller/soap/v6?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.
TemplateNotFound Exception 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 TemplateNotFound Exception IOSoapException Service listServices Name listServices Gets a list of services owned by the requester.
String replacementText String used to make the template hostnames unique. The string is substituted for the # symbol used in the template element names. If no such replacement is defined in the template, this value may be null. 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).
Returns String requestId Exceptions InvalidParameter Exception Request ID for the operation. ServiceNotFound Exception UserNotFoundException IOSoapException deactivateService Name deactivateService Deactivates all logical servers in an infrastructure service (existing at the time of the request). Parameters String serviceName The ID or name of the service containing the logical servers to deactivate. Returns String requestId Request ID for the operation.
is open ended. Otherwise, the endEpoch must be greater than both the startEpoch value and the current time. Returns String requestId Exceptions InvalidParameterException Request ID for the operation. ServiceNotFoundException IOSoapException powerOffService Name powerOffService Powers off all logical servers in an infrastructure service (existing at the time of the request). Parameters String serviceName The ID or name of the service containing the logical servers to power off.
operation may be performed only by an infrastructure orchestration Administrator. Parameters String serviceName The name of the new service to create. String vmId ID of the virtual machine to import. String organizationName ID or name of the organization to own the service, if the service owner is a member of multiple organizations. String owner Optional owner to assign to the service. Defaults to the requesting user.
Returns List requests Exceptions IOSoapException A List of RequestInfo objects containing request status information. getRequestInfo Name getRequestInfo Gets status information about a specified request. Parameters String requestId The ID of the request for which to get status (returned when the action was initiated). Returns RequestInfo request A RequestInfo object containing the status of the request.
Returns None Exceptions InvalidParameterException RequestNotFoundException IOSoapException cancelRequest Name cancelRequest Cancels a request, if allowed for the request type and status. Parameters String requestId The ID of the request to cancel (returned when the action was initiated). String note Optional note to be added to the request history on successful cancellation.
Exceptions InvalidParameterException LogicalServerGroupNot FoundException NoServerPoolsAvailable Exception ServerPoolNotFound Exception ServiceNotFoundException IOSoapException addDiskToLogicalServerGroup Name addDiskToLogicalServer Group Adds a data disk to a logical server group, with Administrator approval. The new disk is based on an existing disk stereotype already in use by the logical server group. Parameters String serviceName The ID or name of service containing the logical server group.
List tags Optional. A list of storage tags. For physical disks only. Ignored for virtual disks. For virtual disks, volume names are copied from the boot disk. RaidLevelEnum raidLevel Optional. The raid level for the disk. Defaults to “any.” For physical disks only. Ignored for virtual disks. Boolean redundantPaths Optional. Mark the disk as needing redundant SAN paths. Defaults to single path. For physical disks only. Ignored for virtual disks. RawMappingTypeEnum rawMappingType Optional.
Logical Server findLogicalServer Name findLogicalServer Gets information about the logical server associated with a hostname or IP address. Parameters String hostId The fully-qualified hostname or IP address of the logical server to look up. If hostId is an IP address, the search will be successful if the IP address is equivalent to a LogicalIPAddress referenced by a LogicalServer’s LogicalNetworkInterface.
activateLogicalServers Name activateLogicalServers Activates selected logical servers in an infrastructure service. Parameters String serviceName The ID or name of the service containing the logical servers to activate. List logicalServerNames A list of names of logical servers to activate. 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 powerCycleLogicalServers Name powerCycleLogicalServers Power cycles 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 cycle. Returns String requestId Request ID for the operation.
Exceptions InvalidParameterException LogicalServerNotFound Exception ServiceNotFoundException IOSoapException syncLogicalServers Name syncLogicalServers Parameters none Returns none Exceptions IOSoapException Causes IO to resynchronize the state of the logical servers that IO is managing with the current state of the logical servers in Matrix OE visualization. This operation runs asynchronously, returning before the synchronization has completed.
Returns none Exceptions InvalidParameterException IOSoapException deleteServerPool Name deleteServerPool Deletes an existing server pool. Any servers in the server pool are moved to the "Unassigned" 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 delete.
ServerPoolNotFound Exception UserNotFoundException IOSoapException unassignUsersFromServerPool Name unassignUsersFromServer Removes user access to a server pool. This operation may be performed Pool only by an infrastructure orchestration Administrator or Organization Administrator. Parameters String serverPoolName The name of the server pool from which to remove user access. List userNames A list of the names of users and Active Directory groups for which to remove server pool access.
listUnmanagedVirtualMachines Name listUnmanagedVirtualMachines Parameters none Returns List unmanagedVirtualMachines Exceptions IOSoapException Lists Virtual Machines on registered hosts that are neither part of an existing service nor managed by Matrix OE visualization. This operation may be performed only by an infrastructure orchestration Administrator. A list of VirtualMachineInfo objects describing the unmanaged VMs.
getSubnet Name getSubnet Gets details of a specified subnet. This operation may be performed only by an infrastructure orchestration Administrator or Architect or an Organization Administrator. Parameters String subnetId The ID of the subnet for which to get details. Returns SubnetDetails subnet A SubnetDetails object containing the details of the subnet.
getSanVolumeTemplate Name getSanVolumeTemplate Gets information about a specified SAN volume template. This operation may be performed only by an infrastructure orchestration Administrator or Architect. Parameters String sanVolumeTemplateId The ID of the SAN volume template to get. Returns SanVolumeTemplate sanVolumeTemplate A SanVolumeTemplate object containing the details of the SAN volume template.
deleteOrganization Name deleteOrganization Deletes an organization with no resource assignments or existing services. This operation may be performed only by an infrastructure orchestration Administrator. Parameters String organizationName The ID or name of the organization to delete. Returns none Exceptions InvalidParameterException OrganizationNotFound Exception IOSoapException assignTemplateToOrganization Name assignTemplateTo Organization Assigns a template to an organization.
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. This operation may be performed only by an infrastructure orchestration Administrator. Parameters String serverResourceId The compute resource to be assigned.
Returns none Exceptions InvalidParameterException SubnetNotFoundException No subnet exists with given subnet ID. OrganizationNot FoundException IOSoapException unassignSubnetFromOrganization Name unassignSubnetFrom Organization Unassigns a subnet from an organization. The operation has no effect if the subnet is not assigned to the organization. A subnet may be unassigned even if services in the organization are using it.
String organizationName Returns none Exceptions InvalidParameterException The ID or name of the organization from which to unassign the software. SoftwareNotFoundException No software exists with the given software ID. OrganizationNotFound Exception IOSoapException assignAdministratorsToOrganization Name assignAdministrators ToOrganization Assigns users and user groups as Organization Administrators. A user or group can be assigned to multiple organizations.
is possible when an error occurs. This operation may be performed only by an infrastructure orchestration Administrator. Parameters List userNames A list of the names of users and Active Directory groups to assign as Organization Users, such as "Domain\User" or "localuser." String organizationName The ID or name of the organization to which to assign users.
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.
unquiesceCms Name unquiesceCms Parameters none Returns none Exceptions IOSoapException Removes the CMS from the quiesced state. This operation may be performed only by an infrastructure orchestration Administrator. getCmsQuiesceStatus Name getCmsQuiesceStatus Parameters none Returns CmsQuiesceStatus cmsQuiesceStatus Exceptions IOSoapException Gets the current quiesce status of the CMS. This operation may be performed only by an infrastructure orchestration Administrator.
Exceptions LoadBalancerNotFound Exception InvalidParameterException IOSoapException removeLoadBalancer Name removeLoadBalancer Removes a load balancer from the infrastructure orchestration server. This operation may be performed only by an infrastructure orchestration Administrator. Parameters String loadBalancerId The ID of the load balancer to remove.
Returns none Exceptions InvalidParameterException IOSoapException unsetLoadBalancerPassword Name unsetLoadBalancerPassword Unsets the password for a load balancer corresponding to a password ID. This operation may be performed only by an infrastructure orchestration Administrator. Parameters String passwordId Returns none Exceptions PasswordNotFoundException The password ID of a load balancer.
ServiceNotFoundException LogicalLoadBalancer NotFoundException IOSoapException addLogicalLoadBalancerGroupMember Name addLogicalLoadBalancer Adds a member to a logical load balancer group defined in an GroupMember infrastructure orchestration service. Parameters String serviceName The ID or name of the service which contains the group. String logicalLoadBalancerId The logical load balancer ID. String groupName The group name where to add the new member.
FirewallRuleGroup getFirewallRuleGroup Name getFirewallRuleGroup Gets the details of a specified firewall rule group. Parameters String firewallRuleGroupId The ID of the firewall rule group to get. Returns FirewallRuleGroupDetails Details of the firewall rule group.
the synchronization has completed. This operation may be performed only by an infrastructure orchestration Administrator. Parameters none Returns none Exceptions IOSoapException FloatingIPAddress addFloatingIPAddress Name addFloatingIPAddress Acquires a floating IP address and adds it to a specified logical server, with Administrator approval. The lifecycle of a floating IP address is independent from the server to which it is added, allowing it to be moved between servers.
LogicalServerNotFound Exception IOSoapException removeFloatingIPAddress Name removeFloatingIPAddress Removes a floating IP address from a logical server and releases it permanently. Parameters String serviceName The ID or name of the service containing the logical server. String logicalServerName The name of the logical server from which to remove the floating IP address. String ipAddress The floating IP address to remove. Returns String requestId Request ID for the operation.
ServerSnapshot listServerSnapshots Name listServerSnapshots Retrieves a list of snapshots for a server. Supported only for ESX VMs. Parameters String serviceName The ID or name of the service containing the logical server. String logicalServerName The name of the logical server for which to retrieve snapshot information. Returns List snapshots A list of snapshots for the servers.
Exceptions InvalidParameterException ServiceNotFoundException LogicalServerNotFound Exception IOSoapException deleteServerSnapshot Name deleteServerSnapshot Deletes a server snapshot and optionally its child snapshots. Supported only for ESX VMs. Parameters String serviceName The ID or name of the service containing the logical server. String logicalServerName The name of the logical server for which to delete a snapshot. String snapshotName The ID or name of the snapshot to delete.
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 58) 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 CidrIpRange String ipAddress IP address component of the CIDR specification. Integer cidrPrefixSize Specifies the CIDR notation for the prefix size for the specified IP address. CmsQuiesceState CmsQuiesceStateEnum enumValue (Required) The value as an enumerated type.
Cost Float value (Required) A numeric cost value. String units The units of the cost value. CostFrequency frequency Time period to which the cost value applies. CostFrequency CostFrequencyEnum 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.
CustomProcessorAttribute String logicalServerGroupName Name of logical server group for which to customize the processor count. Integer processorCount Customized processor count. CustomStorageVolumeAttribute String logicalDiskName Name of the virtual logical disk for which to customize the storage volumes. List storageVolumes Customized storage volume names. CustomSubnetBindingAttribute String originalSubnetId ID of a subnet specified in the template.
Organization processorArchitecture Processor architecture with which the software is compatible. DeploymentServiceType deploymentServiceType Only applicable when the type is IMAGE. ImageType imageType Only applicable when the type is IMAGE. VirtualizationType virtualizationType Only applicable when the type is VM_TEMPLATE. List softwareDiskDefinitions Breakdown of individual disk definitions for the software image, when available.
FirewallRule PacketProtocol packetProtocol Specifies the protocol type to be either TCP, UDP, or ICMP. Integer portRangeStart Starting port range. Integer portRangeEnd Ending port range. Integer icmpType ICMP type (specified if protocolType is ICMP above). Integer icmpCode ICMP code (specified if protocolType is ICMP above). List ipSources List of IP Sources allowed access on the port range specified above.
EXTERNAL [Not yet defined] 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.
LogicalDisk String name A logical name for the disk, based on the stereotypeName. String stereotypeName The name that appears in the template and applies across the Logical Server group. This name is used as a parameter to the addDiskToLogicalServerGroup operation. Integer size Minimum disk size, in the units specified by sizeUnits. ByteSize sizeUnits Disk size units. RaidLevel raidLevel RAID level defined for the disk. StorageType storageType The type of storage represented by the disk.
LogicalLoadBalancerDetails Extends LogicalLoadBalancerInfo List groups A list of load balancer groups. LogicalLoadBalancerGroupDetails Extends LogicalLoadBalancerGroupInfo List members A list of members in a load balancer group. LogicalLoadBalancerGroupInfo String name The name of the group. LogicalLoadBalancerProtocol protocol The type of protocol the application service will use.
List subnetIds A list of networks the load balancer needs to have access to. List tags A list of tags used to match a specific load balancer during allocation. LogicalLoadBalancerProtocol LogicalLoadBalancerProtocolEnum (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.
LogicalLoadBalancerDetails logicalLoadBalancer Details of the LogicalLoadBalancer associated with this LogicalServerGroup, if any. List virtualIPAddresses IP addresses assigned to the group for use as floating IP addresses within the group (for example, by an Oracle DB server). LogicalServerGroupInfo String serviceName Name of the service containing the logical server group. String name Name of the logical server group.
Integer maxMemorySize The maximum value to which the memory size may be updated, using the same units as the memory size. ByteSize memorySizeUnits Memory size units. Integer processorCount Minimum number of processors required for the logical server. Integer maxProcessorCount The maximum value to which the processor count may be updated. Integer processorSpeedMHz Minimum processor speed required for the logical server, in MHz (physical servers only).
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. List userDefinedProperties Additional properties defined in the template. MessageSeverity MessageSeverityEnum 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, WINDOWS_2012, LINUX, HP_UX, VMWARE, HYPER_V, CITRIX_XEN, SOLARIS, AIX, UNKNOWN, UNSPECIFIED, OTHER OrganizationDetails Extends OrganizationInfo. List administratorNames Names of the users assigned as Organization Administrators. List administratorGroupNames Names of the Active Directory groups assigned as Organization Administrators. List userNames Names of the users assigned as Organization Users.
RaidLevel RaidLevelEnum 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. RaidLevelEnum Possible values: RAID0, RAID1, RAID3, RAID4, RAID5, RAID6, RAID01, RAID05, RAID10, RAID50, RAID60, AUTOMATIC, UNSPECIFIED, OTHER RAID01 represents a RAID 0 striped data set which is then mirrored for recovery.
RequestInfo String id An identifier assigned to the request when it is submitted. Corresponds to the request parameters and return values defined for many of the API operations. RequestType type Type of operation represented by the request. Long submitEpoch Time at which the request was submitted, in milliseconds since the epoch. Long startEpoch Time at which processing started for the request, in milliseconds since the epoch.
PAUSED_FOR_PHYSICAL_NETWORK_ALLOCATION, PAUSED_FOR_VIRTUAL_NETWORK_ALLOCATION, FIREWALLRULEGROUP_PROVISIONING, FIREWALLRULEGROUP_DELETING, ASSOCIATING, ASSOCIATED, DELETING, DELETED, VALIDATING, OTHER A “terminal” status indicates that no more processing will be performed on the request. Terminal status values are COMPLETE, CANCELED, REJECTED, FAILED, and TERMINATED. RequestType RequestTypeEnum enumValue (Required) The value as an enumerated type.
RawMappingType rawMappingType Raw Disk Mapping (RDM) type of the volume. List wwnConnections Details of server connections for the volume. SanVolumeState SanVolumeStateEnum 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. SanVolumeStateEnum Possible values: CONFIGURED Storage is partitioned into a volume, the volume is presented to WWNs, and the WWNs are zoned.
ServerPool String name Name of the server pool. String notes Custom server pool notes. List vmHostIds IDs of the VM hosts in the server pool. List computeServerIds IDs of the compute servers in the server pool. List cloudCapacityPoolIds IDs of the cloud capacity pools in the server pool. List esxCapacityPoolIds IDs of the ESX capacity pools in the server pool List userNames Names of the users assigned to the server pool.
String bay Blade enclosure bay name or rack position depending on server model. Boolean validTarget False when errors are detected that would prevent successful provisioning. ServerSnapshot String name Name of the server snapshot. String id Identifier for the snapshot, unique within the set of snapshots for a server. String parentSnapshotId ID of the parent snapshot, if any.
ServiceEntityStatusEnum Possible values: NEW The entity has been defined but no work has been performed on it yet. ALLOCATED Resources required for the entity have been allocated. IN_PROGRESS A request is operating on the entity. 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.
SoftwareDiskDefinition String name Disk name, within a software image. Integer size Disk size, in the units specified by sizeUnits. ByteSize sizeUnits Disk size units. SoftwareType SoftwareTypeEnum 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.
SubnetDetails Extends SubnetInfo String dnsDomain DNS domain for the subnet. List dnsServers DNS servers configured for the subnet. List dnsSearchSuffixes DNS search suffixes configured for the subnet. List defaultGateways Default gateways configured for the subnet. String msDomainName The name of the MS domain to which Windows servers should be joined when provisioned on this subnet.
TemplateInfo String name Name of the template. Long createEpoch Time at which the template was created, in milliseconds since the epoch. Long lastModifiedEpoch (Required) Time at which the template was last modified, in milliseconds since the epoch. Cost cost Aggregate cost of resources for a service based on the template. Boolean isPublished Indicates whether the template is published for general use.
String clusterName Name of the cluster containing the VM host. Boolean haEnabled Indicates whether the VM host supports high availability for VM guests. List dataStores Does not include data stores that cannot be used or are specifically excluded for use by IO List virtualSwitches Virtual switches configured on the VM host. VmHostDataStore String mountPoint Mount point of the data store in the VM host file system. Long sizeMB Data store size, in megabytes.
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. LoadBalancerNotFoundException A specified load balancer was not found. String loadBalancerId The load balancer ID that was not recognized.
OrganizationNotFoundException A specified organization name was not recognized. String organizationName The organization ID or name that was not recognized. RequestNotFoundException A specified request ID was not recognized. String requestId The request ID that was not recognized. 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.
SoftwareNotFoundException A specified software ID was not recognized. String softwareId The software ID that was not recognized. SubnetNotFoundException A specified subnet ID was not recognized. String subnetId The subnet ID that was not recognized. 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. String userName The user name that 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).
package com.hp.io.soap.v6; 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.http.HTTPConduit; org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor; org.
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.println("Invoking deactivateService..."); try { String requestId = port.deactivateService(infServiceName); RequestStatus requestStatus = waitForTerminalStatus(port, requestId); System.out.
} /** * Waits until the specified request is no longer active, and * returns the terminal status. */ private static RequestStatus waitForTerminalStatus( IO port, String requestId) throws Exception { RequestStatus requestStatus = port.getRequestInfo(requestId).getStatus(); // Note: The request may require approval or other intervention // before reaching a terminal status while (!TERMINAL_STATUSES.contains(requestStatus.getEnumValue())) { // Check the status every 10 seconds Thread.
/** 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. * * @param chain The peer certificate chain. * @param authType The authentication type based on the client * certificate.
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 “Accessing WSDL” (page 23)) • Enter a service name (e.g., “IOService”) as the Namespace value • Add these namespaces: using using using using • System.ServiceModel; System.
binding.BypassProxyOnLocal = false; binding.Security.Mode = BasicHttpSecurityMode.Transport; binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.None; binding.Security.Transport.ProxyCredentialType = HttpProxyCredentialType.None; binding.Security.Transport.Realm = ""; binding.Security.Message.ClientCredentialType = BasicHttpMessageCredentialType.UserName; binding.Security.Message.AlgorithmSuite = System.ServiceModel.Security.SecurityAlgorithmSuite.Default; binding.
Part II Chargeback API
Contents 9 Introduction.............................................................................................97 Chargeback SOAP API............................................................................................................97 Creating a standard monthly chargeback report....................................................................97 10 Accessing the Chargeback Web Service Interfaces.....................................99 Accessing WSDL..........................................
14 Sample Python Client............................................................................109 15 Sample Chargeback Usage Report..........................................................
9 Introduction Chargeback SOAP API HP CloudSystem Matrix 7.1 includes a new chargeback feature. Chargeback is primarily a metering system capable of collecting and exposing usage data for the provisioned infrastructure.
NOTE: • You can use predefined chargeback formatters to create reports. They are available on the following website: www.hp.com/go/csdevelopers • Pricing information must be included in your services to have the information appear in the report. • The chargeback.bat utility can create reports up to and including the current date. However, data from any services created on the current date will not appear in the report because the current date has not yet elapsed.
10 Accessing the Chargeback Web Service Interfaces Accessing WSDL The Web Service Description Language or WSDL (see Reference [1]) definition of chargeback operations can be accessed from any installed chargeback system using a web browser.
11 Operations Operations The supported operations are specified in the following sections. Summary Usage Report getServiceUsagePage Name getServiceUsagePage Returns usage and cost data for selected services. Report result is paged according to the information passed in. Parameters Period period Specifies the period of time for which to return data, and specifies how data should be consolidated in the report. There are two options for formatting report result which depend on Period specification.
Returns ServiceUsageDetailPage Specified page for the query result containing service usage detailed resultReport data. This page is formatted according to PeriodType attribute. Exceptions InvalidPeriodException InvalidPagingException InvalidFilterException RequiredParameterException ChargebackException Aggregated Usage Report getAggregatedServiceUsage Name getAggregateServiceUsage Returns aggregated usage and cost values for selected services.
12 Data model The complex data types that are used in the API operation definitions are defined in this section. Figure 3 presents the relationship between the classes that are part of getServiceUsagePage. Figure 4 presents the data model returned from a getServiceUsageDetailPage operation and Figure 5 for getAggregateServiceUsage.
Period Represents the period of time of the data to be returned. Date startDate Start date from which to return data. Format: YYYY-MM-DD Date endDate End date from which to stop returning data. Format: YYYY-MM-DD PeriodType type Specifies how data must be consolidated in the report. PeriodType enum Represents the possible usage data grouping. PERIOD means that the result will consolidate one entry per service for the entire period, and DAILY means one entry per day.
int totalPages Filled every time the web service is called and contains the total number of pages based on the query executed and the pageSize. If no data is returned, totalPages is 0. bool lastPage Indicates if the returned page is the last page for the specified query. ServiceInformation Represents descriptive information of a service. String name Service name. String id Unique id used by Matrix OE infrastructure orchestration and chargeback.
ServiceUsagePage Paging pagingInformation Paging object with detailed information about the pages for the given query. List serviceUsageSummary List of registers returned by this query. A register is represented by a ServiceUsageSummary object. This contains allocation metric information for a given service in a given date. The number of objects returned in a page is determined by the pageSize and the amount of data resulted by specified query.
resources deployed to external cloud providers such as HP Cloud Services, Savvis, or Amazon EC2. BigDecimal allocationHours Total of allocations hours for the server in the given period or day. BigDecimal allocationCost Total cost of the server for the server in the given period or day. BigDecimal uptimeHours Total of uptime hours for the server in the given period or day. Uptime hours for cloud resources may vary 30 minutes. DiskUsageDetail String logicalDiskName Service disk name.
13 Exceptions AuthenticationException Username was not authenticated. String message A string describing the error AuthorizationException Username was not authorized or is not an infrastructure orchestration Administrator. String message A string describing the error ChargebackDataBaseException An error occurred during database query, or trying to connect to the chargeback database. String message A string describing the error ChargebackException An exception occurred during the request fulfillment.
PeriodStartDateGreaterThanEndDateException Start date is a date newer than end date. String message A string describing the error PeriodStartDateTooOldException Start date is older than 365 days from the current date. String message A string describing the error RequiredParameterException A required parameter was not specified.
14 Sample Python Client The following sample client was developed in Python 2.7.2 with the use of open source libraries. It provides the user with a UI to query the chargeback API and returns the report in a formatted PDF. To create the sample client environment: • Download and install Python 2.7 from python.org • Download and install Suds, a lightweight SOAP python client for consuming web services, from https://fedorahosted.
Figure 7 Example of a report for getAggregatedUsage generated from sample client Example 1 connection.py import suds PORT = "55443" SERVICE = "/hpio/chargeback/soap/v1?wsdl" TRANSPORT = "https://" URL = "{0}{1}:{2}{3}" class Connection(object): ''' classdocs ''' def __init__(self, server, username, password): ''' Constructor ''' endpoint = URL.format(TRANSPORT, server, PORT, SERVICE) self.client = suds.client.Client(url=endpoint) security = suds.wsse.Security() token = suds.wsse.
Example 2 reports.py import suds import datetime import locale import root.reports.reports_file from reportlab.platypus import Table, TableStyle, Paragraph from reportlab.platypus.flowables import PageBreak from reportlab.lib import colors from reportlab.lib.colors import Color, PCMYKColor, HexColor, black, white from reportlab.lib.styles import getSampleStyleSheet from reportlab.graphics.shapes import Drawing from reportlab.graphics.charts.piecharts import Pie from reportlab.graphics.charts.
if len (self.service) >0: servicefilter = chargebackservice.factory.create('serviceFilter') servicefilter.filterAttribute = attributefilter.SERVICE_NAME servicefilter.filterOperator = operatorfilter.EQUAL servicefilter.serviceFilterValue = self.service servicefilter.filterConnector = connectorfilter.AND filterCollection.append(servicefilter) if len(filterCollection) > 0: filterCollection[0].filterConnector = connectorfilter.
paging.pageIndex = PAGE_INDEX paging.pageSize = PAGE_SIZE filters = [] if self.filters : filters = self.filters.getFiltersObj(self.chargebackservice) if len(filters) > 0: print "[" + str(datetime.datetime.now()) + "]" + "getServiceUsagePage: start" result = self.chargebackservice.service.getServiceUsagePage(dataPeriod, paging, filters) print "[" + str(datetime.datetime.now()) + "]" + "getServiceUsagePage: end" else: result = self.chargebackservice.service.getServiceUsagePage(dataPeriod, paging) if result.
serviceData.append([ipAddress.ipAddress, ipAddress.ipAssignmentType, ipAddress.allocationHours, str(locale.currency(val=ipAddress.allocationCost, symbol=False, grouping=True))]) return len(ipAddresses.ipAddressUsageDetail) def get_servicetable(self, service): serviceinfotable = [[]] serviceinfotable[0] = ["Service", get_servicename(service)] serviceinfotable.append(["Organization", get_organization(service)]) serviceinfotable.append(["Billing code", get_billingcode(service)]) serviceinfotable.
usageReport.generate (self.format_data(), outputfile) class AggregateUsageReport (object): def __init__ (self, periodInformation, connection, filters=None, title="Title", footer="Footer"): self.title = title self.data = footer self.footer = "" self.period = periodInformation self.filters = filters self.chargebackservice = connection.client def drawpiechart(self, labels, data): pie_chart = Drawing(200, 200) pc = Pie() pc.width = 150 pc.height = 150 pc.data = data pc.labels = labels pc.simpleLabels = 1 pc.
Sample Python Client
Example 3 GUI.py import Tkinter from Tkinter import * import tkMessageBox import calendar as cd import datetime from root.chargeback.reports import * from root.chargeback.connection import * import locale AVAILABLE_REPORTS = [ ("Total Services Cost", 1), ("Services Metrics Details", 2), ("Cost Distribution by Resource Types", 3), ] class chargeback_app(Tkinter.Tk): def __init__(self,parent): Tkinter.Tk.__init__(self,parent) self.parent = parent self.initialize() def initialize (self): self.
self.org = Tkinter.Entry(self, textvariable=self.orgVariable ) self.org.grid(column=2,row=7, columnspan=3, sticky='EW') #Filters - billingcode billingcodelableText = Tkinter.StringVar() billingcodelableText.set(u"Billing Code: ") billingcodelable = Tkinter.Label(self, textvariable=billingcodelableText, anchor="w",fg="black",bg="white") billingcodelable.grid(column=1,row=8,sticky='EW') self.billingcodeVariable = Tkinter.StringVar() self.billingcode = Tkinter.Entry(self, textvariable=self.
reportPeriod = PeriodInformation(startDate=self.fromVariable.get(), endDate=self.toVariable.get()) print reportPeriod.end filters = Filters(organizationid=self.orgVariable.get(), billingcode=self.billingcodeVariable.get(), owner=self.ownerVariable.get(), service=self.servicenameVariable.get()) if self.reporttypeVariable.get() == 1: report = ServiceUsageReport (reportPeriod, chargebackService, filters, self.reporttitleVariable.get()) elif self.reporttypeVariable.
Example 4 reports_file.py from reportlab.platypus import * from reportlab.lib.styles import getSampleStyleSheet from reportlab.lib.units import inch class Report(object): def __init__(self, header, footer): styles = getSampleStyleSheet() self.headerStyle = styles["Heading1"] self.paraStyle = styles["Normal"] self.footerStyle = styles["Code"] self.header = self.header_format(header, self.headerStyle) self.footer = self.header_footer(footer, self.
15 Sample Chargeback Usage Report The whitepaper HP Matrix Operating Environment 7.1 Chargeback: Creating customized reports based on CLI output files demonstrates how to format chargeback CLI XML output for a better presentation in applications that are able to open XML files and process XSL transformations such as Microsoft Excel, Word, and Internet Explorer. This paper is available from www.hp.com/go/csdevelopers on the Whitepapers tab. Formatter files used in the whitepaper can be downloaded from www.
A References 122 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.
B Support and other resources Information to collect before contacting HP Be sure to have the following information available before you contact HP: • Software product name • Hardware product model number • Operating system type and version • Applicable error message • Third-party hardware or software • Technical support registration number (if applicable) How to contact HP Use the following methods to contact HP technical support: • In the United States, see the Customer Service / Contact HP U
The service also provides access to software updates and reference manuals in electronic form as they are made available from HP. Customers who purchase an electronic license are eligible for electronic updates. With this service, Insight Management software customers benefit from expedited problem resolution as well as proactive notification and delivery of software updates. For more information about this service, see the following website: http://www.hp.
http://www.hp.com/go/matrixoe/docs • HP Insight Management Support Matrix • HP Matrix Operating Environment Release Notes • HP Insight Management Installation and Configuration Guide Typographic conventions This document uses the following typographical conventions: Book title The title of a book. On the web, this can be a hyperlink to the book itself. Command A command name or command phrase, for example ls -a. Filename The name of a file or the path to a file location.
C Documentation feedback HP is committed to providing documentation that meets your needs. To help us improve the documentation, send any errors, suggestions, or comments to Documentation Feedback (docsfeedback@hp.com). Include the document title and part number, version number, or the URL when submitting your feedback.
