Hyper Scale-Out Platform

Transcription

1 Hyper Scale-Out Platform MK-94HSP November 2016

2 2016 Hitachi, LTD. All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, or stored in a database or retrieval system for commercial purposes without the express written permission of Hitachi, Ltd., or Hitachi Data Systems Corporation (collectively, Hitachi ). Licensee may make copies of the Materials provided that any such copy is: (i) created as an essential step in utilization of the Software as licensed and is used in no other manner; or (ii) used for archival purposes. Licensee may not make any other copies of the Materials. "Materials" mean text, data, photographs, graphics, audio, video and documents. Hitachi reserves the right to make changes to this Material at any time without notice and assumes no responsibility for its use. The Materials contain the most current information available at the time of publication. Some of the features described in the Materials might not be currently available. Refer to the most recent product announcement for information about feature and product availability, or contact Hitachi Data Systems Corporation at Notice: Hitachi products and services can be ordered only under the terms and conditions of the applicable Hitachi agreements. The use of Hitachi products is governed by the terms of your agreements with Hitachi Data Systems Corporation. By using this software, you agree that you are responsible for: 1) Acquiring the relevant consents as may be required under local privacy laws or otherwise from authorized employees and other individuals to access relevant data; and 2) Verifying that data continues to be held, retrieved, deleted, or otherwise processed in accordance with relevant laws. Notice on Export Controls. The technical data and technology inherent in this Document may be subject to U.S. export control laws, including the U.S. Export Administration Act and its associated regulations, and may be subject to export or import regulations in other countries. Reader agrees to comply strictly with all such regulations and acknowledges that Reader has the responsibility to obtain licenses to export, re-export, or import the Document and any Compliant Products. Hitachi is a registered trademark of Hitachi, Ltd., in the United States and other countries. AIX, AS/400e, DB2, Domino, DS6000, DS8000, Enterprise Storage Server, eserver, FICON, FlashCopy, IBM, Lotus, MVS, OS/390, PowerPC, RS6000, S/390, System z9, System z10, Tivoli, z/os, z9, z10, z13, z/vm, and z/vse are registered trademarks or trademarks of International Business Machines Corporation. Active Directory, ActiveX, Bing, Excel, Hyper-V, Internet Explorer, the Internet Explorer logo, Microsoft, the Microsoft Corporate Logo, MS-DOS, Outlook, PowerPoint, SharePoint, Silverlight, SmartScreen, SQL Server, Visual Basic, Visual C++, Visual Studio, Windows, the Windows logo, Windows Azure, Windows PowerShell, Windows Server, the Windows start button, and Windows Vista are registered trademarks or trademarks of Microsoft Corporation. Microsoft product screen shots are reprinted with permission from Microsoft Corporation. All other trademarks, service marks, and company names in this document or web site are properties of their respective owners. EXPORT CONTROLS - Licensee will comply fully with all applicable export laws and regulations of the United States and other countries, and Licensee shall not export, or allow the export or re-export of, the Software, API, or Materials in violation of any such laws or regulations. By downloading or using the Software, API, or Materials, Licensee agrees to the foregoing and represents and warrants that Licensee is not located in, under the control of, or a national or resident of any embargoed or restricted country.

3 Contents Preface Intended audience Product version Release notes Syntax notation Conventions for storage capacity Accessing product documentation Getting help Comments ix x x x x xi xii xii xii Chapter 1: About the Hyper Scale-Out Platform management API 1 Resources you can manage 2 Identifying a resource 5 Supported HTTP methods 7 Input and output formats 9 HTTP response codes 10 Asynchronous management operations 12 Getting the status of an asynchronous job 12 Getting a list of job URLs 14 Getting the status of all jobs 15 Getting the list and status of spawned jobs 17 About security and authentication 19 API version support 19 Example scripts and VM templates 20 Chapter 2: Using the HSP cluster management API 23 clusters 24 Getting a list of cluster URLs 24 Contents iii

4 Getting the properties of a cluster 26 Getting the properties of all clusters 30 Getting the SMTP configuration properties 35 Editing the SMTP configuration properties 37 alert-conditions 40 Getting the list of alert conditions 42 event-logs 43 Getting the list of event logs 44 racks 46 Getting a list of rack URLs 46 Getting the properties of a rack 48 Getting the properties of all racks 50 Adding a rack 52 Editing the properties of a rack 54 Deleting a rack 56 nodes 57 Getting a list of node URLs 58 Getting the properties of a node 59 Getting the properties of all nodes 64 Editing the properties of a node 69 Putting a node in maintenance mode 73 Adding nodes to or removing nodes from a rack 75 Shutting down or rebooting a node 77 Deleting a node 79 ip-addresses 81 Getting a list of IP address URLs 82 Getting the properties of an IP address 83 Getting the properties of all IP addresses 85 Adding an IP address 87 Editing the properties of an IP address 90 Deleting an IP address 93 disks 94 Getting a list of disk URLs 96 Getting the properties of a disk 97 Getting the properties of all disks 100 Editing the properties of a disk 103 Deleting a disk 105 tenants 106 Getting a list of tenant URLs 107 iv Contents

5 Getting the properties of a tenant 108 Getting the properties of all tenants 112 Adding a tenant 116 Configuring LDAP 118 Step 1: Configuring authentication 119 Step 2: Configuring user mapping 120 Step 3: Configuring group mapping 122 Step 4: Apply settings 123 Getting the list and properties of directory server users 124 Getting the list and properties of directory server groups 124 Granting and revoking roles to LDAP enabled tenant groups 125 Editing the properties of a tenant 127 Deleting a tenant 128 roles 129 Editing the properties of a role 130 Getting the properties of all roles 131 Getting the properties of a role 133 Getting a list of role URLs 134 file-systems 135 Getting a list of file system URLs 136 Getting the properties of a file system 138 Getting the properties of all file systems 143 Adding a file system 148 Editing the properties of a file system 154 Enabling or disabling a file system 159 Checking and repairing a file system 161 Deleting a file system 163 shares 164 Getting a list of share URLs 164 Getting the properties of a share 166 Getting the properties of all shares 168 Adding a share 170 Editing the properties of a share 173 Getting the list of access rules for a share 175 Adding, editing, or deleting an access rule 178 Deleting a share 184 users 185 Getting a list of user account URLs 185 Getting the properties of a user account 187 Contents v

6 Getting the properties of all user accounts 190 Adding a user account 192 Granting and revoking roles to non-ldap enabled tenant users 195 Editing the properties of a user account 198 Deleting a user account 201 Chapter 3: Using the HSP VM management API 203 vm-templates 204 Getting a list of VM template URLs 205 Getting the properties of a VM template 206 Getting the properties of all VM templates 208 Adding a VM template 209 Cloning a VM template 212 Editing the properties of a VM template 214 Deleting a VM template 216 vm-sizes 217 Getting a list of VM size URLs 217 Getting the properties of a VM size 218 Getting the properties of all VM sizes 220 Adding a VM size 222 Editing the properties of a VM size 223 Deleting a VM size 225 vm-instance-groups 226 Getting a list of VM instance group URLs 226 Getting the properties of a VM instance group 227 Getting the properties of all VM instance groups 228 Adding a VM instance group 230 Deleting VM instances from a VM instance group 233 Adding VM instances to a VM instance group 235 Powering on the VM instances in a VM instance group 237 Shutting down the VM instances in a VM instance group 238 Getting a list of VM instances associated with a VM instance group 239 Editing the properties of a VM instance group 242 Deleting a VM instance group 244 vm-instances 245 Getting a list of VM instance URLs 246 Getting the properties of a VM instance 246 Getting the properties of all VM instances 249 Adding VM instances 252 vi Contents

7 Working with a VM instance in sandbox mode 254 Editing the properties of a VM instance 257 Rebooting a VM instance 258 Shutting down a VM instance 259 Powering on a VM instance 261 Migrating a VM instance 262 Deleting a VM instance 263 VM instance snapshots 264 Getting a list of the VM snapshots for an instance 264 Adding a VM snapshot 266 Editing a VM snapshot 267 Reverting a VM snapshot 269 Deleting a VM snapshot 270 Attaching a disk to a VM instance 271 Detaching a disk from a VM instance 272 vm-volumes 274 Getting a list of VM volume URLs 274 Getting the properties of a VM volume 275 Getting the properties of all VM volumes 277 Adding VM volumes 279 Editing the properties of a VM volume 280 Deleting a VM volume 281 Index 283 Contents vii

8 viii Contents

9 Preface This document provides the information you need to use the Hyper Scale- Out Platform (HSP) management API. This is a Representational State Transfer Protocol (REST) API that you can use to manage HSP resources and facilitate application development and integration with existing infrastructure applications like automatic provisioning and billing system systems. This Preface includes the following information: Intended audience Product version Release notes Syntax notation Conventions for storage capacity Accessing product documentation Getting help Comments Preface ix

10 Intended audience Intended audience This document is intended for those who want to use the supplied REST API to manage HSP resources and to integrate HSP management operations with existing infrastructure management systems and applications. To use the management API, you should be familiar with HSP concepts, terminology, and functionality. You should also have a basic understanding of web services and prerequisite knowledge of: JSON REST Programming language you will use for the application development or integration Product version This document applies to Hyper Scale-Out Platform release or later. Release notes Read the release notes before installing and using this product. They may contain requirements or restrictions that are not fully described in this document or updates or corrections to this document. Release notes are available on Hitachi Data Systems Support Connect: Syntax notation The table below describes the conventions used for the syntax of commands, expressions, URLs, and object names in this document. boldface italic Convention Description Indicates text in a user interface window or dialog box, such as menus, menu options, buttons, and labels. For example: On the Add Share dialog box, click OK. Indicates important new terms. x Preface

11 Conventions for storage capacity (Continued) Convention <monospace italic> in angle brackets monospace Description Indicates a variable, which is a placeholder for site- or installationspecific details that you need to provide. For example: Copy <source-file> <target-file> Indicates: The name of a directory, folder, or file. For example: The nodes.xml file Text that is displayed on the screen. For example: # cluster_initialize monospace bold <monospace italic> in angle brackets Indicates text you enter. For example: $ cluster_initialize Indicates a variable, which is a placeholder for site- or installationspecific details that you need to provide. For example: Copy <source-file> <target-file> [ ] square brackets Indicates optional values. For example: [ a b ] indicates that you can choose a, b, or nothing. { } curly braces Indicates required or expected values. For example: { a b } indicates that you must choose either a or b. vertical bar Indicates that you have a choice between two or more options or arguments. For example: [ a b ] indicates that you can choose a, b, or nothing. { a b } indicates that you must choose either a or b. [ ] Indicates optional values. For example: [ a b ] indicates that you can choose a, b, or nothing. ellipsis Indicates text that was removed to shorten the example output. Conventions for storage capacity Hyper Scale-Out Platform uses the International Electrotechnical Commission (IEC) binary definition for storage capacity units: Preface xi

12 Accessing product documentation Capacity unit Value 1 kibibyte (KiB) 1,024 (2 10 ) bytes 1 mebibyte (MiB) 1,024 2 (2 20 ) bytes 1 gibibyte (GiB) 1,024 3 (2 30 ) bytes 1 tebibyte (TiB) 1,024 4 (2 40 ) bytes 1 pebibyte (PiB) 1,024 5 (2 50 ) bytes 1 exbibyte (EiB) 1,024 6 (2 60 ) bytes Accessing product documentation Product documentation is available on Hitachi Data Systems Support Connect: Check this site for the most current documentation, including important updates that may have been made after the release of the product. Getting help Hitachi Data Systems Support Portal is the destination for technical support of products and solutions sold by Hitachi Data Systems. To contact technical support, log on to Hitachi Data Systems Support Connect for contact information: Hitachi Data Systems Community is a global online community for HDS customers, partners, independent software vendors, employees, and prospects. It is the destination to get answers, discover insights, and make connections. Join the conversation today! Go to community.hds.com, register, and complete your profile. Comments Please send us your comments on this document: hsp.documentation.comments@hds.com Include the document title and part number, including the revision (for example, -01), and refer to specific sections and paragraphs whenever possible. All comments become the property of Hitachi Data Systems. Thank you! xii Preface

13 1 About the Hyper Scale-Out Platform management API Hyper Scale-Out Platform (HSP)is an appliance solution that aggregates the storage from multiple homogenous servers into a single storage pool. Multiple thinly provisioned file systems are created on top of this storage pool, and client systems can access these file systems from any server in the storage pool using the NFS protocol. The management API is a REpresentational State Transfer (REST) interface to the administrative tasks available for managing an HSP cluster. This section covers: Resources you can manage Identifying a resource Supported HTTP methods Input and output formats HTTP response codes Asynchronous management operations Getting the status of an asynchronous job Getting a list of job URLs Getting the status of all jobs Getting the list and status of spawned jobs About security and authentication API version support Example scripts and VM templates Chapter 1: About the Hyper Scale-Out Platform management API 1

14 Resources you can manage Resources you can manage Each entity that you can manage independently in the HSP management API is referred to as a resource. The cluster API allows configuration and management access to the following HSP resources: HSP resource Clusters Nodes Description Clusters are the collection of nodes that are interconnected on two networks (one external and one internal) and have one or more underlying file systems that provide client file access through the NFS protocol. Nodes are the physical machines that provide collective storage for the cluster. Nodes are centrally managed and do not need to be individually configured for file sharing or access. Nodes: Manage the underlying disks Store files, provide access to those files using remote file access protocols, and balance client connections and storage capacity within a cluster Maintain the configuration and file system information for the cluster Control the local redundancy and migration of files within the cluster to maintain the data protection policy you set for your files Disks Racks Disks are the physical storage devices in a node. In the context of the HSP software, racks are a virtual organizational resource that you can define and organize in a way that makes sense for your installation. The configuration and management of this virtual resource is optional, but the software does exercise internal rack-aware file placement and rebalancing enhancements if you define racks and distribute the nodes across the racks. 2 Chapter 1: About the Hyper Scale-Out Platform management API

