Swordfish Scalable Storage Management API User's Guide

webinar

Swordfish Logo

Swordfish Scalable Storage Management API User's Guide

Swordfish Technical Proposal Notice

Version 1.0.3 Technical Proposal

Publication of this SNIA Technical Proposal has been approved by the SNIA. This document represents a stable proposal for use as agreed upon by the Scalable Storage Management Technical Work Group. The SNIA does not endorse this proposal for any other purpose than the use described. This proposal may not represent the preferred mode, and the SNIA may update, replace, or release competing proposals at any time. If the intended audience for this release is another standards body, the future support and revision of this proposal may be outside the control of the SNIA or the Scalable Storage Management Technical Work Group. Suggestions for revision should be directed to http://www.snia.org/feedback.

SNIA Technical Proposal

Last Revised: January 24, 2017

USAGE

The SNIA hereby grants permission for individuals to use this document for personal use only, and for corporations and other business entities to use this document for internal use only (including internal copying, distribution, and display) provided that:

  1. Any text, diagram, chart, table or definition reproduced must be reproduced in its entirety with no alteration, and,

  2. Any document, printed or electronic, in which material from this document (or any portion hereof) is reproduced must acknowledge the SNIA copyright on that material, and must credit the SNIA for granting permission for its reuse.

Other than as explicitly provided above, you may not make any commercial use of this document, sell any or this entire document, or distribute this document to third parties. All rights not explicitly granted are expressly reserved to SNIA.

Permission to use this document for purposes other than those enumerated above may be requested by emailing tcmd@snia.org. Please include the identity of the requesting individual and/or company and a brief description of the purpose, nature, and scope of the requested use.

All code fragments, scripts, data tables, and sample code in this SNIA document are made available under the BSD 3-Clause Software License.

Copyright SNIA 2016-2017 The Storage Networking Industry Association.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of The Storage Networking Industry Association (SNIA) nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

DISCLAIMER

The information contained in this publication is subject to change without notice. The SNIA makes no warranty of any kind with regard to this specification, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The SNIA shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use Suggestions for revisions should be directed to http://www.snia.org/feedback/.

Copyright © 2016-2017 Storage Networking Industry Association.

Revision History

Revision history
Date Revision Notes
19 September 2016 1.0.0 Initial Release
12 October 2016 1.0.1 General clean up and formatting consistency
    A discussion of unused CoS and LoS entries in ServiceCatalog
    Improve purpose for many use cases
1 November 2016 1.0.2 Corrected XREF link formatting
24 January 2017 1.0.3 Additonal use cases and new document section addressing client considerations

Suggestion for changes or modifications to this document should be sent to the SNIA Scalable Storage Management (SSM) Technical Working Group at http://www.snia.org/feedback/.

Contact SNIA

SNIA Web Site

Current SNIA practice is to make updates and other information available through their web site at http://www.snia.org.

FEEDBACK AND INTERPRETATIONS

Requests for interpretation, suggestions for improvement and addenda, or defect reports are welcome. They should be sent via the SNIA Feedback Portal at http://www.snia.org/feedback/ or by mail to the Storage Networking Industry Association, 4360 ArrowsWest Drive, Colorado Springs, Colorado 80907, U.S.A.

INTENDED AUDIENCE

This document is intended for use by individuals and companies engaged in storage management.

VERSIONING POLICY

This document is versioned material. Versioned material shall have a three-level revision identifier, comprised of a version number 'v', a release number 'r' and an errata number 'e'. Future publications of this document are subject to specific constraints on the scope of change that is permissible from one revision to the next and the degree of interoperability and backward compatibility that should be assumed between products designed to this standard. This versioning policy applies to all SNIA Swordfish versioned materials.

Version Number: Versioned material having version number 'v' shall be backwards compatible with all of revisions of that material that have the same version number 'v'. There is no assurance of interoperability or backward compatibility between revisions of a versioned material with different version numbers.

Release Number: Versioned material with a version number 'v' and release number 'r' shall be backwards compatible with previous revisions of the material with the same version number, and a lower release number. A minor revision represents a technical change to existing content or an adjustment to the scope of the versioned material. Each minor revision causes the release number to be increased by one.

