HP CloudSystem Matrix/Matrix Operating Environment 7.1 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 – 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 I Matrix API................................................................................................10 1 Introduction..........................................................................................11 Integration interface overview..............................................................................................12 New features in 7.1 Update 1..............................................................................................12 New features in 7.1..............
powerOffLogicalServers.................................................................................................27 powerOnLogicalServers.................................................................................................27 powerCycleLogicalServers..............................................................................................28 editLogicalServers.........................................................................................................28 removeLogicalServers..
setLoadBalancerPassword...............................................................................................40 unsetLoadBalancerPassword...........................................................................................41 LogicalLoadBalancer..........................................................................................................41 createLogicalLoadBalancerGroup....................................................................................
ImageTypeEnum.................................................................................................................53 IPAddressAssignmentType...................................................................................................53 IPAddressAssignmentTypeEnum............................................................................................53 IPType..............................................................................................................................
ServerPool........................................................................................................................65 ServerPoolResourceNote.....................................................................................................66 ServerResource..................................................................................................................66 ServerSnapshot............................................................................................................
7 Sample Java Client...............................................................................76 Sample Code....................................................................................................................76 8 Sample VisualStudio/.NET/C# Client.....................................................81 II Chargeback API.......................................................................................84 9 Introduction..................................................................
RequiredParameterException...............................................................................................95 14 Sample Python Client...........................................................................96 15 Sample Chargeback Usage Report......................................................107 A References.............................................................................................108 B Support and other resources.........................................................
Part I Matrix API
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 12) 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.
NOTE: The extensions in this section are not available in the v4 endpoint, which is included in Matrix OE 7.1.
• • • • ◦ editLogicalServers ◦ removeLogicalServers New CMS operations: ◦ quiesceCms ◦ unquiesceCms ◦ getCmsQuiesceStatus LoadBalancer operations: ◦ listLoadBalancers ◦ addLoadBalancer ◦ modifyLoadBalancer ◦ removeLoadBalancer ◦ addLoadBalancerCertificate ◦ removeLoadBalancerCertificate ◦ setLoadBalancerPassword ◦ unsetLoadBalancerPassword LogicalLoadBalancer operations: ◦ createLogicalLoadBalancerGroup ◦ deleteLogicalLoadBalancerGroup ◦ addLogicalLoadBalancerGroupMembe
◦ – maxMemorySize – maxProcessorCount 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/v5?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).
activateService Name activateService Activates 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 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. Returns String requestId Request ID for the operation.
powerOnService Name powerOnService Powers on 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 on. Returns String requestId Request ID for the operation.
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. Exceptions InvalidParameterException RequestNotFoundException IOSoapException getRequest Name getRequest Gets status and history information about a specified request.
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.
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. String The name of the logical server group to adjust.
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. The Raw Disk Mapping (RDM) type for the disk. Defaults to NONE. For physical disks only. Ignored for virtual disks. Returns String requestId Request ID for the operation.
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.
Software listSoftware Name listSoftware Gets a list of software available for deployment. This operation may be performed only by an infrastructure orchestration Administrator, organization Administrator, or Architect. Parameters none Returns List List of DeployableSoftware objects containing information about software software resources. Exceptions IOSoapException getSoftware Name getSoftware Gets information about a specified deployable software image.
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.
unassigned even if services in the organization were created from it. This operation may be performed only by a Service Provider Administrator. Parameters String templateName The template to be unassigned from an organization. String organizationName The ID or name of the organization from which to unassign the template. Returns none Exceptions InvalidParameterException TemplateNotFound Exception No template exists with given template name.
OrganizationNotFound Exception IOSoapException assignSubnetToOrganization Name assignSubnetToOrganization Assigns a subnet to an organization. A single subnet may be assigned to multiple organizations. It also remains in the Service Provider subnet set. The operation has no effect if the subnet is already assigned to the organization. This operation may be performed only by a Service Provider Administrator. Parameters String subnetId The subnet to be assigned to an organization.
Exceptions InvalidParameterException SoftwareNotFoundException No software exists with the given software ID. OrganizationNotFound Exception IOSoapException unassignSoftwareFromOrganization Name unassignSoftwareFrom Organization Unassigns software from an organization. The operation has no effect if the software is not assigned to the organization. Software may be unassigned even if services in the organization are using it. This operation may be performed only by a Service Provider Administrator.
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. Returns none Exceptions InvalidParameterException IOSoapException countRunningRequestsForCms Name CountRunningRequestsFor Counts the number of requests running on a CMS in maintenance mode.
Returns none Exceptions IOSoapException 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. The current quiesce state.
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.
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.
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. String address The IP address or host name of the member to be added to the load balancer group.
Exceptions FirewallRuleGroupNotFound Exception InvalidParameterException IOSoapException addRuleToFirewallRuleGroup Name addRuleToFirewallRule Group Add a rule to an existing firewall rule group in the inventory and in the underlying resource. Parameters String firewallRuleGroupId The ID of the firewall rule group in which to add a rule. FirewallRule firewallRule The firewall rule to be added.
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. A floating IP address should be removed explicitly when it is no longer needed. Parameters String serviceName The ID or name of the service containing the logical server.
String ipAddress The floating IP address to remove. Returns String requestId Request ID for the operation. Exceptions InvalidParameterException ServiceNotFoundException LogicalServerNotFound Exception IOSoapException releaseFloatingIPAddress Name releaseFloatingIPAddress Permanently releases a floating IP address that is not associated to a server. This operation may be performed only by an infrastructure orchestration Administrator.
ServiceNotFoundException LogicalServerNotFound Exception IOSoapException createServerSnapshot Name createServerSnapshot Creates a snapshot of the current state of a server, with Administrator approval. 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 create a snapshot. String snapshotName The name to assign to the new snapshot.
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. Boolean removeChildren Indicates whether to also delete the child snapshots of the specified snapshot, recursively. Defaults to false. Returns String requestId Exceptions InvalidParameterException Request ID for the operation.
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 48) 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.
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. Only applicable when the type is VM_TEMPLATE. DeploymentService String name Name of the deployment server.
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.
LogicalServerGroupInfo String serviceName Name of the service containing the logical server group. String name Name of the logical server group. Integer minServerCount Initial size of the logical server group on service creation. Integer maxServerCount Maximum size of the logical server group that may be achieved by adding servers. Integer activeServerCount The number of logical servers in the group with status UP.
Integer processorSpeedMHz Minimum processor speed required for the logical server, in MHz (physical servers only). ProcessorArchitecture processorArchitecture Processor architecture required for the logical server (physical servers only). ServiceEntityStatus status Status of operation/automation for the logical server. Cost cost Cost associated with the server resource. Long createEpoch Time at which the logical object was created, in milliseconds since the epoch.
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. MessageSeverityEnum Possible values: CRITICAL, MAJOR, MINOR, WARNING, NORMAL, INFORMATIONAL, OTHER NatEntry NatType type Specifies the NAT type. String ipAddress Public IP address assigned to this entry. String name DNS name assigned to this entry.
Organization String name Name of the organization. String id Unique identifier for the organization. The Service Provider organization ID is "SERVICEPROVIDER". PacketProtocol PacketProtocolEnum 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.
RequestDetails Extends RequestInfo List requestHistory Detail messages associated with the request. 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.
String createdByUser Name of the user that submitted the request (or on whose behalf the request was submitted). String organizationId Unique identifier for the organization to which the request belongs. RequestStatus RequestStatusEnum 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.
SanVolume String id Resource ID for the SAN volume. String name Volume name, for volumes managed by Storage Provisioning Manager (SPM). Long sizeMB Volume size, in megabytes. RaidLevel raidLevel RAID level of the volume. OperatingSystemType osType Operating system type with which the volume is to be used. StorageProvisioningType provisioningType List tags Storage tags assigned to the volume. String lunId LUN ID at which the volume is addressed.
UNKNOWN The state cannot be determined. OTHER A value other than above, possibly introduced by an extension in a subsequent release. SanVolumeTemplate String id Resource ID for the SAN volume template. String spmServerId ID of the SPM server from which the template was discovered. String name Template name. String description StorageProvisioningType provisioningType Long defaultSizeMB Default size of SAN volumes provisioned from the template, in megabytes.
ServerPoolResourceNote String serverResourceId ID of the server (VM host or compute server) to which the note applies. Long movedEpoch Time at which the server was moved to the server pool, in milliseconds since the epoch. String movedFromPoolName Name of the server pool from which the server was moved. This value is not available after the referenced server pool is deleted. String movedByUser Name of the user who initiated the server pool move.
ServiceActionTrigger ServiceActionTriggerEnum 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. ServiceActionTriggerEnum Possible values: SERVICE_BEGIN, SERVICE_END, OTHER ServiceDetails Extends ServiceInfo List serviceActions A list of automatically triggered actions defined for the service.
ServiceInfo String name Name of the service. String id Unique identifier for the service. ServiceEntityStatus status Status of operation/automation for the service. String basedOnTemplate Name of the template on which the service is based. Long createEpoch Time at which the service was created, in milliseconds since the epoch. Long lastModifiedEpoch (Required) Time at which the service was last modified, in milliseconds since the epoch.
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. StorageProvisioningTypeEnum Possible values: THICK, THIN, UNSPECIFIED, OTHER StorageType StorageTypeEnum 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.
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 across services. Integer dhcpAddressCount Number of DHCP addresses configured for allocation on this subnet.
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.
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.
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.v5; 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.http.HTTPConduit; org.apache.cxf.ws.security.
"MyBillingCode"); 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.
tcp.setDisableCNCheck(true); conduit.setTlsClientParameters(tcp); } /** * 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.
/** 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 16)) • Enter a service name (e.g., “IOService”) as the Namespace value • Add these namespaces: using System.Net; using System.Net.Security; using System.
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].InnerText = "password"; //save the timestamp token and the username token xmlDoc.
NOTE: The Timestamp and UsernameToken values are intentionally left blank here. They are set dynamically by the C# code. • Modify the wsa:To value inserted in the previous step to specify the target system IP address or hostname. • Compile and run.
Part II Chargeback API
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.
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 a Service Provider 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.
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.
orglable.grid(column=1,row=7,sticky='EW') self.orgVariable = Tkinter.StringVar() 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.
chargebackService = Connection(server=self.cmsVariable.get(), username=self.usernameVariable.get(), password=self.passwordVariable.get()) 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.
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 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: • See the Contact HP Worldwide website for contact options: htt
Warranty information HP will replace defective delivery media for a period of 90 days from the date of purchase. This warranty applies to all Insight Management software products. HP authorized resellers For the name of the nearest HP authorized reseller, see the following sources: • In the United States, see the HP U.S. service locator web site: http://www.hp.com/service_locator • In other locations, see the Contact HP worldwide web site: http://welcome.hp.com/country/us/en/wwcontact.
Related information Documentation and support The latest versions of manuals and white papers for HP Matrix Operating Environment and related products can be downloaded from the HP Web. Documents for Matrix Operating Environment software can be found at http://www.hp.com/go/matrixoe/docs. For more information about HP Matrix Operating Environment infrastructure orchestration and related products and solutions, visit the following HP websites: • HP Matrix Operating Environment website at http://www.hp.