15 Resources you can manage (Continued) HSP resource IP Addresses Description A pool of external IP addresses are allocated to the cluster when you initially configured the cluster or can be added later to accommodate more storage. IP addresses can move or float from the assigned node to a different node if the assigned node goes down or is taken off line for any reason, so there is no loss of service to the clients. Clients can access the cluster using any one of the external IP addresses associated with any one of the nodes. File systems File systems are the namespaces within the HSP in which files are created and accessed. Each file exists in only one file system, but the files themselves can be stored on multiple disks and spread across multiple nodes. A file system is not limited by the underlying storage available on a single machine. File systems and file system-related resources are owned and managed by administrative entities called tenants (see File system shares Access rules Tenants Files systems are shared out using the NFSv3 protocol. Clients can only access files in a file system that is shared out. You can define and manage host-level access control rules for NFS shares. Administrative entity that own and manage file systems and file system-related resources, as well as virtual machine resources. While multiple tenants share the HSP hardware, storage, and software capabilities within a cluster, they do not share or see each other s data or virtual machine applications. A tenant typically corresponds to an organization such as a company or a division or department within a company. A tenant can also correspond to an individual person. Users Alert conditions Event logs In addition to the default HSP user account called "admin," you can add and maintain other user accounts. Alert conditions are issues or negative circumstances that may require customer support or administrative attention and/or corrective action. Alerts are automatically removed by the HSP software once the underlying issue that caused the alert condition is resolved. Event logs include all internal system generated messages (informational and notice activities, as well as alerts) and administrator-initiated activities that occur within the cluster. Chapter 1: About the Hyper Scale-Out Platform management API 3

16 Resources you can manage The virtual machine API allows configuration and management access to the following HSP resources: HSP resource Templates Sizes Instance groups Instances Snapshots Volumes Description Templates let you install and manage the images used by the virtual machines so that you can run analytic applications. Lets you customize and define the CPU and memory resources for a virtual machine instance. Instance groups let you manage a group of virtual machine instances running within the cluster. Instances are the running instances of virtual machines within the cluster. A VM snapshot is a point-in-time picture of the state of a running VM instance when the snapshot is taken. The snapshot preserves both the disk state and memory state of the VM instance. Volumes let you manage the local volume space for a virtual machine. 4 Chapter 1: About the Hyper Scale-Out Platform management API

17 Identifying a resource Identifying a resource URL specification This section describes various ways of identifying the HSP management API resources. To identify a specific resource that you want to manage, you use a URL. All URLs for the HSP have the following base or root URI: Where: <cluster-ip> is the virtual IP address or resolvable host name of the cluster hspapi is the base name of the collection of HSP APIs X is the version of the API For example: Depending on the management action you are performing, the base URI is then followed by a hierarchical path of: One of the resources defined in Resources you can manage. Followed by an optional resource identifier (if the target of a management action is to be performed on a particular resource) or the list directive (if the target of a management action is to obtain the complete collection of a resource and its properties). For example, the URL to perform a management operation on a particular file system would look something like: a b170df Or, the URL to perform retrieve a list of all the file systems and their properties would look something like: Chapter 1: About the Hyper Scale-Out Platform management API 5

18 Identifying a resource Name queries The HSP supports name queries. You can specify the name of the resource with the list directive to find uniquely named resources, for example: Or: Links to the supported resources Specifying the base URL (for example, gives you a list of links to the supported resources that you can manage: { "collection-links": [ " " " " " " " " " " " " " " " " " ], "current-version": "v2", "supported-versions": [ "v1", "v2" ] } See "Resources you can manage" on page 2 for an overview of these resources. 6 Chapter 1: About the Hyper Scale-Out Platform management API

19 Supported HTTP methods Supported HTTP methods HTTP defines a set of methods that define the actions that can be performed on a resource. The HSP management API supports the following HTTP methods: Method Description GET Retrieves information about an individual resource or retrieves a list of resources of a given type. GET is a synchronous operation. This means that each request completes and returns a response code that conveys the result of the operation. POST Adds or edits the properties of a resource. POST is also used to execute an action on a particular resource. When adding a resource, you need to provide values for any required properties of a resource that do not have default values. To override a default value, include the property and provide an override value for that property in the request body. When editing the properties of a resource, supply values only for the properties that you want to change. Properties that are not specified in the request body remain unchanged. POST is an asynchronous operation. When a POST request is submitted, you can only tell whether or not the submission was successful, but you cannot tell if the asynchronous operation was successful or when it has been completed, so you will need to check the job status. See "Getting the status of an asynchronous job" on page 12 for details about tracking the completion of a POST operation. Chapter 1: About the Hyper Scale-Out Platform management API 7

20 Supported HTTP methods (Continued) Method Description DELETE Deletes a resource. DELETE is an asynchronous operation. When a DELETE request is submitted, you can only tell whether or not the submission was successful, but you cannot tell if the asynchronous operation was successful or when it has been completed, so you will need to check the job status. See "Getting the status of an asynchronous job" on page 12 for details about tracking the completion of a DELETE operation. 8 Chapter 1: About the Hyper Scale-Out Platform management API

21 Input and output formats Input and output formats When you add or modify (POST) a resource through the HSP management API, you will use JSON to specify the resource properties. When you retrieve (GET) information about a resource, the response will also be returned as JSON. The HSP management API does not currently support XML. The HSP management API responses are not cached and expire immediately. The response header "expires" directive with a date in the past ("Thu, 01 Jan :00:00 GMT") is recognized by most browsers and proxies that the page should not be cached. All responses returned through the management API are UTF-8 encoded. All request bodies you create for input to the API must also be UTF-8 encoded. In a JSON request or response body: Properties are specified by name/value pairs that describe or define the resource. For the POST (add/edit) method, these name/value pairs are included in the body of the message. For example, the URL specification to create a file system called sales: POST with body properties of: "name": "sales", "enabled": true, "data-protection": "raid1_3instance_large_io", "quota": , "record-access-time": true, "description": "Sales organization data", "tags": "2014" ; (semicolon) is not a valid character within any string in a payload. A list of resources is represented by a comma-separated list of HTTP URL links containing the resource identifiers. For example, the response body for a request for the file systems might look like this: " 92e03cb3-03b bd8a-332ecbf802c9", Chapter 1: About the Hyper Scale-Out Platform management API 9

22 HTTP response codes " ca02e142-10c4-11e3-a b170df", " ca048a7e-10c4-11e3-a b170df" For an edit request (POST), specify only the properties that you want to change. If you specify an property without a value, you will blank out or empty any existing content for that property. If you are coding your programs/scripts in Python (as are the supplied example files), specify: string entries in quotes number entries without quotes boolean entries as either True or False (case sensitive) without quotes Note that JSON translates boolean inputs True or False to lower case (true or false) in its responses. Follow the syntax rules for the language you are using to write your programs/scripts. Important: Because resource names can be changed by any HSP user with administrative privileges, consider using variables rather than hard coding resource names in your scripts. Each resource had a unique, static identifier. If you need to address a fixed set of resources, we recommend that you use this unique identifier. HTTP response codes The HSP management API uses the following standard HTTP response codes to convey the results of the REST operations: Status code HTTP name Used for 200 OK Resource retrieved or deleted successfully. 201 Created Resource created successfully. 10 Chapter 1: About the Hyper Scale-Out Platform management API

23 HTTP response codes (Continued) Status code HTTP name Used for 202 Accepted/ Success Asynchronous operation successfully accepted for processing. The response includes URL to track the asynchronous job through completion. 400 Bad Request Missing or invalid request contents. 401 Unauthorized Invalid authentication/authorization credentials. 403 Forbidden This user is not allowed to perform this request. 404 Not Found Requested resource not found. 405 Method Not Allowed Requested HTTP verb not allowed on this resource. 409 Conflict Request conflicts with another request, or conflicts with the current state of the object. 500 Internal Server Error 503 Service Unavailable Internal error that may require assistance from support. Multitenancy server is not available. Wait for a few minutes and retry the operation. Chapter 1: About the Hyper Scale-Out Platform management API 11

24 Asynchronous management operations Asynchronous management operations Because of the multi-threaded and individual task queueing nature of the HSP technology, all POST and DELETE operations are performed asynchronously. Once an asynchronous management operation is successfully accepted for processing (status code of 202), the HSP software tracks that operation as a job. This section describes the various ways that you can track job status: Getting the status of an asynchronous job Getting a list of job URLs Getting the status of all jobs Getting the list and status of spawned jobs Getting the status of an asynchronous job HTTP request syntax Request Once an asynchronous job has been successfully submitted, you can use the URL included in the response to track the status of the job. GET Supply the URL link to the job for which you want the status. 12 Chapter 1: About the Hyper Scale-Out Platform management API

25 Asynchronous management operations Response In addition to the response header that provides the status code (200 if the request was successful), the job status request returns the following properties in the response: resource-name string Name of the resource upon which the POST or DELETE operation is being performed. resource-type string Type of resource upon which the POST or DELETE operation is being performed, for example a POST on a cluster. creation-timestamp number Job creation timestamp. completion-status string Completion status of the asynchronous operation: PROCESSING COMPLETE ERROR completion-details string Additional information about the completion status of the asynchronous operation. completion-substatus string Additional information about the completion status of the asynchronous operation: For the completion-substatus of COMPLETE: OK For the completion-substatus of PROCESSING: NOT_QUEUED QUEUED RUNNING For the completion-substatus of ERROR: RETRY FAIL INVALID UNKNOWN Chapter 1: About the Hyper Scale-Out Platform management API 13

26 Asynchronous management operations (Continued) resource-action string The action being performed: ADD EDIT DELETE EXECUTE percent-complete number Completion percentage of the asynchronous operation. resource-id string Resource identifier upon which the POST or DELETE operation is being performed. target-node-name string ID of the node targeted to run the job. target-node-id string ID of the node targeted to run the job. spawned-jobs boolean Whether or not additional jobs were spawned to accomplish the job. spawned-jobs-list-uri string List of URLs to additional jobs that were spawned to accomplish the task requested in this job. Getting a list of job URLs HTTP request syntax Request Response Using the GET HTTP method on the jobs resource retrieves a list of URL links to the jobs found. GET There are no request parameters needed for the GET request for jobs. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the jobs found. 14 Chapter 1: About the Hyper Scale-Out Platform management API

27 Asynchronous management operations Getting the status of all jobs HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the jobs resource retrieves the properties for all running jobs, as well as a number of recently run jobs up to approximately 60 jobs total. GET There are no request parameters needed for the list GET request. In addition to the response header and status code (200 if the request was successful), the request returns the properties described in Getting the status of an asynchronous jobfor all jobs in the response. resource-name string Name of the resource upon which the POST or DELETE operation is being performed. resource-type string Type of resource upon which the POST or DELETE operation is being performed, for example a POST on a cluster. creation-timestamp number Job creation timestamp. completion-status string Completion status of the asynchronous operation: PROCESSING COMPLETE ERROR completion-details string Additional information about the completion status of the asynchronous operation. Chapter 1: About the Hyper Scale-Out Platform management API 15

28 Asynchronous management operations (Continued) completion-substatus string Additional information about the completion status of the asynchronous operation: For the completion-substatus of COMPLETE: OK For the completion-substatus of PROCESSING: NOT_QUEUED QUEUED RUNNING For the completion-substatus of ERROR: RETRY FAIL INVALID UNKNOWN resource-action string The action being performed: ADD EDIT DELETE EXECUTE percent-complete number Completion percentage of the asynchronous operation. resource-id string Resource identifier upon which the POST or DELETE operation is being performed. target-node-name string ID of the node targeted to run the job. target-node-id string ID of the node targeted to run the job. spawned-jobs boolean Whether or not additional jobs were spawned to accomplish the job. spawned-jobs-list-uri string List of URLs to additional jobs that were spawned to accomplish the task requested in this job. 16 Chapter 1: About the Hyper Scale-Out Platform management API

29 Asynchronous management operations Getting the list and status of spawned jobs HTTP request syntax Request Response Additional jobs may be spawned to complete the task requested in the of the initial asynchronous job. You can use the URL included in the original job status in the spawned-jobs-list-uri property to track the status of any of spawned jobs. GET Supply the URL link to the job for which you want the status of the spawned jobs. In addition to the response header that provides the status code (200 if the request was successful), the job status request returns the following properties in the response: resource-name string Name of the resource upon which the POST or DELETE operation is being performed. resource-type string Type of resource upon which the POST or DELETE operation is being performed, for example a POST on a cluster. creation-timestamp number Job creation timestamp. completion-status string Completion status of the asynchronous operation: PROCESSING COMPLETE ERROR completion-details string Additional information about the completion status of the asynchronous operation. Chapter 1: About the Hyper Scale-Out Platform management API 17

30 Asynchronous management operations (Continued) completion-substatus string Additional information about the completion status of the asynchronous operation: For the completion-substatus of COMPLETE: OK For the completion-substatus of PROCESSING: NOT_QUEUED QUEUED RUNNING For the completion-substatus of ERROR: RETRY FAIL INVALID UNKNOWN resource-action string The action being performed: ADD EDIT DELETE EXECUTE percent-complete number Completion percentage of the asynchronous operation. resource-id string Resource identifier upon which the POST or DELETE operation is being performed. target-node-name string ID of the node targeted to run the job. target-node-id string ID of the node targeted to run the job. spawned-jobs boolean Whether or not additional jobs were spawned to accomplish the job. spawned-jobs-list-uri string List of URLs to additional jobs that were spawned to accomplish the task requested in this job. 18 Chapter 1: About the Hyper Scale-Out Platform management API

31 About security and authentication About security and authentication Each HSP request must be authenticated you must successfully prove your identity to HSP to make requests and get responses to those requests. Because HTTP is a stateless protocol, the server cannot remember authentication credentials (user name and password) and must be passed the credentials in each HTTP request. HSP authenticates requests using Basic HTTP authentication as follows: 1. A client makes an HTTP request to the server. 2. The server responds with a 401 error, requesting authentication and supplying the realm to which the client must authenticate. 3. The client retries the request with the authentication user name and password for the realm, encoded as a base 64 string in the request header. 4. The server checks the details and if the user name/password is correct, the request will succeed. If the user name/password is not correct, the server responds with another error. API version support Hyper Scale-Out Platform currently supports two versions of the API: v1 and v2. You can invoke a particular version of API by passing the desired version in the URL, for example: HSP processes the request if the URL specifies one of the supported versions (v1 or v2). If an supported version is specified, then an HTTP 400 Bad Request error is returned, for example: "RequestedHSP API versionv3 is not supported." The header for each response displays the API version, where X is the version number: X-HSPAPI-Version : vx Chapter 1: About the Hyper Scale-Out Platform management API 19

32 Example scripts and VM templates Example scripts and VM templates Python coding examples for the HSP management API are provided on any installed node and are accessible from the reference file system share in the following location: /examples/api The example scripts and their corresponding response output files are organized in a directory structure by resource: alert-conditions clusters disks event-logs file-systems ip-addresses nodes racks roles shares tenants users vm-instance-groups vm-instances vm-templates vm-sizes vm--volumes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. In addition to the example script directories, there is a file called Utilities.py. This is a utilities file that is imported into each one of the example scripts and defines utility methods to generate HMAC authentication headers for various request types. Utilities.py also defines a list of properties that contains values common to the scripts, for example the cluster-ip, cluster-name, node-name, and so on. To run the example scripts in your cluster, you need to change these cluster-specific values for your configuration. A read-only VM template file is included in the cirros_vm directory in the reference file system that is supplied only for the purpose of running the 20 Chapter 1: About the Hyper Scale-Out Platform management API

33 Example scripts and VM templates VM-related API examples. This template is not intended for other testing or production use. The script testing template is accessible on an installed node in the following location: /examples/vm_templates Chapter 1: About the Hyper Scale-Out Platform management API 21

34 22 Chapter 1: About the Hyper Scale-Out Platform management API

35 2 Using the HSP cluster management API The HSP management APIs are described by an HTTP request that defines the supported operations for each resource. This section describes the HSP management API for the following supported cluster resources: Cluster management: clusters Cluster alerts: alert-conditions Cluster events: event-logs Node management: nodes IP address management: ip-addresses Disk management: disks Rack creation and management: racks Multitenancy management: tenants and roles File system creation and management: file-systems File system share creation and management: shares User account creation and management: users Chapter 2: Using the HSP cluster management API 23

36 clusters clusters Clusters are organizational units that allow for connectivity and data segmentation within HSP. A cluster consists of a minimum of five nodes that are physical machines that provide collective storage for the cluster. The following management operations are supported for the clusters resource: Getting a list of cluster URLs Getting the properties of a cluster Getting the properties of all clusters Editing the properties of a cluster Getting the SMTP configuration properties Editing the SMTP configuration properties Getting a list of cluster URLs Using the GET HTTP method on the clusters resource retrieves a list of URL links to the clusters found. Note: In the current release, only managing a single cluster is supported, so only one URL is returned in the response. HTTP request syntax GET Request There are no request parameters needed for the GET request for clusters. 24 Chapter 2: Using the HSP cluster management API

37 clusters Response In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the clusters found. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/clusters Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 25

38 clusters Getting the properties of a cluster HTTP request syntax Request Response You can get the properties of a particular cluster by supplying the URL link to any cluster that was retrieved with the GET HTTP method on the clusters (see "Getting a list of cluster URLs" on page 24). GET Supply the URL link to the cluster for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the cluster. The cluster is configured at the factory with a default cell name of "MyCluster." You can, however, change the name of your cluster. See "Editing the properties of a cluster" on page 1 for details. virtual-ip string Virtual IP address that is specified when the cluster is initially configured. This is the IP address through which clients access file systems and administrators access the management interfaces within a cluster. There is only one virtual IP address associated with a cluster. run-state string Run state of the cluster: UP cluster is up and fully functional. DOWN cluster is offline. Client access to the cluster is interrupted. 26 Chapter 2: Using the HSP cluster management API

39 clusters (Continued) number Storage space usage high water mark percentage defined for the cluster. When the remaining cluster storage space usage reaches the high water mark percentage, an alert is raised until the storage space usage falls below the low water mark percentage. number By default, the storage space high water mark is set to 80. Storage space low water mark percentage defined for the cluster. By default, the storage space low water mark is set to 70. number Existing storage space usage alerts are automatically cleared once the low water mark percentage is achieved. The low water mark is typically 10 to 20 percent less than the high water mark. High water mark percentage set by default for a new file system added to a cluster. You can override this percentage at the file system level. When the remaining allocated file system space reaches the high water mark, an alert is raised until the file system space consumption falls below the low water mark percentage. storage-spacehwm storage-spacelwm file-systemspace-hwm file-systemspace-lwm number By default, file system space high water mark is set to 90. Low water mark percentage set by default for a new file system added to a cluster. Existing file system space alerts are automatically cleared once the low water mark setting is achieved. The low water mark is typically 10 to 20 percent less than the high water mark. By default, the file system space low water mark is set to 85. Chapter 2: Using the HSP cluster management API 27

40 clusters (Continued) file-systemauto-access total-storagecapacity total-storageused total-storageavailable total-filesystem-capacity total-filesystem-used total-filesystem-available boolean number number number number number number Whether or not the required share and access rule will be automatically created when a file system is added. By default, file-system-auto-access is set to true. When you add a file system, the HSP software adds a share with the same name as the file system and adds an access rule called "DefaultAccessRule" that provides read/write access to the share for all client hosts. You can add more restrictive access rules to the share, as well as edit or delete the automatically created "DefaultAccessRule." Total storage capacity of the cluster in bytes. Total storage capacity used in bytes. Total storage capacity available in bytes. Total file system capacity of the cluster in bytes. Total file system capacity used in bytes. Total file system capacity available in bytes. version string Lowest version of HSP software running on a node within the cluster. The first three period-separated numbers (for example, ) are the version number, and the digits after the last period following the version number are the build number. If you expect the version to be higher, it could be that one of your nodes was missed in a upgrade. hide-shares boolean Whether or not share visibility is restricted only to clients that have permission to access the share. By default, hide-shares is set to false. 28 Chapter 2: Using the HSP cluster management API

41 clusters (Continued) gateway string IP address of your network gateway. This is used by HSP to access external services (for example, NTP for time synchronization and SMTP for notification delivery). domain-name string Your company s valid domain name, for example: YourCompanyName.com dns-server string IP address of your DNS server. ntp-server string IP address or fully qualified host name of your NTP server. Network Time Protocol (NTP) is used to synchronize time on the nodes within a cluster. number This property provides support for a special HSP environment and should only be modified by or at the request of HDS support. smtp-config-uri uri Link to the cluster s SMTP configuration and its associated properties. An SMTP server and a valid SMTP configuration is needed to alert condition notifications to users. event-logs-uri uri Link to the cluster s event logs and their associated properties. --coremanagementgroup-targetsize alert-conditionsuri uri Link to the cluster s alert conditions and their associated properties. description string Description of the cluster. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/clusters Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 29

42 clusters Getting the properties of all clusters Supplying an additional list directive to the GET HTTP method on the clusters resource retrieves the properties for all clusters. Note: In the current release, only managing a single cluster is supported, so only one cluster and its properties will be returned in the response. HTTP request syntax Request Response GET There are no request parameters needed for the list GET request. In addition to the response header and status code (200 if the request was successful), the request returns the following properties for all clusters in the response: name string Name of the cluster. The cluster is configured at the factory with a default cell name of "MyCluster." You can, however, change the name of your cluster. See "Editing the properties of a cluster" on page 1 for details. virtual-ip string Virtual IP address that is specified when the cluster is initially configured. This is the IP address through which clients access file systems and administrators access the management interfaces within a cluster. There is only one virtual IP address associated with a cluster. run-state string Run state of the cluster: UP cluster is up and fully functional. DOWN cluster is offline. Client access to the cluster is interrupted. 30 Chapter 2: Using the HSP cluster management API

43 clusters (Continued) number Storage space usage high water mark percentage defined for the cluster. When the remaining cluster storage space usage reaches the high water mark percentage, an alert is raised until the storage space usage falls below the low water mark percentage. number By default, the storage space high water mark is set to 80. Storage space low water mark percentage defined for the cluster. By default, the storage space low water mark is set to 70. number Existing storage space usage alerts are automatically cleared once the low water mark percentage is achieved. The low water mark is typically 10 to 20 percent less than the high water mark. High water mark percentage set by default for a new file system added to a cluster. You can override this percentage at the file system level. When the remaining allocated file system space reaches the high water mark, an alert is raised until the file system space consumption falls below the low water mark percentage. storage-spacehwm storage-spacelwm file-systemspace-hwm file-systemspace-lwm number By default, file system space high water mark is set to 90. Low water mark percentage set by default for a new file system added to a cluster. Existing file system space alerts are automatically cleared once the low water mark setting is achieved. The low water mark is typically 10 to 20 percent less than the high water mark. By default, the file system space low water mark is set to 85. Chapter 2: Using the HSP cluster management API 31

44 clusters (Continued) file-systemauto-access total-storagecapacity total-storageused total-storageavailable total-filesystem-capacity total-filesystem-used total-filesystem-available boolean number number number number number number Whether or not the required share and access rule will be automatically created when a file system is added. By default, file-system-auto-access is set to true. When you add a file system, the HSP software adds a share with the same name as the file system and adds an access rule called "DefaultAccessRule" that provides read/write access to the share for all client hosts. You can add more restrictive access rules to the share, as well as edit or delete the automatically created "DefaultAccessRule." Total storage capacity of the cluster in bytes. Total storage capacity used in bytes. Total storage capacity available in bytes. Total file system capacity of the cluster in bytes. Total file system capacity used in bytes. Total file system capacity available in bytes. version string Lowest version of HSP software running on a node within the cluster. The first three period-separated numbers (for example, ) are the version number, and the digits after the last period following the version number are the build number. If you expect the version to be higher, it could be that one of your nodes was missed in a upgrade. hide-shares boolean Whether or not share visibility is restricted only to clients that have permission to access the share. By default, hide-shares is set to false. 32 Chapter 2: Using the HSP cluster management API

45 clusters (Continued) gateway string IP address of your network gateway. This is used by HSP to access external services (for example, NTP for time synchronization and SMTP for notification delivery). domain-name string Your company s valid domain name, for example: YourCompanyName.com dns-server string IP address of your DNS server. ntp-server string IP address or fully qualified host name of your NTP server. Network Time Protocol (NTP) is used to synchronize time on the nodes within a cluster. number This property provides support for a special HSP environment and should only be modified by or at the request of HDS support. smtp-config-uri uri Link to the cluster s SMTP configuration and its associated properties. An SMTP server and a valid SMTP configuration is needed to alert condition notifications to users. event-logs-uri uri Link to the cluster s event logs and their associated properties. --coremanagementgroup-targetsize alert-conditionsuri uri Link to the cluster s alert conditions and their associated properties. description string Description of the cluster. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/clusters Chapter 2: Using the HSP cluster management API 33

46 clusters Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 34 Chapter 2: Using the HSP cluster management API

47 clusters Getting the SMTP configuration properties HTTP request syntax Request Response A valid SMTP configuration is required for an HSP user to receive notifications of alert conditions. You can get the list of SMTP configuration properties by supplying the URL link returned for the smtp-config-uri property that was retrieved with the GET HTTP method on a cluster ID (see "Getting the properties of a cluster" on page 26). GET smtp-config Supply the URL link specified in the smtp-config-uri for the cluster for which you want the SMTP configuration properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the SMTP configuration. By default, the name of the existing SMTP configuration is "SMTPConfig," but you can change the name. enabled boolean Whether or not the SMTP configuration is enabled. By default, the initial default SMTP configuration is disabled because the SMTP configuration requires editing for your environment. smtpserver smtpserverport string number IP address or fully qualified host name of the SMTP server. The outgoing SMTP server port. The default port for a non-ssl configuration is 25. The default port for an SSL configuration is 465. Chapter 2: Using the HSP cluster management API 35

48 clusters (Continued) displayname address securityenabled username string string boolean string The from display name associated with sent alert messages. The from address associated with sent alert messages. Whether or not the client should use Secure Socket Layer (SSL) based security when sending . By default, security-enabled is set to false. User name that is passed to the service provider for authentication. password string Password that is passed to the service provider for authentication. description string Description of the SMTP configuration. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/clusters Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 36 Chapter 2: Using the HSP cluster management API

49 clusters Editing the SMTP configuration properties A valid SMTP configuration is required for an HSP user to receive notifications of alert conditions. The HSP software comes with a predefined, but disabled SMTP configuration called "SMTPConfig." You need to edit this configuration, specify your site-specific details, and then enable the configuration to get alert notification working properly. Note: You cannot delete "SMTPConfig" or add another SMTP configuration you can only edit the existing configuration. HTTP request syntax Request For more information on setting up user subscriptions to receive notifications for alert conditions, see "Editing the properties of a user account" on page 198. POST edit-smtp-config The <cluster-id> is the ID of the cluster for which you want to edit the SMTP configuration properties and is supplied in the URL. In addition, the action that you want to take (edit-smtp-config) is also specified in the URL. The edit-smtp-config action is repeated in the request body, along with the required and optional properties and their corresponding values: name string Name of the SMTP configuration. By default, the name of the existing SMTP configuration is "SMTPConfig," but you can change the name. SMTP configuration names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). Chapter 2: Using the HSP cluster management API 37

50 clusters (Continued) enabled boolean Whether or not the SMTP configuration is enabled. By default, the initial default SMTP configuration is disabled because the SMTP configuration requires editing for your environment. When you enable the SMTP configuration, you must provide the required SMTP server and address properties. (required) (required) string number string string boolean IP address or fully qualified host name of the SMTP server. For example: "smtp.mailserver.com" If specified as an IP address, use IPv4 notation, for example: The outgoing SMTP server port. The default port for a non-ssl configuration is 25. The default port for an SSL configuration is 465. The from display name associated with sent alert messages. For example: "admin." Display names can be from 1 to 255 characters and can contain any UTF-8 characters except ; (semicolon). The from address associated with sent alert messages. For example: "WestCoastCluster@hds.com" Unicode characters are supported. Whether or not the client should use Secure Socket Layer (SSL) based security when sending . By default, security-enabled is set to false. smtpserver smtpserverport displayname address securityenabled username string If you use SSL, you must provide a user name and password that will be passed to the service provider for authentication. User name that is passed to the service provider for authentication. Required if security-enabled is set to true is. 38 Chapter 2: Using the HSP cluster management API

51 clusters (Continued) password string Password that is passed to the service provider for authentication. Required if security-enabled is set to true is. Passwords can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). description string Description of the SMTP configuration. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). For example, the body of the request would be specified as: { "edit-smtp-config": { "name": "string", "enabled": true, "smtp-server": "string", "smtp-server-port": 25, "display-name": "string", " -address": "string", "security-enabled": true, "user-name": "string", "password": "string", "description": "string", "tags": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. Chapter 2: Using the HSP cluster management API 39

52 alert-conditions The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/clusters Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. alert-conditions Alert conditions are issues or negative circumstances that may require customer support or administrative attention and/or corrective action. Alerts are automatically removed by the HSP software once the underlying issue that caused the alert condition is resolved. The following summarizes the alert conditions that are raised for the various HSP resources: Cluster Warning severity alert conditions are raised when the administrator-defined high and low watermark thresholds for the storage space of the cluster are out of the specified range. Node Warning severity alert conditions are raised when the run state property of a node is DOWN, the node has been put in maintenance mode, or memory consumption may cause the node to be rebooted. Error severity alert condition is raised when the run state property of a node is ERROR. Disk Error severity alert condition is raised when the run state property of a disk is ERROR. IP address Warning severity alert condition is raised when the run state property of an IP address is DOWN. File system Warning severity alert conditions are raised when the administrator-defined high and low watermark thresholds for file system space are out of the specified range. Warning severity alert condition is 40 Chapter 2: Using the HSP cluster management API

53 alert-conditions raised when the run state property of a file system is IMPAIRED. Error severity alert condition is raised when the run state property of a file system is ERROR. Alert conditions are also raised when a node s power supply, fan speed, and CPU temperature sensors detect the following: Power supplies Warning severity alert condition is raised when a power supply cord on a node has been unplugged. Error severity alert condition is raised when a power supply has failed. Sensors Warning severity alert conditions are raised when the thresholds that have been set for them have been exceeded. To send notifications to HSP administrators about alert conditions, you need: A valid SMTP configuration. Review and edit the SMTP configuration. See "Editing the SMTP configuration properties" on page 37 for more information. To configure alert condition notifications within a HSP user account. See "Editing the properties of a user account" on page 1 for more information about subscribing to critical, error, or warning alert conditions. Cleared alerts are archived in the system_archive file system share. The most recently cleared 150 (approximate) alerts are maintained in this archive. Important: To access archived alert conditions, you must create hostbased access rules that are appropriate for your environment for the system_archive. By default, system_archive is not accessible. See "Adding, editing, or deleting an access rule" on page 178 for details. The following management operations are supported for the alertconditions resource: Getting the list of alert conditions Chapter 2: Using the HSP cluster management API 41

54 alert-conditions Getting the list of alert conditions You can get the list of cluster alert conditions by supplying the URL link returned for the alert-conditions property that was retrieved with the GET HTTP method on a cluster ID (see "Getting the properties of a cluster" on page 26). Cleared alerts are archived in the system_archive file system share. The most recently cleared 150 (approximate) alerts are maintained in this archive. Important: By default and for security reasons, system_access is not accessible. To access archived alert conditions, you must create host-based access rules that are appropriate for the system_archive. HTTP request syntax Request Response GET alertconditions Supply the URL link specified in the alert-conditions-u for the cluster for which you want the list of alert conditions. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the alert condition. severity string Severity of the alert condition warning, error or critical. resource-name string Name of the resource to which the alert condition is associated. resource-type string Type of the resource to which the alert condition is associated. time-raised string Date and time that the alert condition was raised. 42 Chapter 2: Using the HSP cluster management API

55 event-logs (Continued) resolution string Description describing the administrative action that should be considered to correct or clear the alert condition. resource-id string ID of the resource to which the alert condition is associated. description string Description of the alert condition. tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/alert-conditions Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. event-logs Event logs include all internal system generated messages (informational and notice activities, as well as alerts) and administrator-initiated activities that occur within the cluster. The HSP software maintains about 10,000 event logs. Older event logs are archived in the system_archive file system. Event logs that are associated with alert conditions are not archived until the system clears those alert conditions. Important: To access archived alert conditions, you must create hostbased access rules that are appropriate for your environment for the system_archive. By default, system_archive is not accessible. See "Adding, editing, or deleting an access rule" on page 178 for details. Chapter 2: Using the HSP cluster management API 43

56 event-logs The following management operations are supported for the event-log resource: Getting the list of event logs Getting the list of event logs You can get the list of cluster event logs by supplying the URL link returned for the event-logs property that was retrieved with the GET HTTP method on a cluster ID (see "Getting the properties of a cluster" on page 26). The HSP software maintains about 10,000 event logs. Older event logs are archived in the system_archive file system share. Event logs that are associated with alert conditions are not archived until the system clears those alert conditions. Important: For security reasons, system_access is not accessible by default. To access archived event logs, you must create host-based access rules that are appropriate for your environment for the system_archive. See "Adding, editing, or deleting an access rule" on page 178 for details. HTTP request syntax Request Response GET event-logs Supply the URL link specified in the event-logs-uri for the cluster for which you want the list of event logs. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the event log. 44 Chapter 2: Using the HSP cluster management API

57 event-logs (Continued) severity string Severity of the event info, debug, critical, error, or warning. resource-name string Name of the resource to which the event log is associated. resource-type string Type of the resource to which the event log is associated. timestamp string Date and time that the event occurred. resource-id string ID of the resource to which the event log is associated. description string Description of the event log. tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/event-logs Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 45

58 racks racks Racks are the physical hardware resource that house the nodes in a cluster. Multi-rack systems are recommended, as each rack has its own power and network connectivity, which provides physical redundancy in the case of node or power supply failure. In the context of the HSP software, racks are a virtual organizational resource that you can define and organize in a way that makes sense for your installation. Defining this virtual resource is optional, but does exercise internal rack-aware placement and rebalancing enhancements if you do define racks and distribute the nodes across the racks. Note: You need to add racks before you can successfully list or get the properties of racks. The following management operations are supported for the racks resource: Getting a list of rack URLs Getting the properties of a rack Getting the properties of all racks Adding a rack Editing the properties of a rack Deleting a rack Getting a list of rack URLs HTTP request syntax Using the GET HTTP method on the racks resource retrieves a list of URL links to the racks found. GET 46 Chapter 2: Using the HSP cluster management API

59 racks Request There are no request parameters needed for the GET request for racks. Response In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the racks found. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/racks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 47

60 racks Getting the properties of a rack HTTP request syntax Request Response You can get the properties of a particular rack by supplying the URL link to any rack that was retrieved with the GET HTTP method on the racks (see "Getting a list of rack URLs" on page 46). GET Supply the URL link to the rack for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the rack. location string User-defined string defining the location of the rack. node-list-uri string Link to the list of nodes located on the rack. cluster-name string Name of the cluster to which the rack is associated. cluster-id string ID of the cluster to which the rack is associated. description string Description of the rack. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/racks 48 Chapter 2: Using the HSP cluster management API

61 racks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 49

62 racks Getting the properties of all racks HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the racks resource retrieves the properties for all racks. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties for all racks in the response: name string Name of the rack. location string User-defined string defining the location of the rack. node-list-uri string Link to the list of nodes located on the rack. cluster-name string Name of the cluster to which the rack is associated. cluster-id string ID of the cluster to which the rack is associated. description string Description of the rack. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/racks 50 Chapter 2: Using the HSP cluster management API

63 racks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 51

64 racks Adding a rack HTTP request syntax Request To exercise internal rack-aware placement and rebalancing enhancements, you need to take action to add racks these are not automatically created. After you add racks, you need to distribute the nodes across the racks. See "Adding nodes to or removing nodes from a rack" on page 75 for more information. POST Specify the properties for the rack: name (required) string Name of the rack. Supply either a name for the rack or enter "autogenerate." The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. Rack names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). location string User-defined string defining the location of the rack. Location can be up to 255 characters except ; (semicolon). description string Description of the rack. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). 52 Chapter 2: Using the HSP cluster management API

65 racks Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/racks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 53

66 racks Editing the properties of a rack HTTP request syntax Request You can edit the properties of an existing rack. POST The <rack-id> is the ID of the rack on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: name string Name of the rack. Rack names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). location string User-defined string defining the location of the rack. Location can be up to 255 characters except ; (semicolon). description string Description of the rack. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. 54 Chapter 2: Using the HSP cluster management API

