Swordfish Scalable Storage Management API Specification

Swordfish Technical Position Notice

Version 1.0.3 Technical Position

Last Updated 24 January 2017

This document has been released and approved by the SNIA. The SNIA believes that the ideas, methodologies and technologies described in this document accurately represent the SNIA goals and are appropriate for widespread distribution. Suggestions for revision should be directed to http://www.snia.org/feedback/.

SNIA Technical Position

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

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:

Table of Contents

1. Abstract
2. Scope
3. Normative References
3.1. Overview
3.2. Approved references
3.3. References under development
3.4. Other references
4. Terms and Definitions
4.1. Overview
4.2. Swordfish-specific
4.3. Reference to Redfish terms
4.4. Keywords (normative language terms)
5. Swordfish Overview
5.1. Introduction
5.2. Relation to Redfish
5.3. Storage Services
5.4. The ClassOfService resource
5.5. The Endpoint resource
5.6. The Endpoint Collection resource
5.7. The EndpointGroup resource
5.8. The EndpointGroupCollection resource
5.9. The StorageGroup resource
5.10. The StoragePool resource
5.11. The Volume resource
5.12. The FileSystem resource
6. Data model
6.1. Swordfish extensions to Redfish
6.2. Entity Sets
6.3. Addressing entities within a collection
6.4. Addressing members of a ResourceCollection
6.5. Schema repository
6.6. Referencing other schemas
7. Schema Considerations
7.1. Schema Introduction and Overview
7.2. Common schema attributes
7.3. Default values and NULLABLE attributes
7.4. Common schema annotations
7.5. Schema repository
7.6. Referencing other schemas
8. Implementation requirements
8.1. Security
8.2. General constraints
8.3. Discovering Swordfish resources
8.4. ClassOfService requirements
8.5. StorageSystems requirements
8.6. Entity Sets
8.7. Addressing entities within a collection
8.8. Addressing members of a ResourceCollection
9. Swordfish type definitions
9.1. Overview
9.2.
9.3. search: true
9.4. ClassOfService 1.0.0
9.5. ClassOfServiceCollection
9.6. DataProtectionLoSCapabilities 1.0.0
9.7. DataSecurityLoSCapabilities 1.0.0
9.8. DataStorageLoSCapabilities 1.0.0
9.9. DriveCollection
9.10. EndpointCollection
9.11. EndpointGroup 1.0.0
9.12. EndpointGroupCollection
9.13. FileShare 1.0.0
9.14. FileSystem 1.0.0
9.15. FileSystemCollection
9.16. HostedStorageServices
9.17. IOConnectivityLoSCapabilities 1.0.0
9.18. IOPerformanceLoSCapabilities 1.0.0
9.19. StorageGroup 1.0.0
9.20. StorageGroupCollection
9.21. StoragePool 1.0.0
9.22. StoragePoolCollection
9.23. StorageService 1.0.0
9.24. StorageServiceCollection
9.25. StorageSystemCollection
9.26. Volume 1.1.0
9.27. VolumeCollection

1. Abstract

The Swordfish Scalable Storage Management API ("Swordfish") defines a RESTful interface and a standardized data model to provide a scalable, customer-centric interface for managing storage and related data services. It extends the Redfish Scalable Platforms Management API Specification (DSP0266) from the DMTF.

2. Scope

Swordfish defines a comprehensive, RESTful API for storage management that addresses block storage, file systems, object storage, and storage network infrastructure. It is centered around common operational and business concerns of storage management, including:

• Configuration and provisioning
• Monitoring
• Event and log management
• Performance assessment
• Diagnostics
• Fault detection and remediation
• Security
• Accounting and resource consumption

Swordfish's storage model is built around well-defined classes of service, which provide a means to map high-level business goals and objectives to specific, storage-based actions and requirements, in a clear and consistent way that can be applied uniformly across a broad spectrum of storage configurations and storage types (e.g., block storage, file systems, object stores). Common storage management functionality covered by class of service includes snapshots, replication, mapping and masking, and provisioning.

The Redfish specification provides the protocols and a core set of data models and behaviors for the management of systems. It defines the elements and behaviors that are mandatory for all Redfish implementations. Additionally it defines additional elements and behaviors that can be chosen by system vendors or manufacturers. The specifications also defines points at which OEM (system vendor) extensions can be provided by a given implementation. The specifications specifies normative requirements for Redfish Services and associated materials, such as Redfish Schema files. The Redfish specifications does not set requirements for Redfish clients, but will indicate what a Redfish client should do in order to access and utilize a Redfish Service successfully and effectively.