Errata Number: Versioned material having version number 'v', a release number 'r', and an errata number 'e' should be backwards compatible with previous revisions of the material with the same version number and release number ("errata versions"). An errata revision of versioned material is limited to minor corrections or clarifications of existing versioned material. An errata revision may be backwards incompatible, if the incompatibility is necessary for correct operation of implementations of the versioned material.

About SNIA

The Storage Networking Industry Association (SNIA) is a non-profit organization made up of member companies spanning information technology. A globally recognized and trusted authority, SNIA's mission is to lead the storage industry in developing and promoting vendor-neutral architectures, standards and educational services that facilitate the efficient management, movement and security of information.

Acknowledgements

The SNIA Scalable Storage Management Technical Work Group, which developed and reviewed work in progress, would like to recognize the significant contributions made by the following members:

Member Contributors
Broadcom Limited Richelle Ahlvers
Dell Inc. Patrick Boyd
  George Ericson
  Michael Raineri
  Rich Roscoe
Hitachi Data Systems Eric Hibbard
Hewlett Packard Enterprise Jeff Hilland
  John Mendonca
Inova Development Inc. Karl Schopmeyer
Intel Corporation Slawek Putyrski
  Paul von Behren
Microsoft Corporation Hector Linares
  Jim Pinkerton
  Michael Pizzo
  Scott Seligman
NetApp, Inc. Don Deel
  Nilesh Maheshwari
Nimble Storage Chris Lionetti
VMware, Inc. Murali Rajagopal

Table of Contents

1. Introduction
1.1. Audience
1.2. Documentation structure
1.3. Configuration assumptions
1.4. Knowledge assumptions
1.5. Related documents
2. General query syntax
2.1. OData conformance
2.2. Query method
2.3. Query Headers
2.4. Service root
2.5. Resource path
2.6. Query options
2.7. Filter expressions
2.8. HTTP status codes
3. Actors
3.1. CloudAdmin
3.2. DevOps
3.3. Storage Admin
4. Management Domains
4.1. Application storage management domain
4.2. Block storage management domain
4.3. Service catalog management domain
4.4. File system storage management domain
5. User Guidance
5.1. Default Class of Service
6. Use Cases
6.1. Add Volume
6.2. Allocate VM space
6.3. Allocate Volume
6.4. Allocate Volume using Default Class of Service
6.5. Health updates
6.6. Create class of service
6.7. Create file share
6.8. Create file system
6.9. Create line of service
6.10. Create StorageGroup
6.11. Create storage pool
6.12. Discover Class of Service
6.13. Expand capacity of a storage volume
6.14. Find storage service
6.15. Get capacity by class of service
6.16. List supported line of service options
6.17. Subscribe to Threshold Events
6.18. Set Capacity Usage Threshold
6.19. Protect Volumes of an application
6.20. Storage health report

1. Introduction

1.1. Audience

This guide is intended to provide a common repository of best practices, common tasks and education for the users of the Swordfish API. Each use case includes an indication of the classes of API users who are most likely to find the case useful.

1.2. Documentation structure

This document begins with a set of information intended to provide a solid foundation for readers new to restful APIs in general and Swordfish in particular. While this material is no replacement for a thorough understanding of the Swordfish specification and the material that it references, it is intended as a stand alone document that can provide a solid introduction to Swordfish.

Based on that foundational material, this document then presents a set of Use Cases intended to capture common tasks and best practices that can be used to exercise the breadth and strength of the Swordfish API. In general, the guide is structured to provide more basic use cases first, and examine common refinements and options at the same time. More advanced tasks are handled later in the guide, and assume the prior skills and assumptions have been mastered.

For each use case, this guide will use a common template. Table 1 lists each field of the template and its description.

Table 1: Guidelines for the Use Case Template

Name Description
Title A description of the high-level scope of the Use Case
Summary A high-level summary of the use case
Purpose The intended goals or motivations for the use case
Who The Actor(s) who are likely to use this use case. The actor description also includes a list of other use cases of interest for a named actor
Management Domain The Management Domain(s) applicable to this use case. The domain description also includes a list of other use cases of interest for the named management domains
Triggers A description of likely business conditions or goals that would make this use case useful
Detailed Context A detailed description of the operations environment and configuration assumptions for this use case
Preconditions Pre-existing knowledge, configurations or capabilities
Inputs A set of parameters and values that are used to adapt a generic use case to a specific business needs. Where appropriate, the parameter description will include a data type (e.g., {CAPACITY}: desired storage capacity (int64))
Basic Course of Events A sequence of API requests, including required headers, the body of the request, and the expected reply
Configuration Impacts Changes to the storage configurations caused by the use case
Failure Scenario Common failure conditions encountered in this use case
See Also Other Use Cases that may be of interest