67 racks The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/racks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 55

68 racks Deleting a rack HTTP request syntax Request Response Example Deleting a rack is removing the rack from the HSP software s control and the rack is no longer available for use inside the cluster. You cannot delete a rack without first removing the nodes from the rack. DELETE The <rack-id> is the ID of the rack that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/racks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 56 Chapter 2: Using the HSP cluster management API

69 nodes nodes Nodes are the physical machines that provide collective storage for the cluster. A node: Owns the underlying storage disks Stores files and provides access to those files using the NFS protocol Stores file metadata and cluster configuration information Nodes plugged into the internal network that have the have HSP software installed are automatically discovered and added to the cluster. The software checks to make sure that the software version of the node being added, matches the version of the cluster and takes the appropriate upgrade or downgrade action to ensure software compatibility. When new nodes are added, the HSP software automatically rebalances space utilization across all the nodes in the cluster by migrating files from more loaded nodes to the newly added nodes. This process takes time to complete and the new storage is not immediately available. Rebalancing is carefully controlled to minimize the file serving impact, but there is some service interruption. Important: We recommend that you add nodes in batches, rather than one at a time, and during off-peak file access time. The following management operations are supported for the nodes resource: Getting a list of node URLs Getting the properties of a node Getting the properties of all nodes Editing the properties of a node Putting a node in maintenance mode Adding nodes to or removing nodes from a rack Shutting down or rebooting a node Chapter 2: Using the HSP cluster management API 57

70 nodes Deleting a node Getting a list of node URLs HTTP request syntax Request Response Example Using the GET HTTP method on the nodes resource retrieves a list of URL links to the nodes found. GET There are no request parameters needed for the GET request for nodes. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the nodes found. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/nodes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 58 Chapter 2: Using the HSP cluster management API

71 nodes Getting the properties of a node HTTP request syntax You can get the properties of a particular node by supplying the URL link to any node that was retrieved with the GET HTTP method on the nodes (see "Getting a list of node URLs" on the previous page). GET Request Response Supply the URL link to the node for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the node. Nodes are initially configured by the software with default node names of Node001, Node002, Node003, and so on. You can rename a node at any time. Chapter 2: Using the HSP cluster management API 59

72 nodes (Continued) run-state string Run state of the node: UP node is up and fully functional. DOWN node is offline, but no errors were detected. When a node is DOWN, its disks are also marked as DOWN. An administrator might have shut down or rebooted or disabled the node.impaired Some services on the node are not available, the system may be attempting a recovery. A warning severity alert is raised. If a node remains DOWN for more than 10 minutes and is not in maintenance mode, you should ensure that the power cord and network cables have not been disturbed and that the node is powered on. Call support if the node remains DOWN. ERROR An unrecoverable node failure has been detected. Customer support intervention is required. An error severity alert is raised. enabled boolean Whether or not the node is enabled. identify boolean Whether or not a light on the physical node is blinking for identification. By default, identify is set to false. maintenance-mode boolean Whether or not the node is in maintenance mode. By default, maintenance-mode is set to false. version string Lowest version of HSP software running on a node within the cluster. The first three period-separated numbers (for example, 1.2.2) are the version number, and the digits after the last period following the version number are the build number. If you expect the version to be higher, it could be that one of your nodes was missed in a upgrade. rack-name string Name of the rack to which the node is associated. serial-number string Serial number associated with the physical disk. 60 Chapter 2: Using the HSP cluster management API

73 nodes (Continued) external-nic string Network interface used for the external network (eth0). max-guestvm-memcapacity max-guestvm-cpucores number number Amount of memory the node has to support VM provisioning. Number of CPU cores that can be used by VMs on the node. internal-networks-uri uri Links to the internal network interfaces and their properties: ip-address string containing the IP address associated with each internal network interface nic string defining each internal network interface ( eth2 and eth3 ) Chapter 2: Using the HSP cluster management API 61

74 nodes (Continued) sensors-uri uri Links to the node s power supply, fan speed, and CPU temperature sensors and their associated properties: name string containing the name of the sensor type string defining the type of sensor, like Power Supply, Fan Speed, CPU Temperature, and Temperature value current value of the hardware component being monitored as reported by the sensor. For power supplies, a sensor value of 1 indicates health, -1 indicates the power cord is unplugged, and 0 indicates failure. units unit of measure for that value, like RPM status current status of the hardware component being monitored as reported by the sensor, like NOMINAL, WARNING, CRITICAL, NON-RECOVERABLE thresholds monitoring thresholds for the hardware component, like LOWER-NON- CRITICAL, UPPER-NON-CRITICAL, LOWER- CRITICAL, UPPER-CRITICAL, LOWER-NON- RECOVERABLE, UPPER-NON-RECOVERABLE A warning severity alert is raised when a sensor status reports anything other than NOMINAL or a power supply on a node has been unplugged. An error severity alert is raised when a power supply on a node has failed. cluster-name string Name of the cluster to which the node is associated. cluster-id string ID of the cluster to which the node is associated. rack-id string ID of the rack to which the node is associated. core-managementgroup-member boolean This property should only be modified by or at the specific request of HDS support. description string Description of the node. tags string User-defined tags that can be used to organize and/or filter the response results. 62 Chapter 2: Using the HSP cluster management API

75 nodes Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/nodes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 63

76 nodes Getting the properties of all nodes HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the nodes resource retrieves the properties for all nodes. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties for all nodes in the response: name string Name of the node. Nodes are initially configured by the software with default node names of Node001, Node002, Node003, and so on. You can rename a node at any time. 64 Chapter 2: Using the HSP cluster management API

77 nodes (Continued) run-state string Run state of the node: UP node is up and fully functional. DOWN node is offline, but no errors were detected. When a node is DOWN, its disks are also marked as DOWN. An administrator might have shut down or rebooted or disabled the node.impaired Some services on the node are not available, the system may be attempting a recovery. A warning severity alert is raised. If a node remains DOWN for more than 10 minutes and is not in maintenance mode, you should ensure that the power cord and network cables have not been disturbed and that the node is powered on. Call support if the node remains DOWN. ERROR An unrecoverable node failure has been detected. Customer support intervention is required. An error severity alert is raised. enabled boolean Whether or not the node is enabled. identify boolean Whether or not a light on the physical node is blinking for identification. By default, identify is set to false. maintenance-mode boolean Whether or not the node is in maintenance mode. By default, maintenance-mode is set to false. version string Lowest version of HSP software running on a node within the cluster. The first three period-separated numbers (for example, 1.2.2) are the version number, and the digits after the last period following the version number are the build number. If you expect the version to be higher, it could be that one of your nodes was missed in a upgrade. rack-name string Name of the rack to which the node is associated. serial-number string Serial number associated with the physical disk. Chapter 2: Using the HSP cluster management API 65

78 nodes (Continued) external-nic string Network interface used for the external network (eth0). number number Amount of memory the node has to support VM provisioning. Number of CPU cores that can be used by VMs on the node. internal-networks-uri uri Links to the internal network interfaces and their properties: ip-address string containing the IP address associated with each internal network interface nic string defining each internal network interface ( eth2 and eth3 ) 66 Chapter 2: Using the HSP cluster management API

79 nodes (Continued) sensors-uri uri Links to the node s power supply, fan speed, and CPU temperature sensors and their associated properties: name string containing the name of the sensor type string defining the type of sensor, like Power Supply, Fan Speed, CPU Temperature, and Temperature value current value of the hardware component being monitored as reported by the sensor. For power supplies, a sensor value of 1 indicates health, -1 indicates the power cord is unplugged, and 0 indicates failure. units unit of measure for that value, like RPM status current status of the hardware component being monitored as reported by the sensor, like NOMINAL, WARNING, CRITICAL, NON-RECOVERABLE thresholds monitoring thresholds for the hardware component, like LOWER-NON- CRITICAL, UPPER-NON-CRITICAL, LOWER- CRITICAL, UPPER-CRITICAL, LOWER-NON- RECOVERABLE, UPPER-NON-RECOVERABLE A warning severity alert is raised when a sensor status reports anything other than NOMINAL or a power supply on a node has been unplugged. An error severity alert is raised when a power supply on a node has failed. cluster-name string Name of the cluster to which the node is associated. cluster-id string ID of the cluster to which the node is associated. rack-id string ID of the rack to which the node is associated. core-managementgroup-member boolean This property should only be modified by or at the specific request of HDS support. description string Description of the node. tags string User-defined tags that can be used to organize and/or filter the response results. Chapter 2: Using the HSP cluster management API 67

80 nodes Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/nodes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 68 Chapter 2: Using the HSP cluster management API

81 nodes Editing the properties of a node HTTP request syntax Request Many properties of a node cannot be edited. Identify and maintenance mode are important node properties with which you should familiarize yourself. This section describes the identify property and you can refer to "Putting a node in maintenance mode" on page 73 for more detailed information about maintenance mode. POST The <node-id> is the ID of the node on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: name string Name of the node. Nodes are initially configured by the software with default node names of Node001, Node002, Node003, and so on. You can rename a node at any time. Follow the RFC 1123 host name guidelines if you want to rename your nodes. Generally, node names can be from 1 to 255 characters and can only contain: letters A-Z and a-z digits 0-9 hyphens (-) enabled boolean Whether or not the node is enabled. Chapter 2: Using the HSP cluster management API 69

82 nodes (Continued) identify boolean Whether or not a light on the physical node is blinking for identification. By default, identify is set to false. If you set identify to true, the light will continue to blink on the disk until you change identify back to false. maintenance-mode boolean Whether or not the node is in maintenance mode. By default, maintenance-mode is set to false. max-guestvm-memcapacity max-guestvm-cpucores number number Amount of memory the node has to support VM provisioning. Number of CPU cores that can be used by VMs on the node. 70 Chapter 2: Using the HSP cluster management API

83 nodes (Continued) sensors-uri uri Links to the node s power supply, fan speed, and CPU temperature sensors and their associated properties: name string containing the name of the sensor description string Description of the node. type string defining the type of sensor, like Power Supply, Fan Speed, CPU Temperature, and Temperature value current value of the hardware component being monitored as reported by the sensor. For power supplies, a sensor value of 1 indicates health, -1 indicates the power cord is unplugged, and 0 indicates failure. units unit of measure for that value, like RPM status current status of the hardware component being monitored as reported by the sensor, like NOMINAL, WARNING, CRITICAL, NON-RECOVERABLE thresholds monitoring thresholds for the hardware component, like LOWER-NON- CRITICAL, UPPER-NON-CRITICAL, LOWER- CRITICAL, UPPER-CRITICAL, LOWER-NON- RECOVERABLE, UPPER-NON-RECOVERABLE A warning severity alert is raised when a sensor status reports anything other than NOMINAL or a power supply on a node has been unplugged. An error severity alert is raised when a power supply on a node has failed. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Chapter 2: Using the HSP cluster management API 71

84 nodes Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/nodes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 72 Chapter 2: Using the HSP cluster management API

85 nodes Putting a node in maintenance mode Use maintenance mode to perform planned, temporary maintenance on a node. When a node is in maintenance mode, the software is not performing automatic rebalancing or file copy and migration activities to bring file protection in compliance with the data protection policy set, which means data is at risk. The longer time a node is in maintenance mode, the greater the chance of data loss. Therefore, placing a node in maintenance mode will raise an alert that will not go away until the node is taken out of maintenance mode. A node that is put in maintenance mode can subsequently be shut down or rebooted without triggering the storage subsystem to initiate data rebalancing (unlike disabling a node, which does trigger rebalancing). Also, if something happens to delay a node being brought back online or has a catastrophic failure, an administrator needs to be able to take a node that is DOWN out of maintenance mode so that rebalancing and file protection activities are resumed. Important: A minimum of five nodes is required for the cluster to function properly and ensure high availability. Therefore, you cannot put a node in maintenance mode if doing so would leave less than five nodes up and running. HTTP request syntax Request POST The <node-id> is the ID of the node that you want to put in maintenance mode and is supplied in the URL. Specify the maintenance-mode property: maintenance-mode boolean Whether or not the node is in maintenance mode. By default, maintenance-mode is set to False. Chapter 2: Using the HSP cluster management API 73

86 nodes Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/nodes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 74 Chapter 2: Using the HSP cluster management API

87 nodes Adding nodes to or removing nodes from a rack If you define the virtual rack resource in your installation and distribute the nodes across those racks, the HSP software performs rack-aware data placement and rebalancing. Nodes are not assigned to a rack until you take action to add racks and then add nodes to those racks. A node cannot be assigned to more than one rack. If you want to move a node to a different rack, you will need to remove the node from one rack and add it to another rack. Note: You must add racks before you can add nodes to the racks. See "Adding a rack" on page 52 for more information. HTTP request syntax Request POST add-to-rack Or: POST remove-from-rack The <node-id> is the ID of the node that you want to add to or remove from a rack and is supplied in the URL. In addition, the action that you want to take (add-to-rack or remove-from-rack) is also specified in the URL. The add-to-rack action is repeated in the request body, along with the required properties and its corresponding value for the add-to-rack action: rack-id string Specify the rack ID to which you want to add the node. Chapter 2: Using the HSP cluster management API 75

88 nodes For example, the body of the request would be specified as: { "add-to-rack": { "rack-id": "string" } } The remove-from-rack action is repeated in the request body without any additional properties. For example, the body of the request would be specified as: { "remove-from-rack": {} } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/nodes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 76 Chapter 2: Using the HSP cluster management API

89 nodes Shutting down or rebooting a node If you shut down a node, you will need to physically power back on the node to bring the node back online. Important: A minimum of five nodes is required for the cluster to function properly and ensure high availability. Therefore, you cannot shut down a node if doing so would leave less than five nodes up and running. Rebooting (stopping and starting) a node does not require physically powering back on the node. If possible, use less disruptive actions than shutdown and reboot. To ensure that the required number of instances specified by the data protection policy is maintained when a node is shut down, the HSP software automatically begins copying files onto other nodes. When the node is brought back online, any additional instances over the data protection policy specification will be removed over time. Both shutting down and rebooting a node can trigger rebalancing if the node does not come back online within the defined wait period, which by default is 10 minutes. Note: When a node is shut down or rebooted, the HSP software also attempts to shut down any VM templates that are deployed/running on the node. HTTP request syntax If a client tries to access a file on a file system that whose data protection policy is not currently compliant and the only copy of that file resides on the disabled node, the client will not be able to access the file until the node is again enabled or additional copies of the file are available on other nodes. POST shutdown Or: POST reboot Chapter 2: Using the HSP cluster management API 77

90 nodes Request The <node-id> is the ID of the node on which you want to perform one of the node actions and is supplied in the URL. In addition, the action that you want to take (shutdown or reboot) is also specified in the URL. The shutdown or reboot action is repeated in the request body without any additional properties. For example, the body of the request would be specified as: Or: { "shutdown": {} } { "reboot": {} } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/nodes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 78 Chapter 2: Using the HSP cluster management API

91 nodes Deleting a node You might need to retire or replace a node in your cluster. Deleting a node removes the node from the HSP software s control. When you delete a node, the HSP software can detect if the number of file instances maintained in the cluster is now insufficient and not in compliance with what has been specified by the administrator for the file system data protection policy. The software automatically performs any file copy and migration activities needed to bring the file protection in compliance with the policy set before the deletion is complete. Node deletion reformats all of the node s underlying disks to ensure any residual data is removed, so this also can take some time to complete. Important: Do not manually power off a node that is being deleted. The HSP software will automatically power off the node when reformatting operations are completed. HTTP request syntax Request Response If the node is not accessible (has a run state of ERROR), you will need to contact support for assistance in deleting the node from your cluster configuration. Deletion is an online operation that does not interrupt client file access services, assuming there are multiple instances of the file on other nodes in the cluster. DELETE The <node-id> is the ID node that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. Chapter 2: Using the HSP cluster management API 79

92 nodes The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/nodes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 80 Chapter 2: Using the HSP cluster management API

93 ip-addresses ip-addresses In addition to the virtual IP address that is associated with the cluster itself, external IP addresses from your public network are used by clients to access the data within the cluster. These IP addresses are specified as a range or pool when you initially configure your cluster network, and are then automatically and randomly assigned to each node in the cluster. IP addresses can move or float from the assigned node to a different node if the assigned node goes down or is taken off line for any reason, so there is no loss of service to the clients. Clients can access the cluster using any one of IP addresses associated with any one of the nodes. When directed to do so, IP addresses in the pool can also be assigned to VM instances. See Chapter 3: "Using the HSP VM management API" on page 203 for more information. Important: You should maintain at least as many IP address as there are nodes in the cluster twice the number of IP addresses per node is recommended. Make sure you do not assign IP addresses to an HSP cluster that are already in use within your network. The following management operations are supported for the ip-addresses resource: Getting a list of IP address URLs Getting the properties of an IP address Getting the properties of all IP addresses Adding an IP address Editing the properties of an IP address Deleting an IP address Chapter 2: Using the HSP cluster management API 81

94 ip-addresses Getting a list of IP address URLs HTTP request syntax Request Response Example Using the GET HTTP method on the ip-addresses resource retrieves a list of URL links to the IP addresses found. GET There are no request parameters needed for the GET request for ip-addresses. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the IP addresses found. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/ip-addresses Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 82 Chapter 2: Using the HSP cluster management API

95 ip-addresses Getting the properties of an IP address HTTP request syntax Request You can get the properties of a particular IP address by supplying the URL link to any IP address that was retrieved with the GET HTTP method on the ip-addresses (see Getting a list of IP address URLs). GET Supply the URL link to the IP address for which you want the list of properties. IP Address Type Select either: One IP Address IP Address Range name string Name of the IP address. run-state string Run state of the IP address: UP IP address is configured and ready to be used for client connections. DOWN IP address cannot be used for client connections because it is not configured or there is an internal issue with the IP that is not allowing its use. Make sure there are no other devices on the network using this IP address. enabled boolean Whether or not the IP address is enabled. By default, the IP address is enabled. ip-address string A valid external IP address that was allocated to the cluster when initially configured or that was added later to accommodate more storage/client connections. Chapter 2: Using the HSP cluster management API 83

96 ip-addresses (Continued) role string Role assigned to the IP address in the configuration: cluster virtual IP address assigned to the cluster. node floating IP address assigned to nodes in the storage pool. vm IP address assigned to each of the virtual machine instances in the virtual machine pool. By default, role is set to node. bound-to string Displays the name of the node, virtual machine, or cluster that the IP address is currently assigned to by the HSP software. cluster-name string Name of the cluster to which the IP address is associated. cluster-id string ID of the cluster to which the IP address is associated. description string Description of the IP address. tags string User-defined tags that can be used to organize and/or filter the response results. Response In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/ip-addresses Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 84 Chapter 2: Using the HSP cluster management API

97 ip-addresses Getting the properties of all IP addresses HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the ip-addresses resource retrieves the properties for all clusters. GET There are no request parameters needed for the list GET request. In addition to the response header and status code (200 if the request was successful), the request returns the following properties for all IP addresses in the response: IP Address Type Select either: One IP Address IP Address Range name string Name of the IP address. run-state string Run state of the IP address: UP IP address is configured and ready to be used for client connections. DOWN IP address cannot be used for client connections because it is not configured or there is an internal issue with the IP that is not allowing its use. Make sure there are no other devices on the network using this IP address. enabled boolean Whether or not the IP address is enabled. By default, the IP address is enabled. Chapter 2: Using the HSP cluster management API 85

98 ip-addresses (Continued) ip-address string A valid external IP address that was allocated to the cluster when initially configured or that was added later to accommodate more storage/client connections. role string Role assigned to the IP address in the configuration: cluster virtual IP address assigned to the cluster. node floating IP address assigned to nodes in the storage pool. vm IP address assigned to each of the virtual machine instances in the virtual machine pool. By default, role is set to node. bound-to string Displays the name of the node, virtual machine, or cluster that the IP address is currently assigned to by the HSP software. cluster-name string Name of the cluster to which the IP address is associated. cluster-id string ID of the cluster to which the IP address is associated. description string Description of the IP address. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/ip-addresses Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 86 Chapter 2: Using the HSP cluster management API

99 ip-addresses Adding an IP address HTTP request syntax Request You can add IP addresses to the pool of floating IP addresses used for virtual machine instances and client connections to the cluster at any time. We recommend that you maintain at least as many IP address as there are nodes in the cluster for client connections twice the number of IP addresses as there are nodes is recommended. In you are going to run analytic applications in virtual machines on the cluster, you need to decide if you are going to allocate a pool of HSP managed IP addresses for the VM instances or you are going to use IP addresses managed from some external source (for example, DHCP). Even if you are going to manage IP addresses outside the cluster, you will need to create at least one virtual machine IP address so that you can run the a VM instance in sandbox mode and set up the address management. See "Working with a VM instance in sandbox mode" on page 254. If you do not specify a role, the IP address is assigned the role of node by default. POST Specify the properties for the IP address: IP Address Type Select either: One IP Address IP Address Range Chapter 2: Using the HSP cluster management API 87

100 ip-addresses (Continued) name (required) string Name of the IP address. Supply either a name for the IP address or enter "auto-generate." The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. IP address names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). enabled boolean Whether or not the IP address is enabled. By default, the IP address is enabled. Specify either true or false (case sensitive). ip-address (required) string A valid external IP address that was allocated to the cluster when initially configured or that was added later to accommodate more storage/client connections. IP addresses are specified in IPv4 CIDR notation, for example: /24. role string Role assigned to the IP address in the configuration: cluster virtual IP address assigned to the cluster. node floating IP address assigned to nodes in the storage pool. vm IP address assigned to each of the virtual machine instances in the virtual machine pool. By default, role is set to node. description string Description of the IP address. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). 88 Chapter 2: Using the HSP cluster management API

101 ip-addresses Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/ip-addresses Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 89

102 ip-addresses Editing the properties of an IP address You can edit some properties of an existing IP address resource. Important: You cannot edit the role of an IP address in the cluster. If you need to repurpose or change the role of an IP address, you will need to delete the IP address and then add it back specifying the new role you want the IP address to have. HTTP request syntax Request POST The <ip-address-id> is the ID of the IP address on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: IP Address Type Select either: One IP Address IP Address Range name string Name of the IP address. IP address names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). enabled boolean Whether or not the IP address is enabled. By default, the IP address is enabled. Specify either true or false (case sensitive). 90 Chapter 2: Using the HSP cluster management API

103 ip-addresses (Continued) ip-address string A valid external IP address that was allocated to the cluster when initially configured or that was added later to accommodate more storage/client connections. IP addresses are specified in IPv4 CIDR notation, for example: /24. role string Role assigned to the IP address in the configuration: cluster virtual IP address assigned to the cluster. node floating IP address assigned to nodes in the storage pool. vm IP address assigned to each of the virtual machine instances in the virtual machine pool. By default, role is set to node. description string Description of the IP address. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Chapter 2: Using the HSP cluster management API 91

104 ip-addresses Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/ip-addresses Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 92 Chapter 2: Using the HSP cluster management API

105 ip-addresses Deleting an IP address Deleting an IP address is removing the IP address from the HSP software s control and the IP address is no longer available for use inside the cluster. Important: You cannot delete the cluster's virtual IP address. HTTP request syntax Request Response Example DELETE The <ip-address> is the name of the IP address that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/ip-addresses Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 93