The Swordfish specification defines additional data models and behaviors for the management of storage systems and storage infrastructure. A Swordfish implementation shall conform to all requirements specified in the Redfish specifications.

Swordfish is suitable for a wide range of storage, from small-scale object drives, integrated RAID cards or RBODs providing storage services, to external disk arrays or file servers, to infrastructure providing storage services for converged, hyperscale and large scale cloud environments.

This document defines the Swordfish Scalable Storage Management API.

3. Normative References

3.1. Overview

The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

3.2. Approved references

3.3. References under development

None defined in this document.

3.4. Other references

None defined in this document.

4. Terms and Definitions

4.1. Overview

In this document, some terms have a specific meaning beyond the normal English meaning. Those terms are defined in this clause. New terms, frequently used Redfish terms.

4.2. Swordfish-specific

Definitions

The following terms are used in this document.

Symbols and abbreviated terms

None in this document.

4.3. Reference to Redfish terms

Many terms in this document were originally defined in the Redfish Specification. Some of the more common terms and definitions are reproduced here, as an aid to the reader.

4.4. Keywords (normative language terms)

This document conforms to ISO/IEC Directives, Part 2 for keyword usage. The most common terms and their intended meanings are summarized below.

5. Swordfish Overview

5.1. Introduction

The Swordfish Scalable Storage Management API ("Swordfish") defines a RESTful interface and a standardized data model to provide a scalable, customer-centric interface for managing storage and related data services. It extends the Redfish Scalable Platforms Management API Specification (DSP0266) from the DMTF.

5.2. Relation to Redfish

The Swordfish service interface extends the Redfish service interface. As such, a Swordfish service is a Redfish service and includes all required elements of the Redfish model.

Storage systems managed by the Swordfish storage service are located in the ServiceRoot (and ServiceContainer) via the StorageSystems resource collection. They are modeled using Redfish ComputerSystems. The physical infrastructure is modeled using Redfish Chassis.

Each Swordfish StorageService is located in the ServiceRoot (and ServiceContainer) via the StorageServices resource collection. All Swordfish defined instances are located through StorageService intances. A Swordfish management client may focus entirely on entities defined by the Swordfish schema.