1.3. Configuration assumptions

This document assumes that some fundamental configuration issues have been properly addressed, and will not need to be addressed in any detail. In particular, this document assumes:

  • An appropriate security infrastructure (e.g., TLS 1.2)
  • A functional Swordfish/Redfish installation, in either a standalone, aggregator, or distributed configuration
  • Any required login credentials

1.4. Knowledge assumptions

The Swordfish API conforms to the standards defined in the Redfish API. More generally, it is provides a RESTful interface. The reader is assumed to be familiar with common conventions for RESTful APIs. Those readers who are interested in additional background information are encouraged to refer to the following sources:

This User's Guide is part of the documentation suite for the Swordfish API. Readers are encouraged to refer to the following for additional information: - Swordfish API Specification - Swordfish Tutorials

2. General query syntax

2.1. OData conformance

Swordfish, like RedFish, conforms to the OData Version 4. It conforms to the query syntax and URL structure that that standard defines. The high-level assumptions are summarized here. Readers who need more information should refer to the OData standard.

All Swordfish URLs follow a general form of:

2.2. Query method

Swordfish queries support four query methods. Each query URL must include exactly one of of the query methods listed in Table 1: Query Methods.

Table 1: Query Methods

Method Action
GET Retrieve the current state or settings of the named Resource Path as seen through the Service Root
POST Create a new object under the named Resource Path
PUT Replace the object referenced by the named Resource Path
DELETE Delete the object referenced by the named Resource Path
PATCH Update the object referenced by the named Resource Path
HEAD Validates a GET request against the named Resource Path without returning the HTML headers for the response without the result of the query

2.3. Query Headers

All HTTP requests and responses in a compliant Swordfish implementation support the HTTP headers required by the Redfish Protocol Specification. The supported headers are reproduced here for convenience.

Request headers

Header Supported Values Notes
Accept RFC 7231 Indicates to the server what media type(s) this client is prepared to accept. Services shall support requests for resources with an Accept header including application/json or application/json;charset=utf-8. Services shall support requests for metadata with an Accept header including application/xml or application/xml;charset=utf-8.
Content-Type RFC 7231 Describes the type of representation used in the message body. Content-Type shall be required in requests that include a request body. Services shall accept Content-Type values of application/json or application/json;charset=utf-8.
OData-Version 4.0 Services shall reject requests which specify an unsupported OData version. If a service encounters a version that it does not support, the service should reject the request with status code 412. If client does not specify an Odata-Version header, the client is outside the boundaries of this specification.
Authorization RFC 7235, Section 4.2 Required for Basic Authentication
User-Agent RFC 7231 Required for tracing product tokens and their version. Multiple product tokens may be listed.
Host RFC 7230 Required to allow support of multiple origin hosts at a single IP address.
Origin W3C CORS, Section 5.7 Used to allow web applications to consume Redfish Service while preventing CSRF attacks.
If-Match RFC 7232 If-Match shall be supported on PUT and PATCH requests for resources for which the service returns ETags, to ensure clients are updating the resource from a known state.
X-Auth-Token Opaque encoded octet strings Used for authentication of user sessions. The token value shall be indistinguishable from random.

Response headers

Header Supported Values Notes
OData-Version 4.0 Describes the OData version of the payload that the response conforms to.
Content-Type RFC 7231 Describes the type of representation used in the message body. Services shall specify a Content-Type of application/json when returning resources as JSON, and application/xml when returning metadata as XML. ;charset=utf-8 shall be appended to the Content-Type if specified in the chosen media-type in the Accept header for the request.
ETag RFC 7232 An identifier for a specific version of a resource, often a message digest. Etags shall be included on responses to GETs of ManagerAccount objects.
Server RFC 7231 Required to describe a product token and its version. Multiple product tokens may be listed.
Link   Link headers shall be returned as described in the clause on Link Headers
Location RFC 7231 Indicates a URI that can be used to request a representation of the resource. Shall be returned if a new resource was created. Location and X-Auth-Token shall be included on responses which create user sessions.
Cache-Control RFC 7234 This header shall be supported and is meant to indicate whether a response can be cached or not.
Access-Control-Allow-Origin W3C CORS, Section 5.7 Prevents or allows requests based on originating domain. Used to prevent CSRF attacks.
Allow POST, PUT, PATCH, DELETE, GET, HEAD Shall be returned with a 405 (Method Not Allowed) response to indicate the valid methods for the specified Request URI. Should be returned with any GET or HEAD operation to indicate the other allowable operations for this resource.
WWW-Authenticate RFC 7234, Section 4.1 Required for Basic and other optional authentication mechanisms. See the Security clause for details.
X-Auth-Token Opaque encoded octet strings Used for authentication of user sessions. The token value shall be indistinguishable from random.