106 disks disks The management operations that you can perform for disks are very similar to those of nodes listing, editing, and deleting. Disk operations happen in greater isolation at a lower level, however, and therefore do not disrupt other disk or node operations. Node and disks shipped in your HSP appliance are automatically discovered. When you expand your storage capacity, additional nodes and disks are also automatically discovered. Note: Because system disks are not available for storage use, these disks not included in the list of disks and their capacity is not included in any of the storage space calculations. Adding disks to or replacing disks in a node are online operations that do not require any service disruption to clients accessing the cluster. These actions do, however, initiate internal cluster rebalancing (when adding disks) and recovery (when replacing disks). Because of these significant internal activities and their impact on cluster performance, the HSP software performs disk discovery activities only once per hour, so you will not see immediate storage capacity changes when you add or replace disks. Important: Do not remove disks without purpose! Disks should be removed only because of problems or failures. Any disk that is removed from an HSP node is treated as a failed disk. The HSP software tracks the serial numbers of any disk that has a run state of ERROR and/or has been physically removed from a node, and does not allow that disk to rejoin the cluster if it is reinserted. Trying to reuse failed or unreliable disks puts data at risk. If you need to perform short-term maintenance operations on multiple disks, consider putting a node in maintenance mode. For more information, see "Putting a node in maintenance mode" on page 73. Important: For performance reasons, disk space statistics are reported at set intervals, rather than dynamically. You may, therefore, see a slight lag between what is displayed for size and use statistics in HSP and what a more dynamic command like df shows. The following management operations are supported for the disks resource: 94 Chapter 2: Using the HSP cluster management API

107 disks Getting a list of disk URLs Getting the properties of a disk Getting the properties of all disks Editing the properties of a disk Deleting a disk Chapter 2: Using the HSP cluster management API 95

108 disks Getting a list of disk URLs HTTP request syntax Request Response Example Using the GET HTTP method on the disks resource retrieves a list of URL links to the disks found. GET There are no request parameters needed for the GET request for disks. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the disks found. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/disks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 96 Chapter 2: Using the HSP cluster management API

109 disks Getting the properties of a disk HTTP request syntax Request Response You can get the properties of a particular disk by supplying the URL link to any disk that was retrieved with the GET HTTP method on the disks (see "Getting a list of disk URLs" on the previous page). GET Supply the URL link to the disk for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the disk. Disk names are automatically assigned when they are discovered by the HSP software and are a combination of the node name and slot number. Chapter 2: Using the HSP cluster management API 97

110 disks (Continued) run-state string Run state of the disk: UP Disk is mounted and fully functional. DOWN Disk is usable, but not currently in use. When a node is DOWN, its disks are also marked as DOWN. An administrator might have rebooted the node, disabled the disk, the disk is new and has not yet been added, or the system is coming online and the disk has not been mounted yet. If a disk on node that is UP and not in maintenance mode remains down for more than 10 minutes, the disk is marked in ERROR. ERROR Disk is unusable due to unrecoverable errors. Customer support intervention is required to replace the disk. An error severity alert is raised. The only thing you can do with a disk that is in ERROR is to delete it. role string Role assigned to the disk in the configuration: cluster disk assigned for use in the cluster. vm disk assigned for dedicate space for a virtual machine instance. By default, role is set to cluster. identify boolean Whether or not a light on the physical disk is blinking for identification. By default, identify is set to false. used-capacity number Number of used bytes on the disk. capacity number Capacity of the disk, in bytes. serial-number string Serial number associated with the physical disk. system-path string Identification and location information for a disk. device-name string System mount point for the disk. node-name string Name of the node to which the disk is associated. 98 Chapter 2: Using the HSP cluster management API

111 disks (Continued) node-id string ID of the node to which the disk is associated. description string Description of the disk. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/disks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 99

112 disks Getting the properties of all disks HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the disks resource retrieves the properties for all disks. GET There are no request parameters needed for the list GET request. In addition to the response header and status code (200 if the request was successful), the request returns the following properties for all disks in the response: name string Name of the disk. Disk names are automatically assigned when they are discovered by the HSP software and are a combination of the node name and slot number. 100 Chapter 2: Using the HSP cluster management API

113 disks (Continued) run-state string Run state of the disk: UP Disk is mounted and fully functional. DOWN Disk is usable, but not currently in use. When a node is DOWN, its disks are also marked as DOWN. An administrator might have rebooted the node, disabled the disk, the disk is new and has not yet been added, or the system is coming online and the disk has not been mounted yet. If a disk on node that is UP and not in maintenance mode remains down for more than 10 minutes, the disk is marked in ERROR. ERROR Disk is unusable due to unrecoverable errors. Customer support intervention is required to replace the disk. An error severity alert is raised. The only thing you can do with a disk that is in ERROR is to delete it. role string Role assigned to the disk in the configuration: cluster disk assigned for use in the cluster. vm disk assigned for dedicate space for a virtual machine instance. By default, role is set to cluster. identify boolean Whether or not a light on the physical disk is blinking for identification. By default, identify is set to false. used-capacity number Number of used bytes on the disk. capacity number Capacity of the disk, in bytes. serial-number string Serial number associated with the physical disk. system-path string Identification and location information for a disk. device-name string System mount point for the disk. node-name string Name of the node to which the disk is associated. Chapter 2: Using the HSP cluster management API 101

114 disks (Continued) node-id string ID of the node to which the disk is associated. description string Description of the disk. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/disks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 102 Chapter 2: Using the HSP cluster management API

115 disks Editing the properties of a disk HTTP request syntax Request You can edit the description and tags properties of a disk, as well as blink a light on the disk for identification. In the current release, you cannot edit disk names. Disk names are a combination of the node name and slot number and are automatically assigned when the disks are discovered by the HSP software. POST The <disk-id> is the ID of the disk on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: role string Role assigned to the disk in the configuration: cluster disk assigned for use in the cluster. vm disk assigned for dedicate space for a virtual machine instance. By default, role is set to cluster. identify boolean Whether or not a light on the physical disk is blinking for identification. By default, identify is set to false. description string Description of the disk. If you set identify to true, the light will continue to blink on the disk until you change identify back to false. Free-flowing text, allowing up to 255 characters except ; (semicolon). Chapter 2: Using the HSP cluster management API 103

116 disks (Continued) tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job". Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/disks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 104 Chapter 2: Using the HSP cluster management API

117 disks Deleting a disk Deleting a disk is removing the disk from the HSP software s control and the disk is no longer available for use inside the cluster. Note: The HSP software tracks the serial numbers of any disk that has a run state of ERROR and/or has been removed from a node, and does not allow that disk to rejoin the cluster if it is reinserted. Trying to reuse failed or unreliable disks puts data at risk. HTTP request syntax Request Response When you remove a failed disk (run state ERROR) and replace it with a new disk in the same slot, the HSP software automatically deletes the failed disk from the internal HSP disk serial number tracking you do not need to take any additional management action to delete the disk. When you delete a disk or the disk fails (run state ERROR), the HSP software detects if the number of file instances maintained in the cluster is now insufficient and not in compliance with what has been specified by the administrator for the file system data protection policy. The software automatically performs any file copy and migration activities needed to bring the file protection in compliance with the policy set before the deletion is complete. In addition, the software runs mkfs on the disk. Disk deletion is an online operation that does not interrupt client file access services, assuming there is more than one instance of the files being deleted in the cluster. DELETE The <disk-id> is the ID of the disk that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. Chapter 2: Using the HSP cluster management API 105

118 tenants The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/disks Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. tenants Tenants own and manage file systems and file system-related resources, as well as virtual machine resources. While multiple tenants share the HSP hardware, storage, and software capabilities within a cluster, they do not share or see each other's data or virtual machine applications. Defining a tenant resource is not required if you simply want to manage HSP cluster resources as a single entity with shared data. Multitenancyrelated fields will be present in certain --json outputs (for example tenantname and tenant-id), but these fields will be empty. The first step in implementing multitenancy in an HSP cluster, is to create one or more tenants. A tenant typically corresponds to an organization such as a company or a division or department within a company. A tenant can also correspond to an individual person. A cluster administrator creates tenants and the HSP software automatically creates an administrative user account "tenant-name*admin" for each tenant when that tenant is created. Tenant administrators have management access to the following tenant resources it manages: 106 Chapter 2: Using the HSP cluster management API

119 tenants alert condition event logs file systems shares roles users VM templates VM instance groups VM instances The cluster administrator is a privileged user and also has access to all tenant resources and can perform all management operations. See "users" on page 185 for more information specific to creating tenant users and the roles and privileges that can be assigned them. The following management operations are supported for the tenants resource: Getting a list of tenant URLs Getting the properties of a tenant Getting the properties of all tenants Adding a tenant Configuring LDAP Granting and revoking roles to LDAP enabled tenant groups Editing the properties of a tenant Deleting a tenant Getting a list of tenant URLs Using the GET HTTP method on the tenants resource retrieves a list of URL links to the tenants found. Chapter 2: Using the HSP cluster management API 107

120 tenants HTTP request syntax Request Response Example GET There are no request parameters needed for the GET request for tenants. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the tenants found. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/tenants Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of a tenant HTTP request syntax You can get the properties of a particular tenant by supplying the URL link to any tenant that was retrieved with the GET HTTP method on the tenants (see "Getting a list of tenant URLs" on the previous page). GET Request Supply the URL link to the tenant for which you want the list of properties. 108 Chapter 2: Using the HSP cluster management API

121 tenants Response In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the tenant. enabled boolean Whether or not the tenant is enabled. By default, the tenant is enabled. ldap-enabled boolean Whether or not the tenant is LDAP enabled. By default, the tenant is not LDAP enabled. number High water mark percentage set by default for a new file system added to a cluster. You can override this percentage at the file system level. When the remaining allocated file system space reaches the high water mark, an alert is raised until the file system space consumption falls below the low water mark percentage. file-system-spacehwm file-system-spacelwm number By default, file system space high water mark is set to 90. Low water mark percentage set by default for a new file system added to a cluster. Existing file system space alerts are automatically cleared once the low water mark setting is achieved. The low water mark is typically 10 to 20 percent less than the high water mark. By default, the file system space low water mark is set to 85. cluster-name string Name of the cluster to which the tenant is associated. cluster-id string ID of the cluster to which the tenant is associated. description string Description of the tenant. tags string User-defined tags that can be used to organize and/or filter the response results. Chapter 2: Using the HSP cluster management API 109

122 tenants (Continued) ldap-configuration-uri uri Link to the LDAP configuration properties. user-list-uri uri When LDAP is enabled and configured, displays links to the directory server users and their associated properties. group-list-uri uri When LDAP is enabled and configured, displays links to the directory server groups and their associated properties. 110 Chapter 2: Using the HSP cluster management API

123 tenants (Continued) ldap-configuration string Displays the LDAP configuration properties if ldapenabled is true, the LDAP configuration has been completed, and there is connection to the LDAP server: ldap-url URL for connecting to the LDAP server. bind-user User DN for the LDAP bind operation. bind-password Password for the bind operation. user-tree-dn Search base for users. user-object-class LDAP objectclass for users. user-id LDAP attribute mapped to user ID. WARNING: Cannot be a multivalued attribute. user-name LDAP attribute mapped to user name. user-password LDAP attribute mapped to password. user- LDAP attribute mapped to user . user-enabled LDAP attribute mapped to user enabled flag. enabled-default Default value to enable users. This should match an appropriate int value if the LDAP server uses non-boolean (bitmask) values to indicate if a user is enabled or disabled. If this is not set to "True" the typical value is "512". This is typically used when "user_enabled_ attribute = useraccountcontrol". Chapter 2: Using the HSP cluster management API 111

124 tenants (Continued) enabled-mask Bitmask integer to indicate the bit that the enabled value is stored in if the LDAP server represents "enabled" as a bit on an integer rather than a boolean. A value of "0" indicates the mask is not used. If this is not set to "0" the typical value is "2". This is typically used when "user_enabled_attribute = useraccountcontrol". group-tree-dn Search base for groups. group-object-class LDAP objectclass for groups. group-id LDAP attribute mapped to group ID. group-name LDAP attribute mapped to group name. group-member LDAP attribute mapped to show group membership. group-description LDAP attribute mapped to group description. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/tenants Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of all tenants HTTP request syntax Supplying an additional list directive to the GET HTTP method on the tenants resource retrieves the properties for all tenants. GET Chapter 2: Using the HSP cluster management API

125 tenants Request There are no request parameters needed for the list GET request. Response In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the tenant. enabled boolean Whether or not the tenant is enabled. By default, the tenant is enabled. ldap-enabled boolean Whether or not the tenant is LDAP enabled. By default, the tenant is not LDAP enabled. number High water mark percentage set by default for a new file system added to a cluster. You can override this percentage at the file system level. When the remaining allocated file system space reaches the high water mark, an alert is raised until the file system space consumption falls below the low water mark percentage. file-system-spacehwm file-system-spacelwm number By default, file system space high water mark is set to 90. Low water mark percentage set by default for a new file system added to a cluster. Existing file system space alerts are automatically cleared once the low water mark setting is achieved. The low water mark is typically 10 to 20 percent less than the high water mark. By default, the file system space low water mark is set to 85. cluster-name string Name of the cluster to which the tenant is associated. cluster-id string ID of the cluster to which the tenant is associated. Chapter 2: Using the HSP cluster management API 113

126 tenants (Continued) description string Description of the tenant. tags string User-defined tags that can be used to organize and/or filter the response results. ldap-configuration-uri uri Link to the LDAP configuration properties. user-list-uri uri When LDAP is enabled and configured, displays links to the directory server users and their associated properties. group-list-uri uri When LDAP is enabled and configured, displays links to the directory server groups and their associated properties. 114 Chapter 2: Using the HSP cluster management API

127 tenants (Continued) ldap-configuration string Displays the LDAP configuration properties if ldapenabled is true, the LDAP configuration has been completed, and there is connection to the LDAP server: ldap-url URL for connecting to the LDAP server. bind-user User DN for the LDAP bind operation. bind-password Password for the bind operation. user-tree-dn Search base for users. user-object-class LDAP objectclass for users. user-id LDAP attribute mapped to user ID. WARNING: Cannot be a multivalued attribute. user-name LDAP attribute mapped to user name. user-password LDAP attribute mapped to password. user- LDAP attribute mapped to user . user-enabled LDAP attribute mapped to user enabled flag. enabled-default Default value to enable users. This should match an appropriate int value if the LDAP server uses non-boolean (bitmask) values to indicate if a user is enabled or disabled. If this is not set to "True" the typical value is "512". This is typically used when "user_enabled_ attribute = useraccountcontrol". Chapter 2: Using the HSP cluster management API 115

128 tenants (Continued) enabled-mask Bitmask integer to indicate the bit that the enabled value is stored in if the LDAP server represents "enabled" as a bit on an integer rather than a boolean. A value of "0" indicates the mask is not used. If this is not set to "0" the typical value is "2". This is typically used when "user_enabled_attribute = useraccountcontrol". group-tree-dn Search base for groups. group-object-class LDAP objectclass for groups. group-id LDAP attribute mapped to group ID. group-name LDAP attribute mapped to group name. group-member LDAP attribute mapped to show group membership. group-description LDAP attribute mapped to group description. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/tenants Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Adding a tenant HSP cluster administrators can create tenants. When you add a new tenant and the HSP software automatically creates the administrative user account "tenant-name*admin" to manage that tenant. 116 Chapter 2: Using the HSP cluster management API

129 tenants When you add a tenant, you have the option to enable and then configure LDAP parameters from which tenant users are retrieved. See "Configuring LDAP " on the next page for more information. Important: The decision about supporting the LDAP must be made at the time the tenancy is added. You cannot add support for LDAP later you would need to add a new tenant and delete the old one. HTTP request syntax POST Request Specify the properties for the tenant: name (required) string Name of the tenant. Supply either a name for the tenant or enter "autogenerate." The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. Tenant names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). enabled boolean Whether or not the tenant is enabled. By default, the tenant is enabled. Specify either true or false (case sensitive). ldap-enabled boolean Whether or not the tenant is LDAP enabled. By default, the tenant is not LDAP enabled. Specify either true or false (case sensitive). description string Description of the tenant. Free-flowing text, allowing up to 255 characters except ; (semicolon). Chapter 2: Using the HSP cluster management API 117

130 tenants (Continued) tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). user-list-uri uri When LDAP is enabled and configured, displays links to the directory server users and their associated properties. group-list-uri uri When LDAP is enabled and configured, displays links to the directory server groups and their associated properties. Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/tenants Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Configuring LDAP When you add a tenant, you have the option to retrieve tenant users from an LDAP server by setting the ldap-enabled property to true and then configuring the LDAP setting inside HSP. 118 Chapter 2: Using the HSP cluster management API