The combined Redfish and Swordfish models defines information requirements and constraints on the values that are used as input or output of the operations supported by the Swordfish interface. The Swordfish interface relies on the operations specified by the OData REST protocol (#normative-references). Additional operations (known as Actions) are also defined by the model. The information content is defined by a schema specified using the Common Schema Definition Language (CSDL) (#normative-references) defined by the OData organization within OASIS (https://www.oasis-open.org/).

Each Swordfish service is accessed via well known URLs on the system supporting the Swordfish Service. Since Swordfish is an extension of Redfish, these URLs are the same as for accessing the Redfish defined aspects of the service.

The ServiceRoot and ServiceContainer entities

Overview

A GET of /redfish/v1 will return the ServiceRoot entity. A GET of /redfish/v1/odata will return the ServiceContainer instances that represents the OData service document. Each of these instances provides links to the remainder of the system.

The following are the elements utilized for Swordfish management.

• Systems: A referemce to a Systems resource collection, as defined in XREF;
• Chassis: A referemce to a Chasis resource collection, as defined in XREF;
• StorageSystems: A referemce to a StorageSystems resource collection, as defined in XREF;
• StorageServices: A referemce to a StorageServices resource collection, as defined in XREF.

The Systems resource collection

A resource collection that references a set of ComputerSystem resources that each represents a general purpose application server. Each ComputerSystem resource will have an entry with the value of "ApplicationServer" in its HostingRoles property. A particular ComputerSystem resource can be in both the StorageSystems collection and the Systems collection.

The Chassis resource collection

A resource collection that references a set of Chassis resources. Each Chassis resource represents physical containers, (i.e. sheet-metal confined spaces and logical zones like racks, enclosures, chassis and all other containers). Subsystems (like sensors), which operate outside of a system's data plane (meaning the resources are not accessible to software running on the system) are linked either directly or indirectly through this resource.

The StorageSystems resource collection

A reference to a ComputerSystemCollection with members of type ComputerSystem that support storage services. These ComputerSystem resources represent systems that support Swordfish storage management services. They will have an entry with the value of "StorageServer" in their HostingRoles property.A resource collection that references a set of ComputerSystem resources that each represents a storage server. Each ComputerSystem resource will have an entry with the value of "StorageServer" in its HostingRoles property. A particular ComputerSystem resource can be a member of both the StorageSystems resource collection and the Systems resource collection.

The StorageServices resource collection

A reference to a StorageServiceCollection with members that are of type StorageService. A resource collection that references a set of StorageService resources. Each StorageService resource represents the resources and behaviors supported by that storage service.

5.3. Storage Services

The StorageService resource

The storage service is hosted on a storage system and exposes logical storage, associated resources and related functionality. Storage service resources can be found in the service root or service container via the StorageServices resource collection.

The following are the principal properties of StorageService that point to resources managed or defined by the storage service:

• ClassesOfService: A reference to a resource collection that specifies the supported ClassOfService resources.
• ClientEndpointGroups: A reference to a resource collection that collects ClientEndpointGroup resources.
• Drives: A reference to a resource collection that collects Drive resources used for storage.
• Enclosures: A reference to a resource collection that collects Chassis resources that contain storage related resources.
• Endponts: A reference to a resource collection that collectsEndpoint resources used to access storage.
• FileSystems: A reference to a resource collection that collects FileSystem resources.
• ServerEndpointGroups: A reference to a resource collection that collects ServerEndpointGroup resources.
• StorageGroups: A reference to a resource collection that collects StorageGroup resources.
• StoragePools: A reference to a resource collection that collects StorageGroup resources.
• Volumes: A reference to a resource collection that collects Volume resources.
• HostingSystem: A reference to the ComputerSystem instance that hosts this StorageService.

The following properties each include a set of attributes that each describe a range of capabilities that the storage service can support for a particular kind of service.

• DataProtectionLoSCapabilities: Replicas that protects data from loss.
• DataSecurityLoSCapabilities: Data security service level requirements. The data security characteristics 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.
• DataStorageLoSCapabilities: Provisioning and access characteristics for storage of the data.
• IOConnectivityLoSCapabilities: IO connectivity requirements for access to the data.
• IOPerformanceLoSCapabilities: IO performance requirements for access to the data.

In each of the above, not all combinations of attribute values are likely to be supported by the storage service.

Known supported combinations of attribute values are used to construct entries in the LinesOfService array property. Not all attributes of a line of service entry need be specified (i.e. some may be Null). If an attribute has no value, the storage service may choose any supported values when provisioning for that entry. Otherwise, the line of service attribute values specifies the kind or level of service to be provided.

5.4. The ClassOfService resource

A class of service represents a choice of utility or warranty offered to customers by a service. (ITIL uses the term service option. See the Normative References.)

Each ClassOfService resource is a uniquely named description of the characteristics of one choice of utility or warranty for a service. Each ClassOfService is a description of the kind and quality of service to provide and is not intended to describe how the service provides that service.

Each ClassOfService is defined by an aggregation of lines of service. Supported lines of service are listed in the corresponding capabilities attributes of the storage service, (see above).

Currently defined lines of service are:

• Data Protection: Describes the characteristics of a replica that protects data from loss.
• Data Security: Describe data security service level requirements. The data security characteristics 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.
• Data Storage: Describes provisioning and access characteristics for storage of the data.
• IO Connectivity: Describes IO connectivity requirements for access to the data.
• IO Performance: Describes the IO performance requirements for access to the data under a particular workload.

Some advertised ClassOfService resources are created by the service implementation. These are generally not changeable and are intrinsic to the implementation.

A service may support creation or modification of ClassOfService resources. All must be consistent with the capabilities of the service.

5.5. The Endpoint resource

Endpoints represent one end of a protocol specific connection that supports sending or receiving messages according to a particular protocol.

5.6. The Endpoint Collection resource

The Endpoint Group is resource collection that references a set of Endpoint resources.

5.7. The EndpointGroup resource

The EndpointGroup is a resource that represents a set of Endpoint resources that have the same management characteristics and which will all have the same access state.

5.8. The EndpointGroupCollection resource

The EndpointGroupCollection is resource collection that references a set of EndpointGroup resources.

5.9. The StorageGroup resource

StorageGroups represent a set of volumes that are managed as a group with the same consistency requirements. The volumes of a storage group are collectively exposed or hidden to a set of clients.

The set of volumes is specified by the Volumes attribute, which is a resource collection that references volumes.

The set of client endpoints to which the volumes can be exposed is specified by the ClientEndpointGroupsattribute. The ClientEndpointGroup resource specifies a collection of EndpointGroup resources.

The set of server endpoints to which the volumes can be exposed is specified by the ServerEndpointGroupsattribute. The ServerEndpointGroup resource specifies a collection of EndpointGroup resources.

5.10. The StoragePool resource

The StoragePool resource represents unassigned storage capacity that can be used to produce storage volumes or other storage pools, which conform to one or more classes of service.

The following are the principal properties of StoragePool that are used to identify resources provisioned or supported by the storage pool:

• ClassesOfService: A reference to a resource collection that specifies the set ClassOfService resources that can be specified when provisioning resources from the storage pool.
• AllocatedVolumes: A reference to a resource collection that collects Volume resources that have been provisioned from the storage pool.
• AllocatedPools: A reference to a resource collection that collects StoragePool resources that have been provisioned from the storage pool.
• DefaultClassOfService: A reference to the default ClassOfService resources used for provisioning from the storage pool.

5.11. The Volume resource

Volume resource represents a block-addressable container of storage, sometimes referred to as a "Logical Unit", "LU", "LUN", or "StorageVolume" in the storage industry. Volumes optionally adhere to a ClassOfService, which defines added functionality. Examples include:

• Access capabilities
• Capacity and capacity sources
• Consumption tracking (e.g., LowSpaceWarningThresholdPercents)
• Replication details
• StorageGroup Information

5.12. The FileSystem resource

This FileSystem resource represents a file system. File systems represent file-addressable capacity that are conformant to a ClassOfService. Each FileSystem may contain a collection of FileShares that can be presented to hosts.

6. Data model

6.1. Swordfish extensions to Redfish

Overview

Redfish has added two properties to the ServiceRoot that provide access to Swordfish resources.

The first is StorageSystems. This property references a collection of ComputerSystem resources that each support Swordfish functionality. Each such ComputerSystem shall have:

• an entry in its HostingRoles property with the value of StorageServer
• at least one entry in its StorageServices.Members property.

The second is StorageServices. This property references a collection of StorageService resources. It provides the client an efficient means to search across all StorageService resources, regardless of which ComputerSystem is supporting the service.

Swordfish and Redfish specific OEM or vendor extensions

The Swordfish and Redfish models are extended by subclassing the OEM ComplexTypes that are defined in the Swordfish and Redfish schemas.

OData specific OEM or vendor extensions

In addition to extending the Redfish model as described above. An OEM may extend the Redfish ServiceContainer by defining a new EntityContainer that extends the ServiceContainer found in the Redfish ServiceRoot_v1.xml file, (see OData EntityContainer).

Note: This has the same semantics as subclassing in a typical object oriented environment.

An OEM extended implementation of the Swordfish service would access OEM extensions to EntityContainer via the service entry-point /redfish/v1/odata.

6.2. Entity Sets

The Swordfish model does not currently expose any explicitly defined entity sets. OData specifies that an entity set is defined for each NavigationProperty that is defined as a collection and that has the ContainsTarget attribute set to true. In all other cases, Swordfish assumes that an entity set is defined globally within the implementation for each entity type. This is effectively the same as if the entity sets were explicitly defined in the ServiceRoot entity container.

6.3. Addressing entities within a collection

An instance (entity) of an EntityType is uniquely identified within its entity set by its key. The URI for the reference may specify the key using one of two general strategies

1. OData recommends specifying the key value within parenthesis following the path segment that identifies the referencing entity set. (See clause "Canonical URL" in in OData)

2. Redfish common practice is to use an alternative form that adds a path segment having the value of the key following the path segment that identifies the referencing collection. (See clause "Alternate Key-as-Segment Syntax" in OData.)

A Swordfish implementation shall support both strategies.

6.4. Addressing members of a ResourceCollection

Redfish specifies that subclasses of ResourceCollection shall include a Members collection property (See clause "Collection resource response" in DSP0266)

Redfish allows a POST request to a ResourceCollection to be equivalent to the same POST request to the Members property of that ResourceCollection.
For a particular ResourceCollection, if a Swordfish implementation supports either form, it shall support both.

It is common practice in Redfish to also eliminate the Members property from any request URI that navigates through a type hierarchy that includes a Member within a ResourceCollection. Care should be taken when defining and using a ResourceCollection subclass to not introduce ambiguities when an explicit reference to a Members property is dropped from a request URI.

6.5. Schema repository

The primary online source for the Swordfish schema shall be co-located on the DMTF schema site with the Redfish schema: http://redfish.dmtf.org/schemas/swordfish Developers may also download the schema as part of the Swordfish bundle from snia.org (refer to snia.org/swordfish for pointers to the bundle locations).

Implementations should refer either to the versions available on the dmtf.org site or to locally provided instances of the schema.

6.6. Referencing other schemas

Swordfish directly reference the following Redfish schemas. - Chassis - ChassisCollection - ComputerSystem - ComputerSystemCollection - Drive - Endpoint - EthernetInterface - EventService - Location - RedfishExtensions - Redundancy - ResourceTask - Schedule - ServiceContainer - ServiceRoot

Other Redfish schema may be added by inference or directly to implementations. Examples are available in the Swordfish mockups.

7. Schema Considerations

7.1. Schema Introduction and Overview

A complete Swordfish implementation includes a Redfish-defined Service Root, is instantiated upon a StorageSystem/ComputerSystem, and runs on a Redfish Chassis. At the same time, a storage client may focus entirely on the storage schema instantiations and never interact with the Redfish portion of an implementation.

Swordfish is defined in terms of schema extended from Redfish which are defined below. This section provides additional definition and context for these schema.

7.2. Common schema attributes

The following table lists common schema attributes used in the definition of Swordfish, for details see CSDL

7.3. Default values and NULLABLE attributes

The interaction of Nullable and DefaultValue needs to be clearly understood by both implementers and client developers. The possible combinations of are summarized in Table 6. The table contains:

• Nullable: True, if a given property may be NULL
• DefaultValue: True, if a default value is provided for a given property
• Client: True, if a client value is supplied for a given property in a query or response
• Result: The resultant value of the given property. One of:
  • C: The client-provided value
  • D: The default value
  • Null: Null
  • I: Implementation defined
  • Error: Error state

Table 6: Default and Nullable Interaction

7.4. Common schema annotations

The following table lists common annotation used in the definition of Swordfish, for details see OData Capabilities Vocabulary, OData Core Vocabulary, OData Measures Vocabulary, and Redfish Extensions,

7.5. Schema repository

The primary online source for the Swordfish schema shall be co-located on the DMTF schema site with the Redfish schema: http://redfish.dmtf.org/schemas/swordfish Developers may also download the schema as part of the Swordfish bundle from snia.org (refer to snia.org/swordfish for pointers to the bundle locations).

Implementations should refer either to the versions available on the dmtf.org site or to locally provided instances of the schema.

7.6. Referencing other schemas

Swordfish directly reference the following Redfish schemas. - Chassis - ChassisCollection - ComputerSystem - ComputerSystemCollection - Drive - Endpoint - EthernetInterface - EventService - Location - RedfishExtensions - Redundancy - ResourceTask - Schedule - ServiceContainer - ServiceRoot

Other Redfish schema may be added by inference or directly to implementations. Examples are available in the Swordfish mockups.

8. Implementation requirements

8.1. Security

This document generally adheres to the security requirements defined in the Redfish Specification. It extends the Redfish security model in one important way:

• Swordfish implementations shall implement TLS version 1.2 or greater.

8.2. General constraints

The Swordfish service interface extends the Redfish service interface. As such, a Swordfish service is a Redfish service and all required elements of the Redfish model shall be present in a Swordfish model.

Swordfish functionality shall not conflict with any previously defined Redfish functionality but it may add to or extend it, and it may add additional constraints on Redfish functionality.

Additionally, any functionality desired in a Swordfish implementation that is specified in Redfish shall follow the requirements as specified in the Redfish specification.

8.3. Discovering Swordfish resources

Each Swordfish implementation supports the following well-known URLs, as defined in Redfish. Specifically:

• /Redfish, which contains one or more version properties for the integrated Swordfish and Redfish implementation, starting with v1.
• /Redfish/v1, which addresses a ServiceRoot instance, which defines the Redfish default principal starting information for version 1 implementation of an integrated Redfish and Swordfish service. A GET operation to it shall retrieve the value of an instance of a ServiceRoot EntityType as defined in the ServiceRoot_v1.xml file.
• /Redfish/v1/odata, which addresses a ServiceContainer instance, which defines OData conformant principal starting information for the same version 1 implementation of an integrated Redfish and Swordfish service. A GET operation shall retrieve the value of an instance of a ServiceContainer EntityContainer as defined in the ServiceRoot_v1.xml file.

Note: Since the ServiceContainer is required to return an @odata.context value of /redfish/v1, all other elements accessed via it will be the same elements found via the ServiceRoot.

Note: A Swordfish service is a Redfish service with extensions to support storage management. No additional service entry-points are necessary.

Both the ServiceRoot and ServiceContainer contain a resource collection named Systems that lists ComputerSystem instances. A ComputerSystem instance that supports Swordfish defined services will have a value of "StorageServer" in an entry of its HostingRoles property.

The ServiceContainer additionally has a Service attribute that references the ServiceRoot resource.

Regardless of starting point, the property values of the ServiceRoot instance enable navigation to all other resources exposed by the Swordfish service.

8.4. ClassOfService requirements

Each ClassOfService shall include at least one line of service. The providing server shall assure that the line of service values of a ClassOfService collectively represent a supported choice of service.

8.5. StorageSystems requirements

This property of the ServiceRoot references a collection of ComputerSystem resources that each support Swordfish functionality. Each ComputerSystem included in the StorageSystems entry in the ServiceRoot shall have:

• an entry in its HostingRoles property with the value of StorageServer
• at least one entry in its StorageServices.Members property.

8.6. Entity Sets

The Swordfish model does not currently expose any explicitly defined entity sets. OData specifies that an entity set is defined for each NavigationProperty that is defined as a collection and that has the ContainsTarget attribute set to true. In all other cases, Swordfish assumes that an entity set is defined globally within the implementation for each entity type. This is effectively the same as if the entity sets were explicitly defined in the ServiceRoot entity container.

8.7. Addressing entities within a collection

An instance (entity) of an EntityType is uniquely identified within its entity set by its key. The URI for the reference may specify the key using one of two general strategies

1. OData recommends specifying the key value within parenthesis following the path segment that identifies the referencing entity set. (See clause "Canonical URL" in in OData)

2. Redfish common practice is to use an alternative form that adds a path segment having the value of the key following the path segment that identifies the referencing collection. (See clause "Alternate Key-as-Segment Syntax" in OData.)

A Swordfish implementation shall support both strategies.

8.8. Addressing members of a ResourceCollection

Redfish specifies that subclasses of ResourceCollection shall include a Members collection property (See clause "Collection resource response" in DSP0266)

Redfish allows a POST request to a ResourceCollection to be equivalent to the same POST request to the Members property of that ResourceCollection. For a particular ResourceCollection, if a Swordfish implementation supports either form, it shall support both.

It is common practice in Redfish to also eliminate the Members property from any request URI that navigates through a type hierarchy that includes a Member within a ResourceCollection. Care should be taken when defining and using a ResourceCollection subclass to not introduce ambiguities when an explicit reference to a Members property is dropped from a request URI.

9. Swordfish type definitions

9.1. Overview

The following sections define the schema and type definitions that make up a Swordfish implementation. Each data type or entity within the schema includes a description that defines its implementation requirements and their interaction.

9.2. 9.2. 9.2. --- title: Schema Documentation

language tabs: - shell

9.3. search: true

9.4. ClassOfService 1.0.0

This resource shall define a service option composed of one or more service options. ITIL defines a service option as a choice of utility or warranty for a service.

9.5. ClassOfServiceCollection

This collection shall contain references to all ClassOfService resource instances sharing the same parent resource.

9.6. DataProtectionLoSCapabilities 1.0.0

The capabilities to protect data from loss by the use of a replica. The requirements shall be met collectively by the communication path and the replica. There should be one instance associated to a class of service for each replica. Each replica independently should have a class of service that describes its characteristics.

Property Details

RecoveryGeographicObjective:

RecoveryTimeObjective:

ReplicaType:

9.7. DataSecurityLoSCapabilities 1.0.0

This resource may be used to describe data security capabilities.

Property Details

ChannelEncryptionStrength:

DataSanitizationPolicy:

HostAuthenticationType:

MediaEncryptionStrength:

SecureChannelProtocol:

UserAuthenticationType:

9.8. DataStorageLoSCapabilities 1.0.0

Each instance of DataStorageLoSCapabilities describes capabilities of the system to support various data storage service options.

Property Details

ProvisioningPolicy:

9.9. DriveCollection

An instance of this resource shall reference the set of Drive resources known in the scope of its use.

9.10. EndpointCollection

An instance of this resource shall reference the set of Endpoint resources known in the scope of its use.

9.11. EndpointGroup 1.0.0

An EndpointGroup represents a collection of endpoints that are managed as a unit. By grouping together a collection of Endpoints, the EndpointGroup allows a collection of entities from differing sources or hosts to be manipulated uniformly and efficiently.

For any given EndpointGroup, all of its endpoints act exclusively as either server endpoints or client endpoints, as indicated by the value of the EndpointType property. Similarly, each Endpoint within a group has the same AccessState.

A server or client may define multiple EndpointGroup entities that access the same set of resources or functionality. A group may be designated as preferred, which signifies that access should be directed through its members in preference to the Endpoints listed in other EndpointGroups. If the value of EndpointType is Server, an EndpointGroup entity can be used to represent target port group as defined by SCSI. In that mode, the value of the TargetEndpointGroupIdentifier should correspond to the target port group number. (See clause "Device Identification VPD page" as defined in the SCSI Primary Commands specification.)

Property Details

AccessState:

GroupType:

9.12. EndpointGroupCollection

An instance of this resource shall reference the set of Endpoint group resources known in the scope of its use.

Property Details

AccessState:

GroupType:

9.13. FileShare 1.0.0

This resource shall be used to represent a shared set of files with a common directory structure.

Property Details

FileShareQuotaType:

WritePolicy:

9.14. FileSystem 1.0.0

This resource shall be used to represent an instance of a hierarchical namespace of files.

Property Details

ConsistencyState:

ConsistencyStatus:

ConsistencyType:

FileShareQuotaType:

ReplicaPriority:

ReplicaProgressStatus:

ReplicaReadOnlyAccess:

ReplicaRecoveryMode:

ReplicaRole:

ReplicaState:

ReplicaType:

ReplicaUpdateMode:

RequestedReplicaState:

UndiscoveredElement:

WritePolicy:

9.15. FileSystemCollection

This resource shall contain a collection of references to FileSystem resource instances.

9.16. HostedStorageServices

A Collection of Hosted Storage Service resource instances.

9.17. IOConnectivityLoSCapabilities 1.0.0

Each instance of IOConnectivityLoSCapabilities describes capabilities of the system to support various IO Connectivity service options.

Property Details

AccessProtocol:

9.18. IOPerformanceLoSCapabilities 1.0.0

Each instance of IOPerformanceLoSCapabilities shall describe the capabilities of the system to support various IO performance service options.

9.19. StorageGroup 1.0.0

The primary purposes of the collection shall be to govern access to the storage by clients or to add service requirements for the members of the collection. Access to the collected storage by a specified set of hosts shall be made available or unavailable atomically. Requirements specified by the class of service shall be satisfied by each collected element to which they apply. The storage group may contain: block, file, or object storage; local storage system access points through which the collection is made available; and hosts, or host access points to which the collection is made available.

Property Details

ConsistencyState:

ConsistencyStatus:

ConsistencyType:

ReplicaPriority:

ReplicaProgressStatus:

ReplicaReadOnlyAccess:

ReplicaRecoveryMode:

ReplicaRole:

ReplicaState:

ReplicaType:

ReplicaUpdateMode:

RequestedReplicaState:

UndiscoveredElement:

9.20. StorageGroupCollection

This collection shall contain references to all StorageGroup resource instances sharing the same parent resource.

9.21. StoragePool 1.0.0

A container of data storage capable of providing capacity conforming to one of its supported classes of service. The storage pool does not support IO to its data storage.

9.22. StoragePoolCollection

This collection shall contain references to all StoragePool resource instances sharing the same parent resource.

9.23. StorageService 1.0.0

Collection of resources that the system can make available to one or more host systems. The collection can contain: block, file, or object storage; local system access points through which the collection is made available; hosts, or host access points to which the collection is made available.

9.24. StorageServiceCollection

An instance of this resource shall reference the set of StorageService resources known in the scope of its use.

9.25. StorageSystemCollection

An instance of this resource shall reference the set of ComputerSystem resources known in the scope of its use and and that has a HostingRoles entry with a value of 'StorageServer'.

9.26. Volume 1.1.0

This resource shall be used to represent a volume, virtual disk, logical disk, LUN, or other logical storage for a Redfish implementation.