2.4. Service root

This is the base of all Swordfish URL's. A GET request to the Service Root will return an overview of the services provided by a given Swordfish service. In addition, the Service Root will include versioning information.

All Service Root URLs that are compliant with the Swordfish specification will be of the form https://hostName/redfish/v1, where hostName specifies the system (and optionally port number), of the Swordfish service provider.

2.5. Resource path

The Resource Path identifies the specific object (or collection of objects) that is the target of the Swordfish query. As with OData, Swordfish Resource Paths can identify: - A singleton object (e.g., a specific storage LUN or Volume) - A collection of objects (e.g., the list of all LUNs provided by a specific storage array)

At the highest level, Swordfish identifies two major collections: Storage Systems and Storage Services.

2.6. Query options

Swordfish queries can include arbitrary sets of query options to further refine the target of given query or the actions being requested of that target. These general query options are summarized in Table 3: Query Options.

Note: Additional query options may be supported (or constrained) for a specific query target or resource path. These target-specific query options will be addressed in specific use case descriptions, as required.

Table 3: Query Options

Parameter Name Arguments Notes  
$skip=n Integer Omit the first n entries in the collection from the returned set of objects (required by redfish)  
$top=n Integer Return, at most, the first n entries in the returned set of objects (required by redfish)  
$filter=condition Filter Expression Returns only the members of the named collection that match the provided logical expression (required by swordfish)  
$expand=target Expand Expression Expand additional detail on the target property(s) in the returned result set (required by swordfish)  
$select=property list Comma-separated list of object properties Return the named properties for each object in the result set, rather than the entire object (required by swordfish)  
$orderby=filter condition Filter Expression sort the result set by the output values from the filter expression (required by swordfish)  

2.7. Filter expressions

 

  1. Simple example $filter=(age gt 30) A group of people never to trust.

For more information see Filter Expression in the OData specification.

2.8. HTTP status codes

Swordfish clients may receive any of the standard HTTP status codes. For status codes greater than 400, the server can also return extended status information as a simple JSON object (see Redfish Specification for more information).

3. Actors

Swordfish defines three high-level users roles, or Actors:

  • Storage Admin
  • DevOps Staffer
  • Cloud Architect

3.1. CloudAdmin

A Cloud Administrator (CloudAdmin) is a converged infrastructure administrator, working with systems that are:

  • Hyper-converged
  • Rack-converged
  • Hyper-scale

The CloudAdmin role in an enterprise or service provider is the individual or group primarily responsible for managing the operational lifecycle of a cloud, virtualization, converged environment that consists of the workloads, resource abstractions, storage, networking, and compute.

Also referred to as a "cloud architect", this role:

  • designates a group of people to build and maintain a virtualized, converged, and/or cloud environment
  • spans compute, storage, and networking disciplines as their job is to manage the operational lifecycle of the entire environment
  • focuses on automation that involves scripting and potentially formal programming
  • This role's value is to keep the environment that hosts applications available and responding. Deep subject matter expertise is less valuable unless it helps solve an issue.
  • The focus for this role is to streamline the deployment of applications into the infrastructure including all the network and storage configuration.
  • This role gets involved in the physical deployment of capacity in the datacenter.
  • This role deals with software defined infrastructure deployment and management.
  • Applications can span physical, virtual machine, container, PaaS building blocks. This role is expected to know how to best configure the "stack" to consume the underlying physical infrastructure.

Use Cases

3.2. DevOps