131 tenants Configuring LDAP for HSP is a four step process: 1. Configure authentication 2. Configure user mapping 3. Configure group mapping 4. Apply all of these configurations to the multitenancy server Step 1: Configuring authentication HTTP request syntax for authentication Request POST The <tenant-id> is the ID of the tenant for which you are configuring LDAP and is supplied in the URL. In addition, the action that you want to take (set-ldap-auth) is also specified in the URL. The set-ldap-auth action is repeated in the request body, along with the required and optional properties and their corresponding values: ldap-url (required) bind-user (required) bind-password (required) string string string Specify the URL for connecting to the LDAP server. Specify the user DN for the LDAP bind operation. Specify the password for the bind operation. For example, the body of the request would be specified as: { "set-ldap-auth": { "ldap-url": "string", "bind-user": "string", Chapter 2: Using the HSP cluster management API 119

132 tenants "bind-password": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Step 2: Configuring user mapping HTTP request syntax for authentication Request POST The <tenant-id> is the ID of the tenant for which you are configuring LDAP and is supplied in the URL. In addition, the action that you want to take (set-ldap-user-mapping) is also specified in the URL. The set-ldap-user-mapping action is repeated in the request body, along with the required and optional properties and their corresponding values: user-tree-dn (required) user-object-class (required) user-id (required) user-name (required) string string string string Specify search base for users. Specify LDAP objectclass for users. Specify LDAP attribute mapped to user ID. WARNING: Cannot be a multivalued attribute. Specify LDAP attribute mapped to user name. 120 Chapter 2: Using the HSP cluster management API

133 tenants (Continued) user-password (required) string Specify LDAP attribute mapped to user password. user- string Specify LDAP attribute mapped to user . user-enabled Boolean Specify LDAP attribute mapped to user enabled flag. enabled-default string Specify default value to enable users. This should match an appropriate int value if the LDAP server uses non-boolean (bitmask) values to indicate if a user is enabled or disabled. If this is not set to "True" the typical value is "512". This is typically used when "user_enabled_attribute = useraccountcontrol". enabled-mask number Specify bitmask integer to indicate the bit that the enabled value is stored in if the LDAP server represents "enabled" as a bit on an integer rather than a boolean. A value of "0" indicates the mask is not used. If this is not set to "0" the typical value is "2". This is typically used when "user_enabled_ attribute = useraccountcontrol". For example, the body of the request would be specified as: { "set-ldap-user-mapping": { "user-tree-dn": "string", "user-object-class": "string", "user-id": "string", "user-name": "string", "user-password": "string", "user- ": "string", "enabled-default"; "string" "enabled-mask": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. Chapter 2: Using the HSP cluster management API 121

134 tenants The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Step 3: Configuring group mapping HTTP request syntax for authentication Request POST The <tenant-id> is the ID of the tenant for which you are configuring LDAP and is supplied in the URL. In addition, the action that you want to take (set-ldap-group-mapping) is also specified in the URL. The set-ldap-group-mapping action is repeated in the request body, along with the required and optional properties and their corresponding values: group-tree-dn (required) group-object-class (required) group-id (required) group-name (required) group-member (required) string string string string string Specify search base for groups. Specify LDAP objectclass for groups. Specify LDAP attribute mapped to group ID. Specify LDAP attribute mapped to group name. Specify LDAP attribute mapped to show group membership. group-description string Specify LDAP attribute mapped to group description. For example, the body of the request would be specified as: { "set-ldap-group-mapping": { "group-tree-dn": "string", 122 Chapter 2: Using the HSP cluster management API

135 tenants "group-object-class": "string", "group-id": "string", "group-name": "string", "group-password": "string", "group-member": "string", "group-description": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Step 4: Apply settings HTTP request syntax for authentication Request Response POST The <tenant-id> is the ID of the tenant for which you are configuring LDAP and is supplied in the URL. In addition, the action that you want to take (apply-ldap-setting) is also specified in the URL. The apply-ldap-setting action is repeated in the request body without any additional properties. For example, the body of the request would be specified as: { "apply-ldap-setting": {} } The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. Chapter 2: Using the HSP cluster management API 123

136 tenants The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Getting the list and properties of directory server users HTTP request syntax Request Response You can get the list and properties of directory server users associated with an LDAP-enabled and configured tenant by supplying an additional userlist directive to the GET HTTP method for a specific tenant. GET There are no request parameters needed for the user-list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the directory server user. enabled boolean Whether or not the user is enabled. string User s primary address. Getting the list and properties of directory server groups HTTP request syntax Request You can get the list and properties of directory server groups associated with an LDAP-enabled and configured tenant by supplying an additional group-list directive to the GET HTTP method for a specific tenant. GET There are no request parameters needed for the group-list GET request. 124 Chapter 2: Using the HSP cluster management API

137 tenants Response In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the directory server group. role-list-urit string List of roles associated with the group. The following roles can be assigned to a directory server group: file-system-full-access file-system-read-only virtual-machine-full-access virtual-machine-read-only description string Description of the group. Granting and revoking roles to LDAP enabled tenant groups Cluster and tenant administrators can grant and revoke roles to tenant users. How roles are granted or revoked depend on whether the tenant is LDAP enabled or not: If the tenant is not LDAP enabled, roles are granted to or revoked from the tenant user directly. The default role granted to a new tenant user is file-system-read-only. If the tenant is LDAP enabled, roles are grant to the LDAP group to which the tenant user belongs. There is no default role granted to a directory server group you must take action to grant a role. Note: You cannot grant both read-only and full-access control to the same resource type they are mutually exclusive. If you grant mutually exclusive roles, HSP uses the role most recently granted. HTTP request syntax This section describes how to grant and revoke roles to LDAP groups, which is then inherited by the tenant users belonging to that group. POST <tenant-id>/actions/grant-group-role Chapter 2: Using the HSP cluster management API 125

138 tenants Or: POST <tenant-id>/actions/revoke-group-role Request The <tenant-id> is the ID of the tenant that you want to grant or revoke a role to an LDAP group and is supplied in the URL. In addition, the action that you want to take (grant-group-role or revoke-group-role) is also specified in the URL. The grant-group-role or revoke-group-role action is repeated in the request body, along with the required properties and their corresponding values: role-id (required) group-id (required) string string Specify the role that you want to grant or revoke to a directory server group. Specify the directory server group to which you want to grant or revoke the specified role. For example, the body of the request for granting a role would be specified as: { "grant-group-role": { "role-id": "string" } } For example, the body of the request for revoking a role would be specified as: { "revoke-group-role": { "role-id": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. 126 Chapter 2: Using the HSP cluster management API

139 tenants The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Editing the properties of a tenant You can edit the description and tags associated with the tenant, as well as enabling or disabling the tenant. Important: If you need to change the name of a tenant, you will need to add a new tenant and then delete the old tenant. HTTP request syntax Request POST The <tenant-id> is the ID of the tenant on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: enabled boolean Whether or not the tenant is enabled. By default, the tenant is enabled. Specify either true or false (case sensitive). ldap-enabled boolean Whether or not the tenant is LDAP enabled. By default, the tenant is not LDAP enabled. Specify either true or false (case sensitive). description string Description of the tenant. Free-flowing text, allowing up to 255 characters except ; (semicolon). Chapter 2: Using the HSP cluster management API 127

140 tenants (Continued) tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). user-list-uri uri When LDAP is enabled and configured, displays links to the directory server users and their associated properties. group-list-uri uri When LDAP is enabled and configured, displays links to the directory server groups and their associated properties. Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/tenants Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Deleting a tenant Deleting a tenant also deletes the associated tenant administrator. 128 Chapter 2: Using the HSP cluster management API

141 roles HTTP request syntax Request Response Example DELETE The <tenant-id> is the ID tenant that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/tenants Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. roles Roles provide the access control rules for tenant-managed HSP file system and virtual machine resources. HSP has a predefined set of roles that cluster and tenant administrators can grant to tenant users: file-system-full-access allows full management access to the file systems associated with a tenant. file-system-read-only allows only read access to the file systems associated with a tenant. Chapter 2: Using the HSP cluster management API 129

142 roles virtual-machine-full-access allows full management access to the virtual machines associated with a tenant. virtual-machine-read-only allows only read access to the virtual machines associated with a tenant. In the current version of the software, you cannot add, edit, or delete roles and you can only view role properties. See "Granting and revoking roles to non-ldap enabled tenant users" on page 195 for details on granting and revoking roles. The following management operations are supported for the roles resource: Getting a list of role URLs Getting the properties of a rack Getting the properties of all roles Editing the properties of a role Editing the properties of a role HTTP request syntax Request You can edit only the description and tags properties of an existing role. POST The <role-id> is the ID of the role on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: description string Description of the role. Free-flowing text, allowing up to 255 characters except ; (semicolon). 130 Chapter 2: Using the HSP cluster management API

143 roles (Continued) tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/roles Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of all roles HTTP request syntax Request Supplying an additional list directive to the GET HTTP method on the roles resource retrieves the properties for all roles. GET There are no request parameters needed for the list GET request. Chapter 2: Using the HSP cluster management API 131

144 roles Response In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties for all roles in the response: name string Predefined set of access control roles for tenant users and groups: file-system-full-access file-system-read-only virtual-machine-full-access virtual-machine-read-only permission string Predefined set of access rights assigned to corresponding named roles for file systems and virtual machines: full-access read-only tenant-name string Name of the tenant associated with the role. tenant-id string ID of the tenant associated with the role. description string Description of the role. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/roles Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 132 Chapter 2: Using the HSP cluster management API

145 roles Getting the properties of a role HTTP request syntax Request Response You can get the properties of a particular role by supplying the URL link to any role that was retrieved with the GET HTTP method on the roles (see "Getting a list of role URLs" on the next page). GET Supply the URL link to the role for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Predefined set of access control roles for tenant users and groups: file-system-full-access file-system-read-only virtual-machine-full-access virtual-machine-read-only permission string Predefined set of access rights assigned to corresponding named roles for file systems and virtual machines: full-access read-only tenant-name string Name of the tenant associated with the role. tenant-id string ID of the tenant associated with the role. description string Description of the role. tags string User-defined tags that can be used to organize and/or filter the response results. Chapter 2: Using the HSP cluster management API 133

146 roles Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/roles Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting a list of role URLs HTTP request syntax Using the GET HTTP method on the roles resource retrieves a list of URL links to the roles found. GET Request Response Example There are no request parameters needed for the GET request for roles. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the roles found. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/roles Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 134 Chapter 2: Using the HSP cluster management API

147 file-systems file-systems A file system is a namespace in which files are created and accessed. The HSP concept of a file system differs from the traditional concept of a file system in the following ways: Each file exists in only one file system, but instead of being stored on individual storage devices, the files are stored on multiple disks and spread across multiple nodes. You manage file system space usage by specifying a quota (size limit) for each file system. HSP monitors and enforces these quotas and issues alerts when you are approaching quota limits. You can easily change the quota for a file system without any interruption in service. Space is only allocated as files are written, so you can create file system quotas that are much larger than the space that is currently available on physical disks. The quota for a file system is also not a guaranty file systems share and can only grow to the actual storage space available within the cluster. Keep in mind that in a distributed file system, reaching the maximum limit of a quota cannot happen with the same preciseness possible in a nondistributed file system. By the time space tracking information has been extracted and synchronized across the nodes, some amount of data may be written that exceeds the quota. By default, all file system data writes include a companion checksum write to verify data integrity. When data is read, a checksum is calculated from the on-disk data and compared to the stored checksum. If the computed checksum does not match the stored checksum, HSP takes the appropriate measures to protect against data corruption, based on the data protection policy you specified for the file system. Important: File system space tracking and high and low water mark calculations for alerts are based on disk space statistics reported by the HSP storage layer. For performance reasons, these statistics are reported at set intervals, rather than dynamically. You may, therefore, see a slight lag between what is displayed for size and use statistics in HSP and what a more dynamic command like df shows. Chapter 2: Using the HSP cluster management API 135

148 file-systems The following management operations are supported for the file-systems resource: Getting a list of file system URLs Getting the properties of a file system Getting the properties of all file systems Adding a file system Editing the properties of a file system Enabling or disabling a file system Checking and repairing a file system Deleting a file system Getting a list of file system URLs HTTP request syntax Using the GET HTTP method on the file-systems resource retrieves a list of URL links to the file systems found. GET Request Response Example There are no request parameters needed for the GET request for file-systems. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the file systems found. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: 136 Chapter 2: Using the HSP cluster management API

149 file-systems /examples/api/file-systems Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 137

150 file-systems Getting the properties of a file system Get the properties of a particular file system. HTTP request syntax GET Request Response The <file-system-id> is the ID of the file system from which you want the list of properties and is supplied in the URL. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the file system. run-state string Run state of the file system: UP File system is fully functional, and data is available. DOWN File system is offline and the data is not available. An administrator might have disabled the file system. IMPAIRED File system has reported errors. We recommend running fsck to check and repair the file system. A warning severity alert is raised. ERROR File system is down due to errors that prevent it from staying online. We recommend running fsck to check and repair the file system. Customer support intervention may be required to troubleshoot the problem if fsck is not successful in repairing the file system. An error severity alert is raised. 138 Chapter 2: Using the HSP cluster management API

151 file-systems (Continued) See "Checking and repairing a file system" on page 161 for more information about running the fsck utility on file systems that have a run state of IMPAIRED or ERROR. enabled boolean Whether or not the file system is enabled. By default, the file system is enabled. shared-out boolean Whether or not the file system is shared out and available for client connections. A file system must have both a share and an access rule associated with it before clients can connect to it and therefore be considered shared out. Chapter 2: Using the HSP cluster management API 139

152 file-systems (Continued) data-protection string Data protection policy set for a file system. By default, the data protection policy is set to raid1_3instance_large_io. The current version of the software supports the following values: raid1_3instance_large_io Mirrored with 3 copies or instances of the data, tuned for supporting large streaming writes. This is the ideal for most Big Data Analytics style workloads or general purpose Data Lake. raid1_3instance_small_io: Mirrored with 3 copies or instances of the data, tuned for supporting small random writes. This is ideal for hosting virtual machine images and the best choice for relational databases. raid0_1instance_small_io: A single instance of the data is kept, data is not highly available. It is tuned for supporting small random writes. This is ideal for scratch space where low storage consumption is desired and workloads may be unpredictable, but losing data due to hardware failures would not be catastrophic. HSP automatically ensures that multiple instances of any given file are stored on multiple nodes based on the data protection policy that you specify for a file system. If a node or disk that contains a particular file fails, HSP automatically finds another instance and forwards the client request to another node for one of the file instances. Keep in mind, however, the more copies of each file you retain, the greater the storage consumption, so you need to determine the data protection/space consumption balance that makes sense for your file system. creation-time number Time stamp of when the file system was created. 140 Chapter 2: Using the HSP cluster management API

153 file-systems (Continued) space-hwm number File system space usage high water mark percentage. A high water mark percentage set at the file system level overrides the cluster-level property file-system-space-hwm that is set by default for new file systems added to the cluster. space-lwm number File system space usage low water mark percentage. A low water mark percentage set at the file system level overrides the cluster-level property file-system-space-lwm that is set by default for new file systems added to the cluster. encryption-algorithm string AES128 - is a symmetric key algorithm that encrypts and decrypts data in 128-bit blocks, using 128-bit keys. AES256 - is a symmetric key algorithm that encrypts and decrypts data in 128-bit blocks, using 256-bit keys. This encryption algorithm offers stronger cryptographic protection than AES128. none - no encryption. quota number An administrator-defined maximum file system size limit. HSP monitors and enforces file system quotas and issues alerts when you are approaching quota limits. Specify a byte value from bytes (128 GiB) to bytes (6 PiB). For example, if you want to create a file system with a 1 TiB maximum size, specify the quota as used-capacity number Used capacity in the file system, specified in bytes. free-capacity number Free capacity in file system, specified in bytes used-inodesusedinodes number Number of used inodes (files+directories+symbolic links) on the file system. free-inodes number Number of free inodes (files+directories+symbolic links) on the file system. record-access-time boolean Whether or not the file system should track the last time a file was accessed. Chapter 2: Using the HSP cluster management API 141

154 file-systems (Continued) fsck-action-running boolean Whether or not an active fsck is running on the file system. fsck-job-id string ID of the job associated with the file system fsck. fsck-job-details string Job details of an active fsck. fsck-percent-complete string Progress of an active fsck, expressed as a percentage. cluster-name string Name of the cluster to which the file system is associated. HSP-internal boolean Whether or not the file system is an HSP internal file system. Internal file systems are created and maintained by the HSP software. These file systems cannot be deleted or renamed. cluster-id string ID of the cluster to which the file system is associated. tenant-name string Name of the tenant who owns/manages the file system. tenant-id string ID of the tenant who owns/manages the file system. description string Description of the file system. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/file-systems Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 142 Chapter 2: Using the HSP cluster management API

155 file-systems Getting the properties of all file systems HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the filesystems resource retrieves the properties for all file systems. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties for all file systems in the response: name string Name of the file system. run-state string Run state of the file system: UP File system is fully functional, and data is available. DOWN File system is offline and the data is not available. An administrator might have disabled the file system. IMPAIRED File system has reported errors. We recommend running fsck to check and repair the file system. A warning severity alert is raised. ERROR File system is down due to errors that prevent it from staying online. We recommend running fsck to check and repair the file system. Customer support intervention may be required to troubleshoot the problem if fsck is not successful in repairing the file system. An error severity alert is raised. Chapter 2: Using the HSP cluster management API 143

156 file-systems (Continued) See "Checking and repairing a file system" on page 161 for more information about running the fsck utility on file systems that have a run state of IMPAIRED or ERROR. enabled boolean Whether or not the file system is enabled. By default, the file system is enabled. shared-out boolean Whether or not the file system is shared out and available for client connections. A file system must have both a share and an access rule associated with it before clients can connect to it and therefore be considered shared out. 144 Chapter 2: Using the HSP cluster management API

157 file-systems (Continued) data-protection string Data protection policy set for a file system. By default, the data protection policy is set to raid1_3instance_large_io. The current version of the software supports the following values: raid1_3instance_large_io Mirrored with 3 copies or instances of the data, tuned for supporting large streaming writes. This is the ideal for most Big Data Analytics style workloads or general purpose Data Lake. raid1_3instance_small_io: Mirrored with 3 copies or instances of the data, tuned for supporting small random writes. This is ideal for hosting virtual machine images and the best choice for relational databases. raid0_1instance_small_io: A single instance of the data is kept, data is not highly available. It is tuned for supporting small random writes. This is ideal for scratch space where low storage consumption is desired and workloads may be unpredictable, but losing data due to hardware failures would not be catastrophic. HSP automatically ensures that multiple instances of any given file are stored on multiple nodes based on the data protection policy that you specify for a file system. If a node or disk that contains a particular file fails, HSP automatically finds another instance and forwards the client request to another node for one of the file instances. Keep in mind, however, the more copies of each file you retain, the greater the storage consumption, so you need to determine the data protection/space consumption balance that makes sense for your file system. creation-time number Time stamp of when the file system was created. Chapter 2: Using the HSP cluster management API 145

158 file-systems (Continued) space-hwm number File system space usage high water mark percentage. A high water mark percentage set at the file system level overrides the cluster-level property file-system-space-hwm that is set by default for new file systems added to the cluster. space-lwm number File system space usage low water mark percentage. A low water mark percentage set at the file system level overrides the cluster-level property file-system-space-lwm that is set by default for new file systems added to the cluster. encryption-algorithm string AES128 - is a symmetric key algorithm that encrypts and decrypts data in 128-bit blocks, using 128-bit keys. AES256 - is a symmetric key algorithm that encrypts and decrypts data in 128-bit blocks, using 256-bit keys. This encryption algorithm offers stronger cryptographic protection than AES128. none - no encryption. quota number An administrator-defined maximum file system size limit. HSP monitors and enforces file system quotas and issues alerts when you are approaching quota limits. Specify a byte value from bytes (128 GiB) to bytes (6 PiB). For example, if you want to create a file system with a 1 TiB maximum size, specify the quota as used-capacity number Used capacity in the file system, specified in bytes. free-capacity number Free capacity in file system, specified in bytes used-inodesusedinodes number Number of used inodes (files+directories+symbolic links) on the file system. free-inodes number Number of free inodes (files+directories+symbolic links) on the file system. record-access-time boolean Whether or not the file system should track the last time a file was accessed. 146 Chapter 2: Using the HSP cluster management API

159 file-systems (Continued) fsck-action-running boolean Whether or not an active fsck is running on the file system. fsck-job-id string ID of the job associated with the file system fsck. fsck-job-details string Job details of an active fsck. fsck-percent-complete string Progress of an active fsck, expressed as a percentage. cluster-name string Name of the cluster to which the file system is associated. HSP-internal boolean Whether or not the file system is an HSP internal file system. Internal file systems are created and maintained by the HSP software. These file systems cannot be deleted or renamed. cluster-id string ID of the cluster to which the file system is associated. tenant-name string Name of the tenant who owns/manages the file system. tenant-id string ID of the tenant who owns/manages the file system. description string Description of the file system. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/file-systems Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 147

160 file-systems Adding a file system HTTP request syntax Create files systems in an organizational manner that makes sense for your company and the files you are storing, for example, by business organization/unit, by file type, by project, and so on. You can add up to 1024 virtual file systems in each cluster. Because the size of a file system is not limited by the underlying storage, file system size limits or quotas are purely space management limits that you want to set for organizational categories you choose. Physical storage is allocated only as files are written to a file system, so you do not need to allocate a physical storage pool of equal size. Another thing to keep in mind, is that data protection policies (how many instances of each file in that file system you want to store) are set at the file system level. Data protection policies then, may play also role in your file system organization creation scheme. The root permissions for a new file system are set to 777 by default. Client access permissions are then granted to the file system by adding an NFS share and by any specific access control rules you create for that share. See "Adding a share" on page 170 for more information. There is a cluster-level property named file-system-auto-access that controls whether or not you will need to manually create the share and access rule required to share out the newly added file system or the whether the HSP software will automatically create these for you. By default, filesystem-auto-access is set to true and the file system is shared out. When you allow the software to automatically share out the file system, HSP adds a share with the same name as the file system and adds an access rule called "DefaultAccessRule" that provides read/write access to the share for all client hosts. You can add more restrictive access rules to the share, as well as edit or delete this automatically created access rule. If at the cluster level, however, file-system-auto-access is set to false is unmarked, you can set the auto-access at file system creation time to override the cluster setting and automatically create the share and default access rule. Otherwise, you will need to manually create the required share and access rule to share out the file system. POST Chapter 2: Using the HSP cluster management API

161 file-systems Request Specify the properties for the file system: name (required) string Name of the file system. Supply either a name for the file system or enter auto-generate. The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. The name of the file system you provide is also the mount point for the file system, so follow standard UNIX file system naming conventions and rules. File system names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk), / (slash), and ; (semicolon). enabled boolean Whether or not the file system is enabled. By default, the file system is enabled. Specify either true or false (case sensitive). Chapter 2: Using the HSP cluster management API 149

162 file-systems (Continued) data-protection string Data protection policy set for a file system. By default, the data protection policy is set to raid1_3instance_large_io. The current version of the software supports the following values: raid1_3instance_large_io Mirrored with 3 copies or instances of the data, tuned for supporting large streaming writes. This is the ideal for most Big Data Analytics style workloads or general purpose Data Lake. raid1_3instance_small_io: Mirrored with 3 copies or instances of the data, tuned for supporting small random writes. This is ideal for hosting virtual machine images and the best choice for relational databases. raid0_1instance_small_io: A single instance of the data is kept, data is not highly available. It is tuned for supporting small random writes. This is ideal for scratch space where low storage consumption is desired and workloads may be unpredictable, but losing data due to hardware failures would not be catastrophic. HSP automatically ensures that multiple instances of any given file are stored on multiple nodes based on the data protection policy that you specify for a file system. If a node or disk that contains a particular file fails, HSP automatically finds another instance and forwards the client request to another node for one of the file instances. Keep in mind, however, the more copies of each file you retain, the greater the storage consumption, so you need to determine the data protection/space consumption balance that makes sense for your file system. 150 Chapter 2: Using the HSP cluster management API

163 file-systems (Continued) space-hwm number File system space usage high water mark percentage. A high water mark percentage set at the file system level overrides the cluster-level property file-system-space-hwm that is set by default for new file systems added to the cluster. When the remaining allocated file system space reaches the high water mark, an alert is raised until the file system space consumption falls below the low water mark percentage. Specify a value from 1 to 100 that is greater than the space-lwm. Keep in mind that any value specified for space-hwm overrides the value of the cluster level file-system-space-hwm property. space-lwm number File system space usage low water mark percentage. A low water mark percentage set at the file system level overrides the cluster-level property file-system-space-lwm that is set by default for new file systems added to the cluster. Existing file system space alerts are automatically cleared once the low water mark setting is achieved. The low water mark is typically 10 to 20 percent less than the high water mark. Specify a value from 1 to 100. Keep in mind that any value specified for space-lwm overrides the value of the cluster level file-system-space-lwm property. encryption-algorithm string AES128 - is a symmetric key algorithm that encrypts and decrypts data in 128-bit blocks, using 128-bit keys. AES256 - is a symmetric key algorithm that encrypts and decrypts data in 128-bit blocks, using 256-bit keys. This encryption algorithm offers stronger cryptographic protection than AES128. none - no encryption. Chapter 2: Using the HSP cluster management API 151

164 file-systems (Continued) quota (required) number An administrator-defined maximum file system size limit. HSP monitors and enforces file system quotas and issues alerts when you are approaching quota limits. The quota of a file system is a virtual limitation. Space is allocated only as files are written and stored, so you can create file systems with a much larger quota than the currently available capacity. Specify a byte value from bytes (128 GiB) to bytes (6 PiB). For example, if you want to create a file system with a 1 TiB maximum size, specify the quota as record-access-time boolean Whether or not the file system should track the last time a file was accessed. Because there is a performance cost associated with tracking access time on frequently changing and accessed files, record-access-time is set to false. description string Description of the file system. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job". 152 Chapter 2: Using the HSP cluster management API

165 file-systems Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/file-systems Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 153

166 file-systems Editing the properties of a file system HTTP request syntax Request You can edit the properties of an existing file system, including the quota limit. Quota changes can be made at any time without any client interruption in service. POST The <file-system-id> is the ID of the file system on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: name string Name of the file system. The name of the file system you provide is also the mount point for the file system, so follow standard UNIX file system naming conventions and rules. File system names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk), / (slash), and ; (semicolon). enabled boolean Whether or not the file system is enabled. By default, the file system is enabled. Specify either true or false (case sensitive). 154 Chapter 2: Using the HSP cluster management API

167 file-systems (Continued) data-protection string Data protection policy set for a file system. By default, the data protection policy is set to raid1_3instance_large_io. The current version of the software supports the following values: raid1_3instance_large_io Mirrored with 3 copies or instances of the data, tuned for supporting large streaming writes. This is the ideal for most Big Data Analytics style workloads or general purpose Data Lake. raid1_3instance_small_io: Mirrored with 3 copies or instances of the data, tuned for supporting small random writes. This is ideal for hosting virtual machine images and the best choice for relational databases. raid0_1instance_small_io: A single instance of the data is kept, data is not highly available. It is tuned for supporting small random writes. This is ideal for scratch space where low storage consumption is desired and workloads may be unpredictable, but losing data due to hardware failures would not be catastrophic. HSP automatically ensures that multiple instances of any given file are stored on multiple nodes based on the data protection policy that you specify for a file system. If a node or disk that contains a particular file fails, HSP automatically finds another instance and forwards the client request to another node for one of the file instances. Keep in mind, however, the more copies of each file you retain, the greater the storage consumption, so you need to determine the data protection/space consumption balance that makes sense for your file system. Chapter 2: Using the HSP cluster management API 155

168 file-systems (Continued) space-hwm number File system space usage high water mark percentage. A high water mark percentage set at the file system level overrides the cluster-level property file-system-space-hwm that is set by default for new file systems added to the cluster. When the remaining allocated file system space reaches the high water mark, an alert is raised until the file system space consumption falls below the low water mark percentage. Specify a value from 1 to 100 that is greater than the space-lwm. Keep in mind that any value specified for space-hwm overrides the value of the cluster level file-system-space-hwm property. space-lwm number File system space usage low water mark percentage. A low water mark percentage set at the file system level overrides the cluster-level property file-system-space-lwm that is set by default for new file systems added to the cluster. Existing file system space alerts are automatically cleared once the low water mark setting is achieved. The low water mark is typically 10 to 20 percent less than the high water mark. Specify a value from 1 to 100. Keep in mind that any value specified for space-lwm overrides the value of the cluster level file-system-space-lwm property. encryption-algorithm string AES128 - is a symmetric key algorithm that encrypts and decrypts data in 128-bit blocks, using 128-bit keys. AES256 - is a symmetric key algorithm that encrypts and decrypts data in 128-bit blocks, using 256-bit keys. This encryption algorithm offers stronger cryptographic protection than AES128. none - no encryption. 156 Chapter 2: Using the HSP cluster management API

169 file-systems (Continued) quota number An administrator-defined maximum file system size limit. HSP monitors and enforces file system quotas and issues alerts when you are approaching quota limits. The quota of a file system is a virtual limitation. Space is allocated only as files are written and stored, so you can create file systems with a much larger quota than the currently available capacity. Specify a byte value from bytes (128 GiB) to bytes (6 PiB). For example, if you want to create a file system with a 1 TiB maximum size, specify the quota as record-access-time boolean Whether or not the file system should track the last time a file was accessed. Because there is a performance cost associated with tracking access time on frequently changing and accessed files, record-access-time is set to false. description string Description of the file system. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. Chapter 2: Using the HSP cluster management API 157

170 file-systems The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/file-systems Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 158 Chapter 2: Using the HSP cluster management API

171 file-systems Enabling or disabling a file system A file system is enabled by default, meaning that as soon as file systems are created and properly shared out (by adding a share and at least one access rule), clients will have access to the file system by default. Disabling a file system disables all shares associated with the file system, which means that you are disrupting client access to that file system make sure this is what you intend. Shares added to a disabled file system will show as disabled until the file system is again enabled. Some administrators like to create all their file systems at once, but enable and bring them online only as needed. Note: You must disable a file system before you can initiate an fsck on that file system (see "Enabling or disabling a file system" above for details about disabling a file system). HTTP request syntax Request POST The <file-system-id> is the ID of the file system that you want to enable or disable and is supplied in the URL. Specify the enabled property: enabled boolean Whether or not the file system is enabled. By default, a file system is enabled. Specify either True or False (case sensitive). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. Chapter 2: Using the HSP cluster management API 159

172 file-systems The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/file-systems Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. To reenable a file system when it has previously been disabled, change the name/value pair to "enabled"=true in the payload and run the POST method again. 160 Chapter 2: Using the HSP cluster management API

173 file-systems Checking and repairing a file system You can manually initiate running the fsck (file system check) utility to check the consistency of and repair a file system. We recommend running fsck when alert conditions are reported for file systems in the IMPAIRED or ERROR run state. Important: Existing storage issues can impact file systems and cause impairment. Be sure to address any node and disk problems in your cluster before running fsck. HTTP request syntax Before you can initiate fsck, you must disable the file system (see "Enabling or disabling a file system" on page 159 for details about disabling a file system). The fsck utility will fail if the file system is enabled or if there is already an fsck running on the file system. Upon completion, the event log for the fsck will report the number of errors found, as well as the location of a log file giving a more detailed description of these errors. The log file is copied to the system_info file system in the following location: /debug_logs/fsck If fsck successfully checks and repairs the file system, the HSP software automatically enables the file system. If the fsck does not successfully repair the file system, the file system remains disabled and requires administrator attention to decide on the next course of action. In addition to running an fsck, you can also abort an fsck using any of the HSP management interfaces. POST actions/fsck-repair Or: POST actions/fsck-abort Chapter 2: Using the HSP cluster management API 161

174 file-systems Request The <file-system-id> is the ID of the file system on which you want to perform one of the fsck actions and is supplied in the URL. In addition, the fsck-repair or the fsck-abort action is also specified in the URL. The fsck-repair or the fsck-abort action is repeated in the request body without any additional properties. For example, the body of the request would be specified as: Or: { "fsck-repair": {} } { "fsck-abort": {} } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, "Getting the status of an asynchronous job" on page 1. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/file-systems Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 162 Chapter 2: Using the HSP cluster management API

175 file-systems Deleting a file system Deleting a file system will delete all files and all instances of the files in the file system. The delete operation also deletes all shares and access rules associated with the file system. Important: Deleting a file system is a permanent removal and you would only be able to recover the files if you have implemented a backup strategy for your cluster. HTTP request syntax Request Response Example Even though file system deletion happens in the background, this task can take some time to complete, as well as report the reclaimed space statistics. DELETE The <file-system-id> is the ID of the file system that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job". A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/file-systems Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 163

176 shares shares A client cannot access a file system until you explicitly share out that file system and define at least one access rule that grants permission to the share. The current version of the product supports NFSv3 only. The following management operations are supported for the share resource: Getting a list of share URLs Getting the properties of a share Getting the properties of all shares Adding a share Editing the properties of a share Getting the list of access rules for a share Adding, editing, or deleting an access rule Deleting a share Getting a list of share URLs HTTP request syntax Request Response Using the GET HTTP method on the shares resource retrieves a list of URL links to the shares found. GET There are no request parameters needed for the GET request for shares. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the shares found. 164 Chapter 2: Using the HSP cluster management API

177 shares Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/shares Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 165

178 shares Getting the properties of a share HTTP request syntax Request Response You can get the properties of a particular share by supplying the URL link to any share that was retrieved with the GET HTTP method on the shares (see "Getting a list of share URLs" on page 164). GET The <share-id> is the ID of the file system share from which you want the list of properties and is supplied in the URL. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response. Here is the list of attributes returned for NFS shares: name string Name of the share. run-state string Run state of the file system share: UP Share is available and fully functional. DOWN Share is currently offline. An administrator might have disabled the share. enabled boolean Whether or not the share is enabled. By default, the share is enabled. access-rules-uri uri Link to the share access rules and their associated properties. file-system-name string Name of the file system to which the share is associated. 166 Chapter 2: Using the HSP cluster management API

179 shares (Continued) file-system-id string ID of the file system to which the share is associated. tenant-name string Name of the tenant associated with the file system share. tenant-id string ID of the tenant associated with the file system share. description string Description of the file system share. tags string User-defined tags that can be used to organize and/or filter the response results. type string Type of file system share. In the current release, only NFS (NFS version 3) is supported and this is the default share type. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/shares Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 167

180 shares Getting the properties of all shares HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the shares resource retrieves the properties for all shares. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the share. run-state string Run state of the file system share: UP Share is available and fully functional. DOWN Share is currently offline. An administrator might have disabled the share. enabled boolean Whether or not the share is enabled. By default, the share is enabled. access-rules-uri uri Link to the share access rules and their associated properties. file-system-name string Name of the file system to which the share is associated. file-system-id string ID of the file system to which the share is associated. tenant-name string Name of the tenant associated with the file system share. 168 Chapter 2: Using the HSP cluster management API

181 shares (Continued) tenant-id string ID of the tenant associated with the file system share. description string Description of the file system share. tags string User-defined tags that can be used to organize and/or filter the response results. type string Type of file system share. In the current release, only NFS (NFS version 3) is supported and this is the default share type. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/shares Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 169

182 shares Adding a share Before clients can access files in a file system, that file system share must be shared out, which means an associated share and an access rule is required. After you add a share, you must define at least one access rule that grants permission to that share. By default, the HSP software automatically creates a share with the same name as the file system and an access rule called "DefaultAccessRule" that grants read/write access to the share for all client hosts. See "Adding, editing, or deleting an access rule" on page 178 for details. You can override this automatic creation at the cluster level by setting the file-system-auto-access property to false. Tip: For ease of management, we suggest that you name the share the same name as the file system. HTTP request syntax POST Request Specify the properties for the file system share: name (required) string Name of the share. Supply either a name for the share or enter "autogenerate." The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. Share names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk), / (slash), and ; (semicolon). 170 Chapter 2: Using the HSP cluster management API

183 shares (Continued) enabled boolean Whether or not the share is enabled. By default, the share is enabled. Specify either true or false (case sensitive). access-rules-uri uri Link to the share access rules and their associated properties. file-system-id (required) string ID of the file system to which the share is associated. tenant-name string Name of the tenant associated with the file system share. tenant-id string ID of the tenant associated with the file system share. description string Description of the file system share. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). type (required) string Type of file system share. In the current release, only NFS (NFS version 3) is supported and this is the default share type. Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Chapter 2: Using the HSP cluster management API 171

184 shares Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/shares Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 172 Chapter 2: Using the HSP cluster management API

185 shares Editing the properties of a share HTTP request syntax Request You can edit the properties of an existing file system share. POST The <share-id> is the ID of the file system share on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: name (required) string Name of the share. Share names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk), / (slash), and ; (semicolon). enabled boolean Whether or not the share is enabled. By default, the share is enabled. Specify either true or false (case sensitive). access-rules-uri uri Link to the share access rules and their associated properties. file-system-id (required) string ID of the file system to which the share is associated. tenant-name string Name of the tenant associated with the file system share. tenant-id string ID of the tenant associated with the file system share. Chapter 2: Using the HSP cluster management API 173

186 shares (Continued) description string Description of the file system share. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). type (required) string Type of file system share. In the current release, only NFS (NFS version 3) is supported and this is the default share type. Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/shares Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 174 Chapter 2: Using the HSP cluster management API

187 shares Getting the list of access rules for a share HTTP request syntax Request Response You can get the list of access rules for a share by supplying the URL link returned for the access-rules-uri property that was retrieved with the GET HTTP method on a share ID (see "Getting the properties of a share" on page 166). GET Supply the URL link specified in the access-rules-uri for the share for which you want the list of access rules. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the access rule. host-specification string The host access control properties for a share. read-write boolean Whether or not the access rights associated with the file system share is read/write. By default, file system share access rights are read/write. NFS access control is based on the requestors user IDs (UID) and group IDs (GID), much like local UNIX/Linux file access. A key difference, however, is that with NFS, the server cannot directly authenticate the identity of its clients and must trust the authentications performed by the users own systems. The following squash options provide the capability to control trusted NFS share access for root and non-root users. Chapter 2: Using the HSP cluster management API 175

188 shares (Continued) all-squash boolean Controls whether or not all non-root users have trusted access to the share. Operating similarly to root squash for the root user, the all squash export option maps all non-root users to the anonymous UID (commonly nobody), which results in no trusted access to the files in the NFS share on the client machine. Generally, you want to trust non-root access to the share and this is the default. root-squash boolean Controls whether or not all root users have trusted access to the share. By default, NFS exports directories with the root squash option set to true prevent root on client machines from having privileged access to exported files. This squashing is accomplished by mapping the root user to the anonymous UID (commonly nobody), which results in root not being able to access files in the NFS share on the client machine. Generally, you do not want to trust root access to the share and this is the default. anonuid number The user identifier (UID) that anonymous (unmapped) users will be mapped to for NFS share access. By default, anonuid is set to (nobody). anongid number The group identifier (GID) that anonymous (unmapped) users will be mapped to for NFS share access. By default, anongid is set to (nobody). share-id string ID of the share to which the access rule is associated. description string Description of the access rule. tags string User-defined tags that can be used to organize and/or filter the response results. 176 Chapter 2: Using the HSP cluster management API

189 shares Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/access-rules Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 177

190 shares Adding, editing, or deleting an access rule Access rules define the permissions for accessing a file system share. You need to create at least one access rule to grant the permissions to access the share. You can add, edit, or delete NFS share access rules. Note: You cannot change the name of an access rule. You can add a new access rule with the desired name, then delete the access rule with the name you do not want. HTTP request syntax Request A client cannot access a file system until that file system is explicitly shared out, which means an associated share and an access rule is required. By default, the HSP software automatically creates a share with the same name as the file system and an access rule called "DefaultAccessRule" that provides read/write access to the share for all client hosts. You can add more restrictive access rules to the share, as well as edit or delete the automatically created access rule. You can override this automatic creation at the cluster level by setting the file-system-auto-access to false. POST actions/add-access-rule Or: POST actions/edit-access-rule Or: POST actions/delete-access-rule The <share-id> is the ID of the file system share on which you want to add, edit, or delete access rules and is supplied in the URL. In addition, the action that you want to take (add-access-rule or edit-access-rule or deleteaccess-rule) action is also specified in the URL. 178 Chapter 2: Using the HSP cluster management API

191 shares The add-access-rule or edit-access-rule action is repeated in the request body, along with the required properties and its corresponding value for the these actions: name (required) string Name of the access rule. Supply either a name for the access rule or enter "auto-generate." The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. Access rules can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). host-specification string The host access control properties for a share. You can create multiple access rules for a share, however, the host specification for each rule must be unique. HSP evaluates rules in descending netmask order from the most specific rule to least specific rule. Specifying an asterisk (*) lets you set a default share access control rule that applies to all client hosts. The advantage to setting up this all clients default as the initial share before restricting access to specific hosts is that you are providing a fall through access rule if no other access rules that you create later apply, then this default share access rule is applied to all client hosts. The host-specification can be from 1 to 255 characters and can specify: asterisk (*) to indicate all hosts hostname or hostname.domain.com (for example, dali.hds.com), if set up in DNS ip-address (for example, ) ip-subnet (for example, /16 or / ) You cannot specify: Chapter 2: Using the HSP cluster management API 179

192 shares (Continued) multiple hosts in a single share access rule domain (for example, hds.com) embedded wildcard characters in host specifications (for example, * or *.hds.com) ; (semicolon) read-write boolean Whether or not the access rights associated with the file system share is read/write. By default, file system share access rights are read/write. NFS access control is based on the requestors user IDs (UID) and group IDs (GID), much like local UNIX/Linux file access. A key difference, however, is that with NFS, the server cannot directly authenticate the identity of its clients and must trust the authentications performed by the users own systems. The following squash options provide the capability to control trusted NFS share access for root and non-root users. all-squash boolean Controls whether or not all non-root users have trusted access to the share. Operating similarly to root squash for the root user, the all squash export option maps all non-root users to the anonymous UID (commonly nobody), which results in no trusted access to the files in the NFS share on the client machine. Generally, you want to trust non-root access to the share and this is the default. 180 Chapter 2: Using the HSP cluster management API

193 shares (Continued) root-squash boolean Controls whether or not all root users have trusted access to the share. By default, NFS exports directories with the root squash option set to true prevent root on client machines from having privileged access to exported files. This squashing is accomplished by mapping the root user to the anonymous UID (commonly nobody), which results in root not being able to access files in the NFS share on the client machine. Generally, you do not want to trust root access to the share and this is the default. anonuid number The user identifier (UID) that anonymous (unmapped) users will be mapped to for NFS share access. By default, anonuid is set to (nobody). anongid number The group identifier (GID) that anonymous (unmapped) users will be mapped to for NFS share access. By default, anongid is set to (nobody). description string Description of the access rule. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). For example, the body of the add-access-rule request would be specified as: { "add-access-rule": { "name": "string", "host-specification": "string", "read-write": true, "all-squash": false, "root-squash": true, "anonuid": 65534, "anongid": 65534, Chapter 2: Using the HSP cluster management API 181

194 shares "description": "string", "tags": "string" } } For example, the body of the edit-access-rule request would be specified as: { "edit-access-rule": { "name": "string", "host-specification": "string", "read-write": true, "all-squash": false, "root-squash": true, "anonuid": 65534, "anongid": 65534, "description": "string", "tags": "string" } } The delete-access-rule action is repeated in the request body, along with the required property and its corresponding value for the delete action: name (required) string Name of the access rule. For example, the body of the delete-access-rule request would be specified as: { "delete-access-rule": { "name": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. 182 Chapter 2: Using the HSP cluster management API

195 shares The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/access-rules Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 183

196 shares Deleting a share HTTP request syntax Request Response Example You can delete a file system share. DELETE The <share-id> is the ID of the file system share that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/shares Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 184 Chapter 2: Using the HSP cluster management API

197 users users A default cluster administrative user account named admin is created by default when the HSP software is installed. This account has full administrative privileges and can perform all of the HSP management operations, including being able to add tenants and user accounts to allow access to a cluster. When a cluster administrator creates a tenant the HSP software automatically creates an administrative user account "tenantname*admin" who has management access to all of the tenant resources it manages. Only cluster and tenant administrators can add, edit, or delete tenant users, as well as grant or revoke access roles to those tenant users. The following management operations are supported for the users resource: Getting a list of user account URLs Getting the properties of a user account Getting the properties of all user accounts Adding a user account Granting and revoking roles to non-ldap enabled tenant users Editing the properties of a user account Deleting a user account Getting a list of user account URLs HTTP request syntax Using the GET HTTP method on the users resource retrieves a list of URL links to the user accounts found. GET Chapter 2: Using the HSP cluster management API 185

198 users Request There are no request parameters needed for the GET request for users. Response In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the user accounts found. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/users Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 186 Chapter 2: Using the HSP cluster management API

199 users Getting the properties of a user account HTTP request syntax Request Response You can get the properties of a particular user account by supplying the URL link to any user that was retrieved with the GET HTTP method on the users (see "Getting a list of user account URLs" on page 185). GET Supply the URL link to the user account for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response. Here is the list of attributes returned for the ADMIN user account type: name string Name of the user account. enabled boolean Whether or not the user account is enabled. first-name string User s first name. last-name string User s last name. By default, the user account is enabled. Because there is only one tenant administrator, you cannot disable that user. primary- string User account s primary address to which to send subscribed to alert condition notifications. critical-alertconditions boolean Whether or not the user is subscribed to receive critical alert notifications. error-alert-conditions boolean Whether or not the user is subscribed to receive error alert notifications. Chapter 2: Using the HSP cluster management API 187

200 users (Continued) warning-alertconditions boolean Whether or not the user is subscribed to receive warning alert notifications. secondary- string Additional address to which to send subscribed to alert condition notifications. password string User s password, shown as asterisks (***), not in clear text. Passwords can be from 1 to 255 characters and can contain any UTF-8 characters except ; (semicolon). cluster-name string Name of the cluster to which the user account is associated. cluster-id string ID of the cluster to which the user account is associated. tenant-name string Name of the tenant to which the user account is associated. tenant-id string ID of the tenant to which the user account is associated. role-list string List of roles associated with a tenant user account. The following roles can be assigned to a tenant user: file-system-full-access file-system-read-only virtual-machine-full-access virtual-machine-read-only description string Description of the user account. tags string User-defined tags that can be used to organize and/or filter the response results. type string Type of the user account: ADMIN TENANT-ADMIN TENANT-USER 188 Chapter 2: Using the HSP cluster management API

201 users Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/users Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 189

202 users Getting the properties of all user accounts HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the users resource retrieves the properties for all user accounts. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties for all user accounts in the response. Here is the list of attributes returned for ADMIN user account type: name string Name of the user account. enabled boolean Whether or not the user account is enabled. first-name string User s first name. last-name string User s last name. By default, the user account is enabled. Because there is only one tenant administrator, you cannot disable that user. primary- string User account s primary address to which to send subscribed to alert condition notifications. boolean Whether or not the user is subscribed to receive critical alert notifications. error-alert-conditions boolean Whether or not the user is subscribed to receive error alert notifications. critical-alertconditions warning-alertconditions boolean Whether or not the user is subscribed to receive warning alert notifications. 190 Chapter 2: Using the HSP cluster management API

203 users (Continued) secondary- string Additional address to which to send subscribed to alert condition notifications. password string User s password, shown as asterisks (***), not in clear text. Passwords can be from 1 to 255 characters and can contain any UTF-8 characters except ; (semicolon). cluster-name string Name of the cluster to which the user account is associated. cluster-id string ID of the cluster to which the user account is associated. tenant-name string Name of the tenant to which the user account is associated. tenant-id string ID of the tenant to which the user account is associated. role-list string List of roles associated with a tenant user account. The following roles can be assigned to a tenant user: file-system-full-access file-system-read-only virtual-machine-full-access virtual-machine-read-only description string Description of the user account. tags string User-defined tags that can be used to organize and/or filter the response results. type string Type of the user account: ADMIN TENANT-ADMIN TENANT-USER Example Chapter 2: Using the HSP cluster management API 191

204 users Adding a user account A default cluster administrative user account named admin is already created when the HSP software is installed. In addition, the cluster administrator can create other user accounts to allow administrative access to a cluster. A cluster administrator can also create tenants. The HSP software automatically creates a tenant administrative user account "tenant-name*admin" for each tenant when that tenant is created. Tenant administrators manage the resources within their tenancy A cluster administrator or a tenant administrator can create tenant user accounts that have access restricted only to the resources within a tenancy. Each tenant user account is created as "tenant-name*tenant-name" so you can easily distinguish them from cluster administrative user accounts. If the tenant is LDAP enabled, you can then provide access to the tenant's resources using roles granted to directory server groups. If the tenant is not LDAP enabled, you can provide access to the tenant's resources using roles granted directly to the tenant user. Note: Certain user account names are restricted and internal to the HSP appliance and Linux operations. The list includes user account names like root, daemon, sync, mail, proxy jetty, and ganglia. You will see the following error if you try to add a user account that is restricted: Operation failed: name is restricted or already in use HTTP request syntax POST Chapter 2: Using the HSP cluster management API

205 users Request Specify the properties for the user account: name (required) string Name of the user account. Supply either a name for the user or enter "autogenerate." The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. User account names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). enabled boolean Whether or not the user account is enabled. first-name string User s first name. last-name string User s last name. By default, the user account is enabled. Because there is only one tenant administrator, you cannot disable that user. Specify either true or false (case sensitive). First names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). Last names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). primary- string User account s primary address to which to send subscribed to alert condition notifications. boolean Whether or not the user is subscribed to receive critical alert notifications. error-alert-conditions boolean Whether or not the user is subscribed to receive error alert notifications. critical-alertconditions warning-alertconditions boolean Whether or not the user is subscribed to receive warning alert notifications. Chapter 2: Using the HSP cluster management API 193

206 users (Continued) secondary- string Additional address to which to send subscribed to alert condition notifications. password string User s password, shown as asterisks (***), not in clear text. Passwords can be from 1 to 255 characters and can contain any UTF-8 characters except ; (semicolon). cluster-name string Name of the cluster to which the user account is associated. cluster-id string ID of the cluster to which the user account is associated. tenant-name string Name of the tenant to which the user account is associated. tenant-id string ID of the tenant to which the user account is associated. description string Description of the user account. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). type string Type of the user account: ADMIN TENANT-ADMIN TENANT-USER Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. 194 Chapter 2: Using the HSP cluster management API

207 users The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/users Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Granting and revoking roles to non-ldap enabled tenant users Cluster and tenant administrators can grant and revoke roles to tenant users. How roles are granted or revoked depend on whether the tenant is LDAP enabled or not: If the tenant is not LDAP enabled, roles are granted to or revoked from the tenant user directly. The default role granted to a new tenant user is file-system-read-only. If the tenant is LDAP enabled, roles are grant to the LDAP group to which the tenant user belongs. There is no default role granted to a directory server group you must take action to grant a role. Note: You cannot grant both read-only and full-access control to the same resource type they are mutually exclusive. If you grant mutually exclusive roles, HSP uses the role most recently granted. HTTP request syntax This section describes how to grant and revoke roles to non-ldap enabled tenant users. See "Granting and revoking roles to LDAP enabled tenant groups" on page 125 to grant and revoke roles to LDAP enabled tenant users. POST <user-id>/actions/grant Chapter 2: Using the HSP cluster management API 195

208 users Or: POST <user-id>/actions/revoke Request The <user-id> is the ID of the user that you want to grant or revoke a role and is supplied in the URL. In addition, the action that you want to take (grant or revoke) is also specified in the URL. The grant or revoke action is repeated in the request body, along with the required property and its corresponding value: role-id (required) string Specify the tenant user role that you want to grant or revoke. For example, the body of the request for granting a role would be specified as: { "grant": { "role-id": "string" } } For example, the body of the request for revoking a role would be specified as: { "revoke": { "role-id": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page Chapter 2: Using the HSP cluster management API

209 users Chapter 2: Using the HSP cluster management API 197

210 users Editing the properties of a user account You can edit the properties of an existing user account, with the exception of name. Important: If you need to change the name of a user account, you will need to create a new user account and then delete the old user account. You can edit properties that will provide the capability for the user to receive regarding HSP alert conditions. You must, however, configure SMTP before the user can receive alert-related s. See "Editing the SMTP configuration properties" on page 37 for details. HTTP request syntax Request POST The <user-id> is the ID of the user account on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: enabled boolean Whether or not the user account is enabled. first-name string User s first name. By default, the user account is enabled. Because there is only one tenant administrator, you cannot disable that user. Specify either true or false (case sensitive). First names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). 198 Chapter 2: Using the HSP cluster management API

211 users (Continued) last-name string User s last name. Last names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). primary- string User account s primary address to which to send subscribed to alert condition notifications. boolean Whether or not the user is subscribed to receive critical alert notifications. error-alert-conditions boolean Whether or not the user is subscribed to receive error alert notifications. critical-alertconditions warning-alertconditions boolean Whether or not the user is subscribed to receive warning alert notifications. secondary- string Additional address to which to send subscribed to alert condition notifications. password string User s password, shown as asterisks (***), not in clear text. Passwords can be from 1 to 255 characters and can contain any UTF-8 characters except ; (semicolon). cluster-name string Name of the cluster to which the user account is associated. cluster-id string ID of the cluster to which the user account is associated. tenant-name string Name of the tenant to which the user account is associated. tenant-id string ID of the tenant to which the user account is associated. description string Description of the user account. Free-flowing text, allowing up to 255 characters except ; (semicolon). Chapter 2: Using the HSP cluster management API 199

212 users (Continued) tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). type string Type of the user account: ADMIN TENANT-ADMIN TENANT-USER Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/users Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 200 Chapter 2: Using the HSP cluster management API

213 users Deleting a user account HTTP request syntax Request Response Example When you delete a user account, that user will no longer be available to perform any HSP management operations. You cannot delete all of the cluster administrator accounts at least one cluster user account must be retained to manage the HSP cluster. You cannot delete the tenant administrator account there is only one tenant administrator and that account must be retained to manage the tenancy. DELETE The <user-id> is the ID of the user account that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/users Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 2: Using the HSP cluster management API 201

214 202 Chapter 2: Using the HSP cluster management API

215 3 Using the HSP VM management API HSP provides the capability to host virtual machine images on the nodes of an HSP cluster to run applications on the same machines where the data for those applications resides. To ensure high availability, the HSP software monitors both node and VM health and attempts to failover and bring VM instances back online when a node goes down. You can use the HSP management API to perform the administrative tasks needed to manage the virtual machine environment running on the cluster. These APIs are described by an HTTP request that defines the supported operations for each virtual machine resource. The key to a successful virtual machine environment on an HSP cluster is not to over provision the VMs. The HSP software does provide some limits to help ensure VMs are not over provisioned in the cluster. These limits can deny that a VM be placed on a node that does not have enough memory. Here are important things to understand about VM provisioning: The memory limit for VMs is 2/3 of installed physical memory on a node. VM deployments are "all or nothing." If the HSP software cannot place all the requested VMs, the request fails with an error message. You can then choose between requesting a smaller number of VMs, requesting a smaller amount of memory for the VMs, or stopping other VMs to make room for the new ones. Placement for a VM failover is also subject to over provisioning limits. To successfully failover all of the VMs if a node goes down, you need to ensure you have enough unallocated memory on the rest of the nodes to handle the failover from the downed node. Chapter 3: Using the HSP VM management API 203

216 vm-templates We recommend deploying larger VMs before smaller ones, so that multiple small VMs do not consume so many resources that there is not enough memory on any one node to place the larger VM, even though the cluster as a whole has enough memory. This section describes the HSP management API for the following supported virtual machine resources: Virtual machine templates: vm-templates Virtual machine instance groups: vm-instance-groups Virtual machine sizes: vm-sizes Virtual machine instances: vm-instances Virtual machine volumes: vm-volumes Virtual machine snapshots: VM instance snapshots Here are some best practices to keep in mind vm-templates Virtual machine templates are used to install and manage the disk images used by the virtual machine software on HSP cluster nodes. Templates are either regular or golden. A golden template cannot be modified, which protects the contents of the image file. Golden templates let you distribute a base template that others can copy (clone) and modify to suit their needs. Say that you have a template that contains an image of the Linux operating system. This is considered a golden template because you want the applications deployed on your HSP cluster to run on the same version of Linux. Your applications team can clone this golden template and edit it to install Hadoop or other analytic application. Here is a summary of the steps required to get a virtual machine environment up and running on the Hyper Scale-Out Platform: 1. Copy the VM template to a shared out file system and add the VM template to HSP configuration so that it can be managed. 204 Chapter 3: Using the HSP VM management API