A member of the DevOps group:

  • Consumes infrastructure capacity offered as a service/building blocks.
  • Develops and deploys programmatic requests for capacity (fully automated, no ticketing or human intervention)
  • Provisions storage as a virtual appliance on-premises or in the cloud as part of a larger application deployment
  • Deploys 'cloud born apps' to consume object storage APIs (S3, Swift)

This role is typically aligned with the business unit. Their focus is the delivery, deployment, and maintenance of apps on IaaS and PaaS resources. This role is not typically a deep subject matter expert in compute, storage, or networking. From a development perspective, their desire is to treat the infrastructure as a programmable subsystem that presents resources on-demand.

This role:

  • does not get involved in the physical deployment of capacity in the datacenter
  • is responsible for automating infrastructure provisioning as part of the E2E deployment and management of an application with minimal or no human intervention
  • consumes higher level services and protocols from the infrastructure; understanding how the device works is not interesting
  • expects to consume the programmable interfaces of a device using their existing tools (REST, Python, Ansible, Puppet, Chef, Ruby etc.)

Use Cases

3.3. Storage Admin

A storage administrator designs storage solutions for modern environments, including:

  • Virtualization (traditional virtualization VMware, Hyper-V)
  • private cloud (self-service portal)
  • hybrid cloud (can span private, colo, hosted, and public cloud)
  • IaaS/PaaS stacks (modern app/devops)

The storage admin role in an enterprise or service provider can have dedicated to managing the operational lifcycle of storage in the datacenter.

  • Organizations can have one or more people exclusively assigned to operating lifecycle of storage in the datacenter.
  • The storage admin role is typically tasked with "figuring" out storage needs for the company
  • The admin role can consist of level 2 operators and level 3 engineers and architects.
  • The admin role deals with multiple storage devices from multiple vendors across one or more datacenters.
  • Storage devices attached to multiple operating systems (Linux, Windows, Mainframe, Unix, virtualized, bare metal).
  • The Admin role consists of deep storage subject matter expertise, may or may have general practitioners across all disciplines
  • Members of this role are typically skilled at scripting and formal programming
  • In a converged environment (storage, compute, and networking converged in to a rack), the storage admin role may choose to avoid/minimize involvement in the support of storage WITHIN the rack. (e.g. in virtualization, a single physical port can host 1000s of VMs).

Use Cases

4. Management Domains

Swordfish defines four general management domains:

  • Block Storage
  • Filesystem Storage
  • Application Storage
  • Class of Service

4.1. Application storage management domain

This domain manages the interface between applications and the storage that they rely upon.

StorageGroups provide a means to collectively manage the Volumes and FileShares utilized by an Application. The StorageGroup specifies whether the collected resources are managed so that storage is updated or replicated consistently across all members. Additionally, the StorageGroup provides the means to atomically expose (or hide) the collected resources to (or from) host endpoints.

Use cases

4.2. Block storage management domain

Many devices and services provide their storage capacity to external devices and applications through block-based protocols to storage devices. This domain includes the management of resources that provide block-based access to storage.

Block-based storage is represented by a Volume. This domain provides for the discovery and provisioning of Volumes and for maintaining relationships to Device, Endpoint, StorageService, StorageGroup, StoragePool, and ComputerSystem resources.

Use Cases

4.3. Service catalog management domain

Swordfish supports access and management to a catalog of service options, (see ITIL glossary and abbreviations), supported by storage services.

The ClassOfService resource represents a service option that may be used to specify requirements for utility or warranty when provisioning a resource. Currently ClassOfService is defined for use in the Block Storage, File System, and ApplicationStorage domains.

The service catalog for each StorageService is represented by a collection of references to supported ClassOfService resources. Each ClassOfService is known minimally by a Name and a unique Identifier. When a ClassOfService is specified for a resource, the StorageService shall attempt to maintain that resource in compliance to the requirements of that ClassOfService. The requirements may be specified informally by text in the Description property or may be specified formally by the property values of embedded options related to specific lines of service.

The embedded service options are described by values of complex types representing lines of service.

Over time, as the service catalog is continually updated to match evolving user needs and service provider offerings, it is expected that the catalog will contain entries (one or more ClassOfSerice or LineOfService instances) that are not currently active.

Data protection

The primary storage is described by a ClassOfService resource. That ClassOfService may aggregate any number of data protection service options. Each instance of a data protection service option describes the characteristics a replication session that shall be maintained for the containing primary storage resource.