217 vm-templates 2. Clone the VM template if it is a protected golden template. (Cloning is not required for regular templates.) 3. Verify the properties associated with the template before instances and/or instance groups are deployed and make any necessary edits. If you have changed the base template considerably and you no longer want anyone to use an old template, you can delete a template. The following management operations are supported for the vm-templates resource: Getting a list of VM template URLs Getting the properties of a VM template Getting the properties of all VM templates Adding a VM template Cloning a VM template Editing the properties of a VM template Deleting a VM template Getting a list of VM template URLs HTTP request syntax Request Response Using the GET HTTP method on the vm-templates resource retrieves a list of URL links to the VM templates found. GET There are no request parameters needed for the GET request for vm-templates. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the VM templates found. Chapter 3: Using the HSP VM management API 205

218 vm-templates Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-templates Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of a VM template HTTP request syntax Request Response You can get the properties of a particular VM template by supplying the URL link to any VM template that was retrieved with the GET HTTP method on the vm-templates (see "Getting a list of VM template URLs" on the previous page). GET Supply the URL link to the VM template for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM template. is-golden boolean Whether or not this template is a golden image. By default, is-golden is set to to true. image-path string Path to the bootable VM disk image file. 206 Chapter 3: Using the HSP VM management API

219 vm-templates (Continued) image-format string Format of the image file. The supported image formats are: auto-detect qcow2 raw By default, the software automatically detects whether the image format is raw or qcow2. creation-time number Time stamp of when the virtual machine template was created. modification-time number Time stamp of when the virtual machine template was modified. The modification time stamp is different from creation time when the virtual machine template was modified in sandbox mode. cluster-name string Name of the cluster to which the virtual machine template is associated. cluster-id string ID of the cluster to which the virtual machine template is associated. tenant-name string Name of the tenant who owns/manages the virtual machine template. tenant-id string ID of the tenant who owns/manages the virtual machine template. description string Description of the VM template. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-templates Chapter 3: Using the HSP VM management API 207

220 vm-templates Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of all VM templates HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the vm-templates resource retrieves the properties for all of the VM templates. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM template. is-golden boolean Whether or not this template is a golden image. By default, is-golden is set to to true. image-path string Path to the bootable VM disk image file. image-format string Format of the image file. The supported image formats are: auto-detect qcow2 raw By default, the software automatically detects whether the image format is raw or qcow Chapter 3: Using the HSP VM management API

221 vm-templates (Continued) creation-time number Time stamp of when the virtual machine template was created. modification-time number Time stamp of when the virtual machine template was modified. The modification time stamp is different from creation time when the virtual machine template was modified in sandbox mode. cluster-name string Name of the cluster to which the virtual machine template is associated. cluster-id string ID of the cluster to which the virtual machine template is associated. tenant-name string Name of the tenant who owns/manages the virtual machine template. tenant-id string ID of the tenant who owns/manages the virtual machine template. description string Description of the VM template. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-templates Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Adding a VM template Adding a VM template is the first HSP management API task you need to perform to get your virtual machine environment up and running. Chapter 3: Using the HSP VM management API 209

222 vm-templates HTTP request syntax Request Prior to adding the VM template, you need to copy the bootable disk image file to a shared out HSP file system. A shared out file system is one that has both a share and access rule created and is available for client connections. POST Specify the properties for the VM template: name (required) string Name of the VM template. Supply either a name for the VM template or enter auto-generate. The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. VM template names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). is-golden boolean Whether or not this template is a golden image. By default, is-golden is set to to true. Specify either true or false (case sensitive). image-path (required) string Path to the bootable VM disk image file. Specify the path in the following format: <share_name>:/full/path/to/image_file_name.img For example: vm_images:cirros_vm/cirros x86_64-disk.img 210 Chapter 3: Using the HSP VM management API

223 vm-templates (Continued) image-format string Format of the image file. The supported image formats are: auto-detect qcow2 raw By default, if not specified when adding or editing a VM template, the software automatically detects whether the image format is raw or qcow2. description string Description of the VM template. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example Prior to adding a template, you need to copy the bootable disk image to a directory on a shared out HSP file system. A shared out file system is one that has both a share and access rule created and is available for client connections. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-templates Chapter 3: Using the HSP VM management API 211

224 vm-templates Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Cloning a VM template HTTP request syntax Request The contents of a golden template are protected. However, you can modify or deploy a golden image by first copying or cloning that template. You can also clone a regular template if you want to make additional changes while preserving the original template. Cloning a template creates a new copy of the template. This includes creating a new directory, and creating a copy of the VM image file and the xml configuration file of the source template. This new template directory is created at the same path level as the source template. So if the golden template was located at <share>:/path/to/goldentemplate, the clone would be created as <share>:/path/to/uuid_of_new_template. The directory name of the cloned template is the UUID of the new template. POST actions/clone The <vm-template-id> is the ID of the template that you want to clone and is supplied in the URL. In addition, the action that you want to take on that ID is also specified in the URL. The named action is repeated in the request body, along with any required and optional properties and their corresponding values for the clone action: 212 Chapter 3: Using the HSP VM management API

225 vm-templates clone-name (required) string Name of the cloned VM template. Supply either a name for the VM template or enter auto-generate. The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. VM template clone names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). description string Description of the VM template clone. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). For example, the body of the request would be specified as: { "clone": { "clone-name": "string", "description": "string", "tags": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Chapter 3: Using the HSP VM management API 213

226 vm-templates Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-templates Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Editing the properties of a VM template HTTP request syntax Request You can edit only a few properties associated with a template. POST The <vm-template-id> is the ID of the template on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: name string Name of the VM template. VM template names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). 214 Chapter 3: Using the HSP VM management API

227 vm-templates (Continued) image-format string Format of the image file. The supported image formats are: auto-detect qcow2 raw By default, if not specified when adding or editing a VM template, the software automatically detects whether the image format is raw or qcow2. description string Description of the VM template. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-templates Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 3: Using the HSP VM management API 215

228 vm-templates Deleting a VM template HTTP request syntax Request Response Example Deleting a VM template will delete and remove the template from HSP administrative control. Use this command only if you no longer want add VM instance groups or instances using this VM template. DELETE Or: DELETE The <vm-template-id> is the ID of the template that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-templates Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 216 Chapter 3: Using the HSP VM management API

229 vm-sizes vm-sizes The VM size resource defines the maximum CPU and memory resources available to a VM instance. For best VM performance and cluster performance, we recommend taking care not to over or under specify these resources for your application. You can specify one of the HSP pre-defined VM sizes or you can define a custom VM size. The following management operations are supported for the vm-sizes resource: Getting a list of VM template URLs Getting the properties of a VM size Getting the properties of all VM sizes Adding a VM size Editing the properties of a VM size Deleting a VM size Getting a list of VM size URLs HTTP request syntax Request Response Using the GET HTTP method on the vm-sizes resource retrieves a list of URL links to the VM sizes found. GET There are no request parameters needed for the GET request for vm-sizes. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the VM sizes found. Chapter 3: Using the HSP VM management API 217

230 vm-sizes Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-sizes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of a VM size HTTP request syntax Request Response You can get the properties of a particular VM template by supplying the URL link to any VM template that was retrieved with the GET HTTP method on the vm-sizes (see "Getting a list of VM template URLs" on page 205). GET Supply the URL link to the VM size for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name (required) string Name of the VM size. The current version of the software provides the following pre-defined sizes: jumbo If the vm-size is jumbo, then memory size is bytes (16 GiB) and the number of CPUs is 4. large If the vm-size is large, then memory size is bytes (8 GiB) and the number of CPUs is Chapter 3: Using the HSP VM management API

231 vm-sizes (Continued) medium If the vm-size is medium, then memory size is bytes (4 GiB) and the number of CPUs is 2. small If the vm-size is small, then memory size is bytes (2 GiB) and the number of CPUs is 1. tiny If the vm-size is tiny, then memory size is bytes (128 GiB) and the number of CPUs is 1. You can also define a custom VM size to fit your needs. See "Adding a VM size" on page 222 Supply either a name for the VM size or enter autogenerate. The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. VM size names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). memory-size (required) num-cpus (required) number number Amount of memory allowed for a VM instance resource. You can specify a memory size from bytes (512 MiB) to bytes (128 GiB). Number of CPUs allowed for a VM instance resource. You can specify from 1 to 8 CPUs. cluster-name string Name of the cluster to which the VM size is associated. cluster-id string ID of the cluster to which the VM size is associated. tenant-name string Name of the tenant associated with the VM size. tenant-id string ID of the tenant associated with the VM size. description string Description of the VM size. Free-flowing text, allowing up to 255 characters except ; (semicolon). Chapter 3: Using the HSP VM management API 219

232 vm-sizes (Continued) tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-sizes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of all VM sizes HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the vm-sizes resource retrieves the properties for all of the VM templates. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM size. 220 Chapter 3: Using the HSP VM management API

233 vm-sizes (Continued) The current version of the software provides the following pre-defined sizes: jumbo If the vm-size is jumbo, then memory size is bytes (16 GiB) and the number of CPUs is 4. large If the vm-size is large, then memory size is bytes (8 GiB) and the number of CPUs is 2. medium If the vm-size is medium, then memory size is bytes (4 GiB) and the number of CPUs is 2. small If the vm-size is small, then memory size is bytes (2 GiB) and the number of CPUs is 1. tiny If the vm-size is tiny, then memory size is bytes (128 GiB) and the number of CPUs is 1. You can also define a custom VM size to fit your needs. See "Adding a VM size" on the next page memory-size number Amount of memory allowed for a VM instance resource. num-cpus number Number of CPUs allowed for a VM instance resource. cluster-name string Name of the cluster to which the VM size is associated. cluster-id string ID of the cluster to which the VM size is associated. tenant-name string Name of the tenant associated with the VM size. tenant-id string ID of the tenant associated with the VM size. description string Description of the VM size. tags string User-defined tags that can be used to organize and/or filter the response results. Chapter 3: Using the HSP VM management API 221

234 vm-sizes Example Adding a VM size HTTP request syntax Request A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-sizes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. If the predefined HSP VM sizes do not suit your needs, you can add a VM size that can customize the CPU and memory resources you require. POST Specify the properties for the VM template: name (required) memory-size (required) num-cpus (required) string number number Name of the VM size. Supply either a name for the VM size or enter autogenerate. The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. VM size names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). Amount of memory allowed for a VM instance resource. You can specify a memory size from bytes (512 MiB) to bytes (128 GiB). Number of CPUs allowed for a VM instance resource. You can specify from 1 to 8 CPUs. 222 Chapter 3: Using the HSP VM management API

235 vm-sizes (Continued) description string Description of the VM size. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-sizes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Editing the properties of a VM size HTTP request syntax You can edit the properties any of the VM sizes, including the predefined HSP VM sizes. POST Chapter 3: Using the HSP VM management API 223

236 vm-sizes Request The <vm-template-id> is the ID of the template on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: name string Name of the VM size. VM size names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). memory-size number Amount of memory allowed for a VM instance resource. You can specify a memory size from bytes (512 MiB) to bytes (128 GiB). num-cpus number Number of CPUs allowed for a VM instance resource. You can specify from 1 to 8 CPUs. description string Description of the VM size. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page Chapter 3: Using the HSP VM management API

237 vm-sizes Example Deleting a VM size HTTP request syntax A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-sizes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. You can delete any of the VM sizes, including the predefined HSP VM sizes. DELETE Request Response Example The <vm-size-id> is the ID of the VM size that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-sizes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 3: Using the HSP VM management API 225

238 vm-instance-groups vm-instance-groups VM instance groups provide a way for you to manage a group of instances that operate together. Instances that belong to an instance groups can have different size limit attributes and even use different VM templates. Complex analytic setups often require multiple products. A data analysis example, might require cooperating virtual machines for Hadoop, Cassandra, a relational DB, and Pentaho. Being able to group these virtual machines together in a virtual abstraction makes it easier to manage them as a unit. The following management operations are supported for the vm-instance-groups resource: Getting a list of VM instance URLs Getting the properties of a VM instance Getting the properties of all VM instances Adding a VM instance group Deleting a VM instance group In addition, you can perform the following management operations on the VM instances that belong to a VM instance group: Adding VM instances to a VM instance group Editing the properties of a VM instance group Deleting VM instances from a VM instance group Powering on the VM instances in a VM instance group Shutting down the VM instances in a VM instance group Getting a list of VM instance group URLs Using the GET HTTP method on the vm-instance-groups resource retrieves a list of URL links to the VM instance groups found. 226 Chapter 3: Using the HSP VM management API

239 vm-instance-groups HTTP request syntax Request Response Example GET There are no request parameters needed for the GET request for vm-instance-groups. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the VM instance groups found. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of a VM instance group HTTP request syntax Request You can get the properties of a particular VM instance group by supplying the URL link to any VM instance group that was retrieved with the GET HTTP method on the vm-instance-groups (see "Getting a list of VM instance group URLs" on the previous page). GET <vm-instance-group-id> Supply the URL link to the VM instance group for which you want the list of properties. Chapter 3: Using the HSP VM management API 227

240 vm-instance-groups Response In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM instance group. num-instances number Number of instances in the VM instance group. vm-instance-list-uri uri Link to the VM instances in the VM instance group and their associated properties. cluster-name string Name of the cluster to which the VM instance group is associated. cluster-id string ID of the cluster to which the VM instance group is associated. tenant-name string Name of the tenant who owns/manages the VM instance group. tenant-id string ID of the tenant who owns/manages the VM instance group. description string Description of the VM instance group. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of all VM instance groups Supplying an additional list directive to the GET HTTP method on the vm-instance-groups resource retrieves the properties for all of the VM instances. 228 Chapter 3: Using the HSP VM management API

241 vm-instance-groups HTTP request syntax Request Response GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM instance group. num-instances number Number of instances in the VM instance group. vm-instance-list-uri uri Link to the VM instances in the VM instance group and their associated properties. cluster-name string Name of the cluster to which the VM instance group is associated. cluster-id string ID of the cluster to which the VM instance group is associated. tenant-name string Name of the tenant who owns/manages the VM instance group. tenant-id string ID of the tenant who owns/manages the VM instance group. description string Description of the VM instance group. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Chapter 3: Using the HSP VM management API 229

242 vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Adding a VM instance group You can add a VM instance group to manage a group of virtual machine instances that operate together. HSP provides two approaches to setting up VM instance groups: You can add an "empty" instance group to which you can add multiple instances with the same sizing attributes (CPU and memory) or individual instances that have dissimilar sizing attributes. You can add multiple instances with the same sizing attributes (CPU and memory) at the same time that you create the instance group. The properties that you specify when adding a VM instance group depend on which approach you are taking. The property table below will guide you, so read the property descriptions carefully. No matter which approach you use, you can add instances to or delete instances from a VM instance group at any time. An IP address is required for each VM instance. If you do not have sufficient IP addresses, the deployment will fail. You need to decide if you are going to allocate these addresses from a pool of HSP-managed IP addresses or you are going to use IP addresses managed from some external source (for example, DHCP). See "Adding an IP address" on page 87 for information about adding HSP-managed IP addresses. If you are going to manage IP addresses outside the cluster, you may need to run the VM instance in sandbox mode and set up the address management. See "Working with a VM instance in sandbox mode" on page 254. If you are adding multiple instances at the same time, HSP names the instances for you. If you are adding a single instance, you have the option to name the instance. The default name format of a virtual machine instance depends on which kind of IP address that you use. If you are using the pool of HSP-managed IP addresses, the default instance name will include the IP address itself, something like vm If you use IP addresses from an external 230 Chapter 3: Using the HSP VM management API

243 vm-instance-groups HTTP request syntax Request source, the default instance name will include the deploying template name, something like <template_name>-vm-1. In either case, the number at the end will increment for each instance deployed. POST Specify the properties for the VM instance group: name (required) string Name of the VM instance group. Supply either a name for the VM instance group or enter auto-generate. The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. Name is the only property you need to specify if you are adding an "empty" VM instance group and are not adding instances at the same time (numinstances is not specified). vm-template-id (required only if num-instances is specified) vm-size-id (required only if num-instances is specified) string string VM instance group names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). VM template to use for any VM instances added during VM instance group creation. VM size to use for any VM instances added during VM instance group creation. The current version of the software provides the following predefined sizes: jumbo If the vm-size is jumbo, then memory size is bytes (16 GiB) and the number of CPUs is 4. Chapter 3: Using the HSP VM management API 231

244 vm-instance-groups (Continued) large If the vm-size is large, then memory size is bytes (8 GiB) and the number of CPUs is 2. medium If the vm-size is medium, then memory size is bytes (4 GiB) and the number of CPUs is 2. small If the vm-size is small, then memory size is bytes (2 GiB) and the number of CPUs is 1. tiny If the vm-size is tiny, then memory size is bytes (128 GiB) and the number of CPUs is 1. You can also define a custom VM size to fit your needs. See "Adding a VM size" on page 222 Supply either a name for the VM size or enter autogenerate. The auto-generate option uses the UUID for the name, so we recommend that you specify a more human readable form for the name. VM size names can be from 1 to 255 characters and can contain any UTF-8 characters. num-instances number Number of VM instances to add to the VM instance group during creation. If you want to add one or more instances at the same time you are adding the VM instance group, specify the number of instances that you want to add. If you add instances, you also need to specify the VM template and the VM size to use for the instances. use-address-pool boolean Whether or not IP assignments are to be made from the pool of IP addresses already designated for virtual machine instance use. By default, the HSP address pool designated for virtual machines is used to make IP address assignments. Specify either true or false (case sensitive). 232 Chapter 3: Using the HSP VM management API

245 vm-instance-groups (Continued) description string Description of the VM instance group. tags string User-defined tags that can be used to organize and/or filter the response results. Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Deleting VM instances from a VM instance group HTTP request syntax Request Deleting a VM template will delete and remove the template from HSP administrative control. Use this command only if you no longer want add VM instance groups or instances using this VM template. POST <vm-instance-group-id>/actions/delete-instances The <vm-instance-group-id> is the ID of the VM instance group from which you want to delete VM instances and is supplied in the URL. In addition, the action that you want to take (delete-instances) is also specified in the URL. Chapter 3: Using the HSP VM management API 233