For additional information, see the definitions for DataProtectionLineOfService and DataProtectionLoSCapabilities.

Data security

An instance of a data security service option describes an optional set of data security requirements. A data security Service option is typically aggregated into a ClassOfService resource that is associated with storage. At most one data security service option may be aggregated into a ClassOfService resource. When storage is provisioned with that ClassOfService, it will provide the currently specified data security characteristics.

A data security service option may specify data security characteristics that enable the storage system to be used in an environment where compliance with an externally-specified security standard or standards is required. Examples of such standards include FIPS-140, HIPAA and PCI. In this case, the names of the standard or standards can usefully be included in the user/admin-visible name of the instance. With the notable exception of FIPS-140, compliance requires measures well beyond the means of a storage system to provide (e.g., both HIPAA and PCI impose significant requirements on administration and operation of the data center), so this approach promises that the storage system will do its part in supporting compliance, but does not (and cannot) promise that the storage system will deliver full compliance by itself.

The description attribute value may include human readable information including:

  • Whether encryption keys are drive or array resident or externally managed (e.g., via KMIP).

  • Information on how the array supports compliance to a standard identified in the name of the Service option. (e.g., specific algorithms employed that are FIPS-140 compliant, information about the validated cryptographic module and its validation certificate, relationship of the security functionality to specific PCI or HIPAA requirements).

NOTE For comparable cryptographic strengths, (see NIST SP 800-57 part 1)