246 vm-instance-groups The delete-instances action is repeated in the request body, along with the required and optional properties and their corresponding values: instance-id-list (required) string Comma separated list of VM instances that you want to delete from the VM instance group. force string Whether or not to force the deletion of the VM instances on a node that have gone down or are not responding. Specify either true or false (case sensitive). For example, the body of the request would be specified as: { "delete-instances": { "instance-id-list": "string", "force": "false" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 234 Chapter 3: Using the HSP VM management API

247 vm-instance-groups Adding VM instances to a VM instance group HTTP request syntax Request You can add one or more instances to an existing VM instance group. You can add instances with the same or different VM template and/or VM size attributes as other existing VM instances in the group. An IP address is required for each VM instance. If you do not have sufficient IP addresses, the deployment will fail. You need to decide if you are going to allocate these addresses from a pool of HSP-managed IP addresses or you are going to use IP addresses managed from some external source (for example, DHCP). See "Adding an IP address" on page 87 for information about adding HSP-managed IP addresses. If you are going to manage IP addresses outside the cluster, you may need to run the VM instance in sandbox mode and set up the address management. See "Working with a VM instance in sandbox mode" on page 254. If you are adding multiple instances at the same time, HSP names the instances for you. If you are adding a single instance, you have the option to name the instance. The default name format of a virtual machine instance depends on which kind of IP address that you use. If you are using the pool of HSP-managed IP addresses, the default instance name will include the IP address itself, something like vm If you use IP addresses from an external source, the default instance name will include the deploying template name, something like <template_name>-vm-1. In either case, the number at the end will increment for each instance deployed. POST <vm-instance-group-id>/actions/add-instances The <vm-instance-group-id> is the ID of the VM instance group to which you want to add instances and is supplied in the URL. In addition, the action that you want to take (add-instances) is also specified in the URL. Chapter 3: Using the HSP VM management API 235

248 vm-instance-groups The add-instances action is repeated in the request body, along with the required and optional properties and their corresponding values: vm-template-id string VM template to use for the VM instances being added. num-instances number Number of VM instances to add to the VM instance group during creation.number of instances in the VM instance group. If you want to add one or more instances at the same time you are adding the VM instance group, specify the number of instances that you want to add. If you add instances, you also need to specify the VM template and the VM size to use for the instances. vm-size-id string Size of the VM instances being added. use-address-pool boolean Whether or not IP assignments are to be made from the pool of IP addresses already designated for virtual machine instance use. By default, the HSP address pool for designated for virtual machines is used to make IP address assignments. Specify either true or false (case sensitive). instance-name string Name of the VM instance. Follow the RFC 1123 host name guidelines. Generally, instance names can be from 1 to 255 characters and can only contain: letters A-Z and a-z digits 0-9 hyphens (-) description string Description of the VM instance. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). 236 Chapter 3: Using the HSP VM management API

249 vm-instance-groups For example, the body of the request would be specified as: { "add-instances": { "vm-template-id": "string", "vm-size-id": "string", "num-instances": "string", "use-address-pool": true, "instance-name": "string", "description": "string", "tags": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Powering on the VM instances in a VM instance group HTTP request syntax You can power on a group of VM instances that are associated with a VM instance group. POST <vm-instance-group-id>/actions/power-on-instances Chapter 3: Using the HSP VM management API 237

250 vm-instance-groups Request Response Examples The <vm-instance-group-id> is the ID of the instance group on which you want to perform the power on action and is supplied in the URL. In addition, the power-on-instances action is also specified in the URL. The power-on-instances action is repeated in the request body without any additional properties. For example, the body of the request would be specified as: { "power-on-instances": {} } The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Shutting down the VM instances in a VM instance group HTTP request syntax You can shut down a group of VM instances that are associated with a VM instance group. POST <vm-instance-group-id>/actions/shutdown-instances 238 Chapter 3: Using the HSP VM management API

251 vm-instance-groups Request The <vm-instance-group-id> is the ID of the instance group on which you want to perform the shut down action and is supplied in the URL. In addition, the shutdown-instances action is also specified in the URL. The shutdown-instances action is repeated in the request body without any additional properties. For example, the body of the request would be specified as: { "shutdown-instances": {} } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting a list of VM instances associated with a VM instance group You can list the VM instances that are associated with a VM instance group. Chapter 3: Using the HSP VM management API 239

252 vm-instance-groups HTTP request syntax Request Response Use the link returned in the vm-instance-list-uri property for any VM instance group that was retrieved with the GET HTTP method on the vminstance-groups (see "Getting the properties of a VM instance group" on page 227 or "Getting the properties of all VM instance groups"). GET <vm-instance-groups-id>/vm-instance-list Supply the URL link to the VM instance group for which you want the list of properties. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties for each VM instance in the response: name string Name of the VM instance. The name you use also sets the hostname for the guest operating system. run-state string Run state of the VM instance: UP Instance is running. DOWN Instance or template deploying the instance has been shut down. ip-address string IP address of the node on which the VM instance is running. mac-address number MAC address of the node on which the VM instance is running. vnc-address number VNC address provides console or desktop access to the VM instance through a VNC viewer client. memory-size number Amount of memory allowed for the VM instance resource. 240 Chapter 3: Using the HSP VM management API

253 vm-instance-groups (Continued) num-cpus number Number of CPUs allowed for the VM instance resource. image-path string Path to the bootable VM disk image file. image-format string Format of the VM image file. The supported image formats are: auto-detect qcow2 raw By default, the software automatically detects whether the image format is raw or qcow2. is-sandbox boolean A VM instance in sandbox mode is running a single instance of the actual template, not a copy of the template. You can edit the contents of a VM instance that is running in sandbox mode. By default, is-sandbox is set to false. disk string The list of local disks attached to the VM instance. vm-snapshots-uri uri Link to the VM snapshots and their associated properties. vm-template-name string Name of the VM template to which the VM instance is associated. vm-template-id string ID of the VM template to which the VM instance is associated. vm-side-name string Name of the VM template to which the VM instance is associated. vm-size-id string ID of the VM template to which the VM instance is associated. vm-instance-groupname vm-instance-groupid string string Name of the VM instance group to which the VM instance is associated. ID of the VM instance group to which the VM instance is associated. Chapter 3: Using the HSP VM management API 241

254 vm-instance-groups (Continued) host-node-name string Host name of the node on which the VM instance is running. host-node-id string Host ID of the node on which the VM instance is running. cluster-name string Name of the cluster to which the VM instance is associated. cluster-id string ID of the cluster to which the VM instance is associated. tenant-name string Name of the tenant who owns/manages the VM instance. tenant-id string ID of the tenant who owns/manages the VM instance. description string Description of the VM instance. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Editing the properties of a VM instance group HTTP request syntax You can edit only a few properties associated with a VM instance group. POST Chapter 3: Using the HSP VM management API

255 vm-instance-groups Request The <vm-instance-group-id> is the ID of the cluster on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: name string Name of the VM instance group. VM instance group names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). description string Description of the VM instance group. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Chapter 3: Using the HSP VM management API 243

256 vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Deleting a VM instance group Deleting a VM instance group will remove the group and associated instances from HSP administrative control. Use this command only if you no longer want to manage instances using this VM instance group. Note: If the VM instance group you want to delete has running instances, you need to shut down those instances before you can delete the VM instance group. HTTP request syntax DELETE <vm-instance-group-id> Request Response Example The <vm-instance-group-id> is the ID of the instance group that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instance-groups Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 244 Chapter 3: Using the HSP VM management API

257 vm-instances vm-instances You can run VM instances on HSP nodes. The following management operations are supported for the vm-instances resource: Getting a list of VM instance URLs Getting the properties of a VM instance Getting the properties of all VM instances Adding VM instances Working with a VM instance in sandbox mode Editing the properties of a VM instance Attaching a disk to a VM instance Detaching a disk from a VM instance Rebooting a VM instance Migrating a VM instance Shutting down a VM instance Powering on a VM instance Deleting a VM instance The following snapshot management operations are supported for the vm-instances resource: Getting a list of the VM snapshots for an instance Adding a VM snapshot Editing a VM snapshot Reverting a VM snapshot Deleting a VM snapshot Chapter 3: Using the HSP VM management API 245

258 vm-instances Getting a list of VM instance URLs HTTP request syntax Request Response Example Using the GET HTTP method on the vm-instances resource retrieves a list of URL links to the VM instances found. GET There are no request parameters needed for the GET request for vm-instances. In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the VM instances found. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of a VM instance HTTP request syntax Request You can get the properties of a particular VM instance by supplying the URL link to any VM instance that was retrieved with the GET HTTP method on the vm-instances (see "Getting a list of VM instance URLs" above). GET Supply the URL link to the VM instance for which you want the list of properties. 246 Chapter 3: Using the HSP VM management API

259 vm-instances Response In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM instance. The name you use also sets the hostname for the guest operating system. run-state string Run state of the VM instance: UP Instance is running. DOWN Instance or template deploying the instance has been shut down. ip-address string IP address of the node on which the VM instance is running. mac-address number MAC address of the node on which the VM instance is running. vnc-address number VNC address provides console or desktop access to the VM instance through a VNC viewer client. memory-size number Amount of memory allowed for the VM instance resource. num-cpus number Number of CPUs allowed for the VM instance resource. image-path string Path to the bootable VM disk image file. image-format string Format of the VM image file. The supported image formats are: auto-detect qcow2 raw By default, the software automatically detects whether the image format is raw or qcow2. Chapter 3: Using the HSP VM management API 247

260 vm-instances (Continued) is-sandbox boolean A VM instance in sandbox mode is running a single instance of the actual template, not a copy of the template. You can edit the contents of a VM instance that is running in sandbox mode. By default, is-sandbox is set to false. disk string The list of local disks attached to the VM instance. vm-snapshots-uri uri Link to the VM snapshots and their associated properties. vm-template-name string Name of the VM template to which the VM instance is associated. vm-template-id string ID of the VM template to which the VM instance is associated. vm-side-name string Name of the VM template to which the VM instance is associated. vm-size-id string ID of the VM template to which the VM instance is associated. vm-instance-groupname vm-instance-groupid string string Name of the VM instance group to which the VM instance is associated. ID of the VM instance group to which the VM instance is associated. host-node-name string Host name of the node on which the VM instance is running. host-node-id string Host ID of the node on which the VM instance is running. cluster-name string Name of the cluster to which the VM instance is associated. cluster-id string ID of the cluster to which the VM instance is associated. tenant-name string Name of the tenant who owns/manages the VM instance. tenant-id string ID of the tenant who owns/manages the VM instance. description string Description of the VM instance. 248 Chapter 3: Using the HSP VM management API

261 vm-instances (Continued) tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of all VM instances HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the vm-instances resource retrieves the properties for all of the VM instances. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM instance. The name you use also sets the hostname for the guest operating system. Chapter 3: Using the HSP VM management API 249

262 vm-instances (Continued) run-state string Run state of the VM instance: UP Instance is running. DOWN Instance or template deploying the instance has been shut down. ip-address string IP address of the node on which the VM instance is running. mac-address number MAC address of the node on which the VM instance is running. vnc-address number VNC address provides console or desktop access to the VM instance through a VNC viewer client. memory-size number Amount of memory allowed for the VM instance resource. num-cpus number Number of CPUs allowed for the VM instance resource. image-path string Path to the bootable VM disk image file. image-format string Format of the VM image file. The supported image formats are: auto-detect qcow2 raw By default, the software automatically detects whether the image format is raw or qcow2. is-sandbox boolean A VM instance in sandbox mode is running a single instance of the actual template, not a copy of the template. You can edit the contents of a VM instance that is running in sandbox mode. By default, is-sandbox is set to false. disk string The list of local disks attached to the VM instance. vm-snapshots-uri uri Link to the VM snapshots and their associated properties. 250 Chapter 3: Using the HSP VM management API

263 vm-instances (Continued) vm-template-name string Name of the VM template to which the VM instance is associated. vm-template-id string ID of the VM template to which the VM instance is associated. vm-side-name string Name of the VM template to which the VM instance is associated. vm-size-id string ID of the VM template to which the VM instance is associated. vm-instance-groupname vm-instance-groupid string string Name of the VM instance group to which the VM instance is associated. ID of the VM instance group to which the VM instance is associated. host-node-name string Host name of the node on which the VM instance is running. host-node-id string Host ID of the node on which the VM instance is running. cluster-name string Name of the cluster to which the VM instance is associated. cluster-id string ID of the cluster to which the VM instance is associated. tenant-name string Name of the tenant who owns/manages the VM instance. tenant-id string ID of the tenant who owns/manages the VM instance. description string Description of the VM instance. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Chapter 3: Using the HSP VM management API 251

264 vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Adding VM instances HTTP request syntax You can add a VM instance to an existing VM instance group or you can add a standalone instance. Adding an VM instance starts the guest operating system for the instance. An IP address is required for each VM instance. If you do not have sufficient IP addresses, the deployment will fail. You need to decide if you are going to allocate these addresses from a pool of HSP-managed IP addresses or you are going to use IP addresses managed from some external source (for example, DHCP). See "Adding an IP address" on page 87 for information about adding HSP-managed IP addresses. If you are going to manage IP addresses outside the cluster, you may need to run the VM instance in sandbox mode and set up the address management. See "Working with a VM instance in sandbox mode" on page 254. If you are adding multiple instances at the same time, HSP names the instances for you. If you are adding a single instance, you have the option to name the instance. The default name format of a virtual machine instance depends on which kind of IP address that you use. If you are using the pool of HSP-managed IP addresses, the default instance name will include the IP address itself, something like vm If you use IP addresses from an external source, the default instance name will include the deploying template name, something like <template_name>-vm-1. In either case, the number at the end will increment for each instance deployed. POST Chapter 3: Using the HSP VM management API

265 vm-instances Request Specify the properties for the VM instance: name (required) string Name of the VM instance. The name you use also sets the hostname for the guest operating system. Follow the RFC 1123 host name guidelines. VM instance names can be from 1 to 255 characters and can only contain: vm-template-id (required) vm-size-id (required) string string letters A-Z and a-z digits 0-9 hyphens (-) VM template to use for the VM instances being added. Size of the VM instances being added. use-address-pool boolean Whether or not IP assignments are to be made from the pool of IP addresses already designated for virtual machine instance use. By default, the HSP address pool for designated for virtual machines is used to make IP address assignments. Specify either true or false (case sensitive). is-sandbox boolean A VM instance in sandbox mode is running a single instance of the VM template image. You can edit the contents of a VM instance that is running in sandbox mode. By default, is-sandbox is set to false. Specify either true or false (case sensitive). tenant-id string Tenant who owns/manages the VM instance. Chapter 3: Using the HSP VM management API 253

266 vm-instances (Continued) disk string The list of local disks to which the VM instance has been attached. description string Description of the VM instance. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Working with a VM instance in sandbox mode You can edit the contents of a copy of VM template image using a VM instance running in sandbox mode. You need to create an instance, specifying the sandbox property. Once you complete your edits to the image, you can delete the instance. 254 Chapter 3: Using the HSP VM management API

267 vm-instances Note: You cannot edit a golden template you can only edit a cloned copy of a golden template. You also cannot edit the VM image if that template is being used for other running VM instances. HTTP request syntax Request POST The <vm-instance-id> is the ID of the VM instance that you want to work with in sandbox mode and is supplied in the URL. Specify the properties for the VM instance and set is-sandbox to true (case sensitive): name (required) string Name of the VM instance. The name you use also sets the hostname for the guest operating system. Follow the RFC 1123 host name guidelines. VM instance names can be from 1 to 255 characters and can only contain: vm-template-id (required) vm-size-id (required) string string letters A-Z and a-z digits 0-9 hyphens (-) VM template to use for the VM instances being added. Size of the VM instances being added. Chapter 3: Using the HSP VM management API 255

268 vm-instances (Continued) use-address-pool boolean Whether or not IP assignments are to be made from the pool of IP addresses already designated for virtual machine instance use. By default, the HSP address pool for designated for virtual machines is used to make IP address assignments. Specify either true or false (case sensitive). is-sandbox boolean A VM instance in sandbox mode is running a single instance of the VM template image. You can edit the contents of a VM instance that is running in sandbox mode. By default, is-sandbox is set to false. Specify either true or false (case sensitive). tenant-id string Tenant who owns/manages the VM instance. disk string The list of local disks to which the VM instance has been attached. description string Description of the VM instance. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page Chapter 3: Using the HSP VM management API

269 vm-instances Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Editing the properties of a VM instance HTTP request syntax Request You can edit only a few properties associated with a virtual machine instance. POST The <vm-instance-id> is the ID of the cluster on which you want to edit properties and is supplied in the URL. Specify the properties and corresponding values for any of the following properties that you want to edit: name string Name of the VM instance. The name you use also sets the hostname for the guest operating system. Follow the RFC 1123 host name guidelines. VM instance names can be from 1 to 255 characters and can only contain: letters A-Z and a-z digits 0-9 hyphens (-) Chapter 3: Using the HSP VM management API 257

270 vm-instances (Continued) description string Description of the VM instance. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Rebooting a VM instance HTTP request syntax You can reboot a VM instance. POST <vm-instance-id>/actions/reboot 258 Chapter 3: Using the HSP VM management API

271 vm-instances Request The <vm-instance-id> is the ID of the VM instance that you want to reboot and is supplied in the URL. In addition, the action that you want to take (reboot) is also specified in the URL. The reboot action is repeated in the request body without any additional properties. For example, the body of the request would be specified as: { "reboot": {} } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Shutting down a VM instance HTTP request syntax You can shut down a particular VM instance. POST <vm-instance-id>/actions/shutdown Chapter 3: Using the HSP VM management API 259

272 vm-instances Request The <vm-instance-id> is the ID of the instance on which you want to perform the power on or shutdown action and is supplied in the URL. In addition, the action that you want to take (shutdown) is also specified in the URL. The shutdown action is repeated in the request body, along with the optional property and its corresponding value: force string Whether or not to force the shutdown of the VM instance. Specify either true or false (case sensitive). For example, the body of the request would be specified as: { "shutdown": { "force": "false" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. 260 Chapter 3: Using the HSP VM management API

273 vm-instances Powering on a VM instance HTTP request syntax Request Response Examples You can power on a particular VM instance. POST <vm-instance-id>/actions/power-on The <vm-instance-id> is the ID of the instance on which you want to perform the power on action and is supplied in the URL.In addition, the action that you want to take (power-on) is also specified in the URL. The reboot action is repeated in the request body without any additional properties. For example, the body of the request would be specified as: { "power-on": {} } The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Chapter 3: Using the HSP VM management API 261

274 vm-instances Migrating a VM instance If you need to shut down or retire a node, migration lets you to shutdown the running VM instance on one node and restart it on another node you specify. You can also use migration to manually load balance virtual machines when you are not satisfied with the automatic round robin placement scheme made the HSP software. Important: You cannot migrate VMs that have local virtual machine disks attached. Note: VM instance migration is not "live migration." The running VM instance is shut down and restarted as if the power button was cycled. We therefore recommend that you gracefully shut down any applications running on the virtual machine before migration. HTTP request syntax Request POST <vm-instance-id>/actions/migrate The <vm-instance-id> is the ID of the instance that you want to migrate and is supplied in the URL. In addition, the action that you want to take (migrate) is also specified in the URL. The migrate action is repeated in the request body, along with the optional property and its corresponding value: host-node-id (required) string Specify the node to which you want to migrate the VM instance. force-shutdown boolean Whether or not to force the shutdown of running instances. Specify the force option if you have not or were not able to shut down the instances gracefully. For example, the body of the request would be specified as: { "migrate": { "host-node-id": "string", 262 Chapter 3: Using the HSP VM management API

275 vm-instances "force-shutdown": "false" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Examples A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Deleting a VM instance HTTP request syntax Deleting a VM instance will shutdown the guest operating system and remove the instance from HSP administrative control. Use this command only if you no longer want to run the VM instance in an HSP cluster. DELETE Request Response The <vm-instance-id> is the ID of the instance that you want to delete and is supplied in the URL. The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous DELETE operation was successfully accepted for processing. Chapter 3: Using the HSP VM management API 263

276 VM instance snapshots Example The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. VM instance snapshots A virtual machine snapshot is a point-in-time picture of the state of a running VM instance when the snapshot is taken. The snapshot preserves both the disk state and memory state of the VM. Consider taking a VM snapshot periodically so that you have a stable state to revert to if something goes wrong. A snapshot would let you return the deployed and running VM instance back to a known good point. You can only snapshot instances deployed from a template with a qcow2 image format, raw image formats are not supported. Snapshots are kept in the same qcow2 file from which the instance is running. You can take as many snapshots as you have space for in your instance. So if you created a virtual machine with 50 GB of disk space, you can take snapshots until you run you run out of space. Snapshots are only retained for as long as the VM instance is running. Once a VM instance has been shutdown, all snapshots are deleted. Getting a list of the VM snapshots for an instance HTTP request syntax Using the GET HTTP method on the vm-snapshots resource for a VM instance retrieves a list of the VM snapshots and their properties. GET vm-snapshots 264 Chapter 3: Using the HSP VM management API

277 VM instance snapshots Request There are no request parameters needed for the GET request for vm-snapshots. Response In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of the VM instance snapshots found and the following snapshot properties in the response: name string Name of the VM snapshot. Names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). run-state string Run state of a VM snapshot: UP Snapshot that is the most current and from which the virtual machine is actively working from. There is only one snapshot that is UP. DOWN Older, nonactive snapshot. Virtual machines can be reverted to older, nonactive snapshots. creation-time number Time stamp of when the virtual machine snapshot was created. vm-instance-name string Name of the VM instance to which the VM snapshot is associated. vm-instance-id string ID of the VM instance to which the VM snapshot is associated. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Chapter 3: Using the HSP VM management API 265

278 VM instance snapshots Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Adding a VM snapshot Adds a snapshot of the specified VM instance. Note: You can only snapshot instances deployed from a template with a qcow2 image format, raw image formats are not supported. HTTP request syntax Request POST <vm-instance-id>/actions/add-vm-snapshot The <vm-instance-id> is the ID of the VM instance on which you want to add a VM snapshot and is supplied in the URL. In addition, the action that you want to take (add-vm-snapshot) is also specified in the URL. The add-vm-snapshot action is repeated in the request body, along with the required and optional properties and their corresponding values: name string Name of the VM snapshot. Names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). description string Description of the VM snapshot. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). 266 Chapter 3: Using the HSP VM management API

279 VM instance snapshots For example, the body of the request would be specified as: { "add-vm-snapshot": { "name": "string", "description": "string", "tags": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Editing a VM snapshot HTTP request syntax You can edit a snapshot of the specified VM instance. POST <vm-instance-id>/actions/edit-vm-snapshot Chapter 3: Using the HSP VM management API 267

280 VM instance snapshots Request The <vm-instance-id> is the ID of the VM instance on which you want to add a VM snapshot and is supplied in the URL. In addition, the action that you want to take (edit-vm-snapshot) is also specified in the URL. The edit-vm-snapshot action is repeated in the request body, along with the required and optional properties and their corresponding values: name string Name of the VM snapshot. Names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). description string Description of the VM snapshot. Free-flowing text, allowing up to 255 characters except ; (semicolon). tags string User-defined tags that can be used to organize and/or filter the response results. Free-flowing text, allowing up to 255 characters except ; (semicolon). Response For example, the body of the request would be specified as: { "edit-vm-snapshot": { "name": "string", "description": "string", "tags": "string" } } The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page Chapter 3: Using the HSP VM management API

281 VM instance snapshots Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Reverting a VM snapshot HTTP request syntax Request Reverts a snapshot of the specified VM instance back to the specified snapshot. POST <vm-instance-id>/actions/revert-vm-snapshot The <vm-instance-id> is the ID of the VM instance on which you want to add a VM snapshot and is supplied in the URL. In addition, the action that you want to take (revert-vm-snapshot) is also specified in the URL. The revert-vm-snapshot action is repeated in the request body, along with the required and optional properties and their corresponding values: name string Name of the VM snapshot. Names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). For example, the body of the request would be specified as: { "revert-vm-snapshot": { "name": "string" } } Chapter 3: Using the HSP VM management API 269

282 VM instance snapshots Response Example The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Deleting a VM snapshot HTTP request syntax Request You can delete a snapshot of the specified VM instance. POST <vm-instance-id>/actions/delete-vm-snapshot The <vm-instance-id> is the ID of the VM instance on which you want to add a VM snapshot and is supplied in the URL. In addition, the action that you want to take (delete-vm-snapshot) is also specified in the URL. The delete-vm-snapshot action is repeated in the request body, along with the required and optional properties and their corresponding values: name string Name of the VM snapshot. Names can be from 1 to 255 characters and can contain any UTF-8 characters except * (asterisk) and ; (semicolon). 270 Chapter 3: Using the HSP VM management API

283 VM instance snapshots For example, the body of the request would be specified as: { "delete-vm-snapshot": { "name": "string" } } Response The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Attaching a disk to a VM instance You can associate one or more existing VM volumes with a local HSP disk and attach the disk to a VM instance. You need to edit the role of the disk from cluster to virtual machine prior to adding volumes and associating them with a disk. Note: The VM instance may need to be rebooted before the VM disk is seen by the guest operating system. HTTP request syntax POST /actions/attach Chapter 3: Using the HSP VM management API 271

284 VM instance snapshots Request The <vm-instance-id> is the ID of the instance to which you want to attach the VM disk and is supplied in the URL. In addition, the action that you want to take (attach) is also specified in the URL. The attach action is repeated in the request body, along with the required property and its corresponding value: vm-disk string A comma-separated list of VM volumes to be associated with the disk and attached to the VM instance. In this version of the software, only local disks are supported. Specify the disk as one or more VM volumes: vm-volume-id=<id>,vm-volume-id=<id> Response Examples The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Detaching a disk from a VM instance You can detach one or more existing VM volumes from a local HSP disk that is attached to VM instance. 272 Chapter 3: Using the HSP VM management API

285 VM instance snapshots HTTP request syntax Request POST /actions/detach The <vm-instance-id> is the ID of the instance to which you want to detach the VM volumes associated with the VM disk and is supplied in the URL. In addition, the action that you want to take (detach) is also specified in the URL. The detach action is repeated in the request body, along with the required property and its corresponding value: vm-disk string A comma-separated list of VM volumes to be detached from the disk that is attached to the VM instance. In this version of the software, only local disks are supported. Specify the disk as one or more VM volumes: vm-volume-id=<id>,vm-volume-id=<id> Response Examples The status code is the most important part of the response header. What you are looking for is a status code of 202, which means that the asynchronous POST operation was successfully accepted for processing. The response also includes URL you can use with the GET method to track the asynchronous job. For more information, see "Getting the status of an asynchronous job" on page 12. A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-instances Chapter 3: Using the HSP VM management API 273

286 vm-volumes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. vm-volumes Some high availability applications, like Hadoop and NoSQL, need to manage their own storage and do not require the built-in high availability features of HSP. VM volumes let you manage the local volume space for virtual machines running in an HSP cluster. Having this dedicated storage improves the performance of applications that do a lot of small writes. VM volumes are created on an HSP disk and then attached to VM instances. Note: Only a cluster administrator can add, edit, or delete VM volumes. The following management operations are supported for the vm-volumes resource: Getting a list of VM volume URLs Getting the properties of a VM volume Getting the properties of all VM volumes Adding VM volumes Rebooting a VM instance Deleting a VM volume Getting a list of VM volume URLs HTTP request syntax Using the GET HTTP method on the vm-volumes resource retrieves a list of URL links to the disks found. GET Chapter 3: Using the HSP VM management API

287 vm-volumes Request There are no request parameters needed for the GET request for vm-volumes. Response In addition to the response header that provides the status code (200 if the request was successful), the request returns a list of URL links to the VM volumes found. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-volumes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of a VM volume HTTP request syntax Request You can get the properties of a particular VM volume by supplying the URL link to any volume that was retrieved with the GET HTTP method on the vm-volumes (see "Getting a list of disk URLs" on page 96). GET Supply the URL link to the VM volume for which you want the list of properties. Chapter 3: Using the HSP VM management API 275

288 vm-volumes Response In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM volume. run-state string Run state of the VM volume: UP VM Volume has been added and available for use. ERROR The underlying disk to which the VM volume is associated has failed. capacity number Capacity of the VM Volume. vm-instance-name string Name of the VM instance to which the VM volume is associated. vm-instance-id string ID of the VM instance to which the VM volume is associated. disk-name string The name of the disk to which the VM Volume is associated. disk-id string The ID of the disk to which the VM Volume is associated. source-dev-name target-dev-name The LVM2 volume device name on the host HSP node. Block device name inside the guest VM. cluster-name string Name of the cluster to which the VM volume is associated. cluster-id string ID of the cluster to which the VM volume is associated. tenant-id string The tenant who owns/manages the VM volume. tenant-name string Name of the tenant who owns/manages the VM volume. tenant-id string ID of the tenant who owns/manages the VM volume. 276 Chapter 3: Using the HSP VM management API

289 vm-volumes (Continued) description string Description of the VM volume. tags string User-defined tags that can be used to organize and/or filter the response results. Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-volumes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Getting the properties of all VM volumes HTTP request syntax Request Response Supplying an additional list directive to the GET HTTP method on the vm-volumes resource retrieves the properties for all of the VM volumes. GET There are no request parameters needed for the list GET request. In addition to the response header that provides the status code (200 if the request was successful), the request returns the following properties in the response: name string Name of the VM volume. Chapter 3: Using the HSP VM management API 277

290 vm-volumes (Continued) run-state string Run state of the VM volume: UP VM Volume has been added and available for use. ERROR The underlying disk to which the VM volume is associated has failed. capacity number Capacity of the VM Volume. vm-instance-name string Name of the VM instance to which the VM volume is associated. vm-instance-id string ID of the VM instance to which the VM volume is associated. disk-name string The name of the disk to which the VM Volume is associated. disk-id string The ID of the disk to which the VM Volume is associated. source-dev-name target-dev-name The LVM2 volume device name on the host HSP node. Block device name inside the guest VM. cluster-name string Name of the cluster to which the VM volume is associated. cluster-id string ID of the cluster to which the VM volume is associated. tenant-id string The tenant who owns/manages the VM volume. tenant-name string Name of the tenant who owns/manages the VM volume. tenant-id string ID of the tenant who owns/manages the VM volume. description string Description of the VM volume. tags string User-defined tags that can be used to organize and/or filter the response results. 278 Chapter 3: Using the HSP VM management API

291 vm-volumes Example A Python coding example for this request is provided in the reference file system share on any HSP node in the following location: /examples/api/vm-volumes Each example file name carries the.py suffix and their corresponding output file carries the same name as the example files with an additional.out suffix. Adding VM volumes You can add a VM volume that will let you dedicate space for a virtual machine instance. After you have added one or more VM volumes you need to specify the disk used for the volumes and attach the disk to a VM instance. See "Attaching a disk to a VM instance" on page 271. Important: You need to edit the role of the disk from cluster to virtual machine prior to adding volumes and associating them with a disk. HTTP request syntax POST Request Specify the properties for the VM volume: name string Name of the VM volume. disk-id string The disk to which the VM Volume is associated. size number Size of the VM Volume. Specify the VM Volume size in bytes. The size you can specify for the VM volume depends on how large the disk is and how much space is left on the disk. Chapter 3: Using the HSP VM management API 279