NOTE For symmetric encryption algorithm key sizes, 112 bits is the 3DES key size and 128, 192, and 256 bits are options for AES key sizes.`

NOTE MediaEncryptionStrength includes the case where metadata about the data must be encrypted. (e.g. data presence vs. absence in a thin volume, array filesystem metadata) The implementation may be self-encrypting drives or encryption in the storage system’s drive controller. Keys may be drive or array resident or externally managed (e.g., via KMIP).

For additional information, see the definitions for DataSecurityLineOfService and DataSecurityLoSCapabilities.

Data storage

Each data storage service option describes characteristics of the storage at a particular location. A class of service will have at most one data storage service option, which describes the storage specified by that class of Service.

For additional information, see the DataStorageLineOfService and DataProtectionLoSCapabilities.

IO connectivity

An IO connectivity service option specifies the characteristics of storage connectivity. For each value of AccessProtocol, at most one IO connectivity service option may be aggregated into a class of service.

NOTE: If used within a ClassOfService for Storage Provisioning, this value constrains the set of connections used to expose that storage.

For additional information, see the IOConnectivityLineOfService and IOConnectivityLoSCapabilities.

IO performance

An IO performance service option specifies a choice of performance characteristics as viewed through the data path to the storage. This is affected by choices of storage and connection technologies.
At most one IO performance service option may be aggregated into a ClassOfService for a storage resource. When storage is provisioned with that ClassOfService, it should provide at least the specified performance.

For additional information, see the IOConnectivityLineOfService and IOConnectivityLoSCapabilities.

Use cases

4.4. File system storage management domain

FileSystems provide access to byte-accessible storage through file-based protocols. This domain includes the management of resources that provide file-based access to storage.

File-based storage is represented by a FileSystem resources. Remote access to portions of a FileSystem is provided by FileShare resources.

Use cases

5. User Guidance

5.1. Default Class of Service

If a pool, storage volume or other contruct is created with no specified class of service when a class of service exists, the implementation will attempt to apply the DefaultClassOfService.

6. Use Cases

Title Description
Add volume Add a volume to a StorageGroup
Allocate VM Space Allocate space for a new VM
Allocate volume Allocate a new volume
Allocate volume using default class of service Allocate a new volume without default class of service
Create class of service Create a class of service
Create file share Create a file share
Create file system Create a files system
Create line of service Create a line of service
Create StorageGroup Create a StorageGroup
Create Storage Pool Create a StoragePool
Discover class of service Discover a class of service
Expand Volume Expand capacity of a Volume
Find storage service Find a services support a class of service
Get capacity by class of service Summarized capacity by a class of service
Health Updates Example of health status monitoring
List supported line of service options List Supported Line Of Service Options
Set space thresholds Set Capacity Usage Thresholds
Protect Volumes of an application Protect Volumes of an Application
Subscribe to thresholds events Subscribe to Threshold Events

See also: None defined.

6.1. Add Volume

 

Summary: Add Volumes to a StorageGroup

Purpose: Add Volumes to a StorageGroup

Who: Cloud Admin

Management Domain: Block Storage Management

Triggers: A need for expanded capacity in a StorageGroup

Detailed Context: A Volume has been created, and needs to be added to an existing StorageGroup.

Preconditions: None.

Inputs:

  • {SGURL}: URL for storage group
  • One or more URLs for Volumes to add [{VURI1}, {VURI2}, ...]

Basic Course of Events:

  1. Add the Volume(s) the Members collection of the StorageGroup

    • Request:

    POST {SGURL}/Volumes/Members

    • Headers: No additional headers required.

    • Body:

      [{"VURI_1"}, {"VURI_2"}, ... ]

    • Response: None defined.

Postconditions: The selected Volume(s) are added to the Members collection for the Storage Group.

Failure Scenario: None defined.

See also: None defined.

6.2. Allocate VM space

 

Summary: Allocate space for a VM (e.g., Docker) deployment

Purpose: Allocate space for a VM (e.g., Docker) deployment

Who: DevOps

Management domain: [Block Storage Management]#blockstoragemanagementdomain "Block Storage Management)

Triggers: DevOp needs to set up a new VM to host a Ceph OSD service.

Detailed context: Some cloud web services deploy a large number of VMs (or containers) that do not keep data in traditional files or block storage; instead, they store data in remote object stores. This use case relates to setting up systems hosting Ceph as an object store. Ceph is deployed as a set of collaborating systems providing fault tolerance; this use case addresses one VM dedicated as a Ceph Object store (OSD) system. The VM is allocated with a virtual disk for the OS and Ceph software; an external disk is allocated for Ceph data. For this use case, the DevOP prefers using an HDD rather than an SSD and needs at least 400 Gigabytes (400,000,000,000 bytes).

Preconditions: The catalog (see JBOD discovery use case) must exist and include at least one available HD

Inputs:

  • {MEDIA}: The MediaType (in this case, HDD)
  • {CAPACITY}: Capacty in bytes (in this case, at lease 400,000,000,000)

Basic course of events:

  • Devop searches for Drives in the catalog, looking for those with MediaType = HDD and CapacityBytes >= 400,000,000,000)

  • A matching drive is selected. The admin notes the drive serial number and updates the catalog to mark the drive as allocated

  • If necessary, the Devop makes the appropriate zoning changes to make the drive accessible to the server with the hypervisor hosting the Ceph VM

  • The Devop configures the hypervisor to make this drive available to the Ceph V

Postconditions: The Devop can now install and configure Ceph to use the selected drive

Failure Scenario: None defined.

See also: None defined.

6.3. Allocate Volume

 

Summary: Allocate a Volume

Purpose: Allocate a Volume with a known capacity and class of service.

Who: Cloud Admin, Storage Admin, DevOps

Management Domain: Block Storage Management

Triggers: Need to allocate storage for a new application.

Detailed Context: The admin needs to satisfy a service request to provide a given amount of storage to an application, and to assure a given class of service.

Preconditions: None.

Inputs:

  • _URL for Storage Service: /redfish/v1/StorageServices(1)
  • _Requested volume size in TB (int64): 1099511627776
  • _URL for requested class of service: /redfish/v1/StorageServices(1)/Links/ClassesofService(BostonBunker)
  • _Requested name of volume (string): Snapshot1

Basic Course of Events:

  1. Post the definition of the new volume to the Volumes resource collection.

This instructs the service to allocate a new volume of the requested size that meets the requirements of the specified class of service. Since additional details are not provided, the service is free to allocate the storage from any of its storage pools that can satisfy the request.

  • Request: POST /redfish/v1/StorageServices(1)/Volumes

  • Headers: No additional headers required.

  • Body:

    {
  "Name": "Snapshot1",
  "Size": 1099511627776,
  "Class": "/redfish/v1/StorageServices(1)/Links/ClassesofService(BostonBunker)"
}

  • Response:

  • Headers:

    Location = /redfish/v1/StorageServices(1)/Volumes(3)

  • Body:

    {
"@SSM.Copyright": "Copyright (c) 2014-2016 SNIA. All rights reserved.",
"@odata.context": "/redfish/v1/$metadata#Volume.Volume",
"@odata.id": "/redfish/v1/StorageServices(1