Shared File Systems API¶

This is a reference for version 2 of the OpenStack Shared File Systems API which is provided by the Manila project. Manila provides a RESTful HTTP service through which it offers on-demand, scalable, self-service access to shared file system storage resources.

Important

Prior to the Wallaby release, Shared File System service required the caller to specify their “project_id” in the API URLs. This requirement has been dropped. The API service now behaves the same way whether or not “project_id” is included in the URLs. If your cloud does not yet support version 2.60, all the resource URLs below will require a project ID. For example:

GET /v2/{project_id}/shares

API versions¶

Lists information for all Shared File Systems API versions.

Concepts¶

In order to bring new features to users over time, the Shared File Systems API supports versioning. There are two kinds of versions in the Shared File Systems API:

‘’major versions’’, which have dedicated URLs
‘’microversions’’, which can be requested through the use of the X-OpenStack-Manila-API-Version header

Read more about microversion guidelines that the service adheres to here

See A history of the Shared File Systems API versions to view the evolution of the API and pick an appropriate version for API requests.

GET

List All Major Versions

This fetches all the information about all known major API versions in the deployment. Links to more specific information will be provided for each API version, as well as information about supported min and max microversions.

Response codes¶

Success¶

Code	Reason
`300 - Multiple Choices`	The resource corresponds to more than one representation.

Response¶

Name	In	Type	Description
versions	body	array	A list of version objects that describe the API versions available.
id	body	string	A common name for the version in question. Informative only, it has no real semantic meaning.
updated	body	string	A date and time stamp for API versions. This field presents no meaningful information.
status	body	string	The status of this API version. This can be one of: `CURRENT`: this is the preferred version of the API to use `SUPPORTED`: this is an older, but still supported version of the API `DEPRECATED`: a deprecated version of the API that is slated for removal
links	body	array	Pagination and bookmark links for the resource.
media-types	body	object	Media types supported by the API.
version	body	string	If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.
min_version	body	string	If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.

Note

The updated and media-types parameters in the response are vestigial and provide no useful information. They will probably be deprecated and removed in the future.

Response Example¶

This demonstrates the expected response from a bleeding edge server that supports up to the current microversion. When querying OpenStack environments you will typically find the current microversion on the v2.1 API is lower than listed below.

{
    "versions": [
        {
            "status": "DEPRECATED",
            "updated": "2015-08-27T11:33:21Z",
            "links": [
                {
                    "href": "http://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://172.18.198.54:8786/v1/",
                    "rel": "self"
                }
            ],
            "min_version": "",
            "version": "",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.share+json;version=1"
                }
            ],
            "id": "v1.0"
        },
        {
            "status": "CURRENT",
            "updated": "2015-08-27T11:33:21Z",
            "links": [
                {
                    "href": "http://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://172.18.198.54:8786/v2/",
                    "rel": "self"
                }
            ],
            "min_version": "2.0",
            "version": "2.15",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.share+json;version=1"
                }
            ],
            "id": "v2.0"
        }
    ]
}

GET

/{api_version}/

Show Details of Specific API Version

This gets the details of a specific API at it’s root. Nearly all this information exists at the API root, so this is mostly a redundant operation.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Request¶

Name	In	Type	Description
api_version	path	string	The API version as returned in the links from the `GET /` call.

Response¶

Name	In	Type	Description
version	body	string	The version.
id	body	string	A common name for the version in question. Informative only, it has no real semantic meaning.
status	body	string	The status of this API version. This can be one of: `CURRENT`: this is the preferred version of the API to use `SUPPORTED`: this is an older, but still supported version of the API `DEPRECATED`: a deprecated version of the API that is slated for removal
links	body	array	Pagination and bookmark links for the resource.
version	body	string	If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.
updated	body	string	A date and time stamp for API versions. This field presents no meaningful information.
min_version	body	string	If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.
media-types	body	object	Media types supported by the API.

Note

The updated and media-types parameters in the response are vestigial and provide no useful information. They will probably be deprecated and removed in the future.

Response Example¶

This is an example of a GET /v2/ on a relatively current server.

{
    "versions": [
        {
            "status": "CURRENT",
            "updated": "2015-08-27T11:33:21Z",
            "links": [
                {
                    "href": "http://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://172.18.198.54:8786/v2/",
                    "rel": "self"
                }
            ],
            "min_version": "2.0",
            "version": "2.15",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.share+json;version=1"
                }
            ],
            "id": "v2.0"
        }
    ]
}

API extensions¶

Lists available Shared File Systems API extensions.

GET

/v2/extensions

List extensions

Lists all extensions.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).

Response parameters¶

Name	In	Type	Description
name	body	string	The name of the extension. For example, “Fox In Socks.”
links	body	array	The extension links.
description	body	string	The description of the extension API.
alias	body	string	The alias for the extension. For example, “FOXNSOX”, “os-availability-zone”, “os-extended-quotas”, “os- share-unmanage”, or “os-used-limits”.
updated	body	string	The date and time stamp when the extension API was last updated. The date and time stamp format is ISO 8601: :: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2015-08-27T09:49:58-05:00`.

Response example¶

{
    "extensions": [
        {
            "alias": "os-extended-quotas",
            "updated": "2013-06-09T00:00:00+00:00",
            "name": "ExtendedQuotas",
            "links": [],
            "description": "Extend quotas. Adds ability for admins to delete quota and optionally force the update Quota command."
        },
        {
            "alias": "os-quota-sets",
            "updated": "2011-08-08T00:00:00+00:00",
            "name": "Quotas",
            "links": [],
            "description": "Quotas management support."
        },
        {
            "alias": "os-quota-class-sets",
            "updated": "2012-03-12T00:00:00+00:00",
            "name": "QuotaClasses",
            "links": [],
            "description": "Quota classes management support."
        },
        {
            "alias": "os-share-unmanage",
            "updated": "2015-02-17T00:00:00+00:00",
            "name": "ShareUnmanage",
            "links": [],
            "description": "Enable share unmanage operation."
        },
        {
            "alias": "os-types-manage",
            "updated": "2011-08-24T00:00:00+00:00",
            "name": "TypesManage",
            "links": [],
            "description": "Types manage support."
        },
        {
            "alias": "share-actions",
            "updated": "2012-08-14T00:00:00+00:00",
            "name": "ShareActions",
            "links": [],
            "description": "Enable share actions."
        },
        {
            "alias": "os-availability-zone",
            "updated": "2015-07-28T00:00:00+00:00",
            "name": "AvailabilityZones",
            "links": [],
            "description": "Describe Availability Zones."
        },
        {
            "alias": "os-user-quotas",
            "updated": "2013-07-18T00:00:00+00:00",
            "name": "UserQuotas",
            "links": [],
            "description": "Project user quota support."
        },
        {
            "alias": "os-share-type-access",
            "updated": "2015-03-02T00:00:00Z",
            "name": "ShareTypeAccess",
            "links": [],
            "description": "share type access support."
        },
        {
            "alias": "os-types-extra-specs",
            "updated": "2011-08-24T00:00:00+00:00",
            "name": "TypesExtraSpecs",
            "links": [],
            "description": "Type extra specs support."
        },
        {
            "alias": "os-admin-actions",
            "updated": "2015-08-03T00:00:00+00:00",
            "name": "AdminActions",
            "links": [],
            "description": "Enable admin actions."
        },
        {
            "alias": "os-used-limits",
            "updated": "2014-03-27T00:00:00+00:00",
            "name": "UsedLimits",
            "links": [],
            "description": "Provide data on limited resources that are being used."
        },
        {
            "alias": "os-services",
            "updated": "2012-10-28T00:00:00-00:00",
            "name": "Services",
            "links": [],
            "description": "Services support."
        },
        {
            "alias": "os-share-manage",
            "updated": "2015-02-17T00:00:00+00:00",
            "name": "ShareManage",
            "links": [],
            "description": "Allows existing share to be 'managed' by Manila."
        }
    ]
}

Limits¶

Limits are the resource limitations that are allowed for each tenant (project). An administrator can configure limits in the manila.conf file.

Users can query their rate and absolute limits. The absolute limits contain information about:

Total maximum share memory, in GiBs.
Number of share-networks.
Number of share-snapshots.
Number of shares.
Shares and total used memory, in GiBs.
Snapshots and total used memory, in GiBs.
Number of share replicas (since API version 2.53).
Share replicas and total used memory, in GiBs (since API version 2.53).

Rate limits control the frequency at which users can issue specific API requests. Administrators use rate limiting to configure limits on the type and number of API calls that can be made in a specific time interval. For example, a rate limit can control the number of GET requests that can be processed during a one-minute period.

Lists share limits.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).

Response parameters¶

Name	In	Type	Description
maxTotalShareGigabytes	body	integer	The total maximum number of share gigabytes that are allowed in a project. You cannot request a share that exceeds the allowed gigabytes quota.
maxTotalSnapshotGigabytes	body	integer	The total maximum number of snapshot gigabytes that are allowed in a project.
maxTotalShares	body	integer	The total maximum number of shares that are allowed in a project.
maxTotalShareSnapshots	body	integer	The total maximum number of share snapshots that are allowed in a project.
maxTotalShareNetworks	body	integer	The total maximum number of share-networks that are allowed in a project.
maxTotalShareReplicas	body	integer	The maximum number of share replicas that is allowed. New in version 2.53
maxTotalReplicaGigabytes	body	integer	The maximum number of replica gigabytes that are allowed in a project. You cannot create a share, share replica, manage a share or extend a share if it is going to exceed the allowed replica gigabytes quota. New in version 2.53
maxTotalShareBackups	body	integer	The total maximum number of share backups that are allowed in a project. New in version 2.80
maxTotalBackupGigabytes	body	integer	The total maximum number of backup gigabytes that are allowed in a project. New in version 2.80
totalSharesUsed	body	integer	The total number of created shares in a project.
totalShareSnapshotsUsed	body	integer	The total number of created share snapshots in a project.
totalShareNetworksUsed	body	integer	The total number of created share-networks in a project.
totalShareGigabytesUsed	body	integer	The total number of gigabytes used in a project by shares.
totalSnapshotGigabytesUsed	body	integer	The total number of gigabytes used in a project by snapshots.
totalShareReplicasUsed	body	integer	The total number of created share replicas in a project.
totalReplicaGigabytesUsed	body	integer	The total number of replica gigabytes used in a project by share replicas.
totalShareBackupsUsed	body	integer	The total number of created share backups in a project.
totalBackupGigabytesUsed	body	integer	The total number of gigabytes used in a project by backups.
uri (Optional)	body	string	A human-readable URI of a rate limit.
regex (Optional)	body	string	An API regular expression. For example, `^/shares` for the `/shares` API URI or `.*` for any URI.
value (Optional)	body	integer	The number of API requests that are allowed during a time interval. Used in conjunction with the `unit` parameter, expressed as `value` per `unit`. For example, 120 requests are allowed per minute.
verb (Optional)	body	string	The HTTP method for the API request. For example, `GET`, `POST`, `DELETE`, and so on.
remaining (Optional)	body	integer	The remaining number of allowed requests.
unit (Optional)	body	string	The time interval during which a number of API requests are allowed. A valid value is `SECOND`, `MINUTE`, `HOUR`, or `DAY`. Used in conjunction with the `value` parameter, expressed as `value` per `unit`. For example, 120 requests are allowed per minute.
next-available (Optional)	body	string	The date and time stamp when next issues are available. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2015-08-27T09:49:58-05:00`.

Response example¶

{
    "limits": {
        "rate": [],
        "absolute": {
            "totalShareNetworksUsed": 0,
            "maxTotalShareGigabytes": 1000,
            "maxTotalShareNetworks": 10,
            "totalSharesUsed": 0,
            "totalShareGigabytesUsed": 0,
            "totalShareSnapshotsUsed": 0,
            "maxTotalShares": 50,
            "totalSnapshotGigabytesUsed": 0,
            "maxTotalSnapshotGigabytes": 1000,
            "maxTotalShareSnapshots": 50,
            "maxTotalShareReplicas": 100,
            "maxTotalReplicaGigabytes": 1000,
            "totalShareReplicasUsed": 0,
            "totalReplicaGigabytesUsed": 0,
            "maxTotalShareBackups": 100,
            "maxTotalBackupGigabytes": 1000,
            "totalShareBackupsUsed": 0,
            "totalBackupGigabytesUsed": 0
        }
    }
}

Shares¶

A share is a remote, mountable file system. In the APIs below, a share resource is a representation of this remote file system within the Shared File Systems service. This resource representation includes useful metadata, communicating the characteristics of the remote file system as determined by the user and the Shared File Systems service.

You can create a share and associate it with a network, list shares, and show information for, update, and delete a share.

To create a share, specify one of these supported protocols:

NFS. Network File System (NFS).
CIFS. Common Internet File System (CIFS).
GLUSTERFS. Gluster file system (GlusterFS).
HDFS. Hadoop Distributed File System (HDFS).
CEPHFS. Ceph File System (CephFS).
MAPRFS. MapR File System (MAPRFS).

You can also create snapshots of shares. To create a snapshot, you specify the ID of the share that you want to snapshot.

A share has one of these status values:

Share statuses

Status	Description
`backup_creating`	The share is being backed up.
`backup_restoring`	The share is being restored from backup.
`backup_restoring_error`	An error occurred during share backup restore.
`creating`	The share is being created.
`creating_from_snapshot`	The share is being created from a parent snapshot.
`deleting`	The share is being deleted.
`deleted`	The share was deleted.
`error`	An error occurred during share creation.
`error_deleting`	An error occurred during share deletion.
`available`	The share is ready to use.
`inactive`	The share is inactive.
`manage_starting`	Share manage started.
`manage_error`	Share manage failed.
`unmanage_starting`	Share unmanage started.
`unmanage_error`	Share cannot be unmanaged.
`unmanaged`	Share was unmanaged.
`extending`	The extend, or increase, share size request was issued successfully.
`extending_error`	Extend share failed.
`shrinking`	Share is being shrunk.
`shrinking_error`	Failed to update quota on share shrinking.
`shrinking_possible_data_loss_error`	Shrink share failed due to possible data loss.
`migrating`	Share is currently migrating.
`migrating_to`	Share is a migration destination.
`replication_change`	The share is undergoing a replication change.
`reverting`	Share is being reverted to a snapshot.
`reverting_error`	Share revert to snapshot failed.
`awaiting_transfer`	Share is being transferred to a different project’s namespace.

GET

/v2/shares

List shares

Lists all shares.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name (Optional)	query	string	The user defined name of the resource to filter resources by.
status (Optional)	query	string	Filters by a share status. For valid statuses, see the section above.
share_server_id (Optional)	query	string	The UUID of the share server.
metadata (Optional)	query	object	One or more metadata key and value pairs as a url encoded dictionary of strings.
extra_specs (Optional)	query	string	The extra specifications as a set of one or more key-value pairs. In each pair, the key is the name of the extra specification and the value is the share type that was used to filter search share type list. The query must be a “percent-encoded” string, for example, the following query parameters: {‘extra-specs’: {‘snapshot_support’: ‘true’, ‘availability_zones’: ‘az1’}} is encoded as ‘extra_specs=%7B%27snapshot_support%27%3A+%27true%27%2C+%27availability_zones%27%3A+%27az1%27%7D’ New in version 2.43
share_type_id (Optional)	query	string	The UUID of a share type to query resources by.
snapshot_id (Optional)	query	string	The UUID of the share’s base snapshot to filter the request based on.
source_backup_id (Optional)	query	string	The UUID of the share’s backup to filter the request based on.
host (Optional)	query	string	The host name of the resource to query with. Querying by hostname is a privileged operation. If restricted by API policy, this query parameter may be silently ignored by the server.
share_network_id (Optional)	query	string	The UUID of the share network to filter resources by.
project_id (Optional)	query	string	The ID of the project that owns the resource. This query parameter is useful in conjunction with the `all_tenants` parameter.
is_public (Optional)	query	boolean	A boolean query parameter that, when set to true, allows retrieving public resources that belong to all projects.
share_group_id (Optional)	query	string	The UUID of a share group to filter resource. New in version 2.31
export_location_id (Optional)	query	string	The export location UUID that can be used to filter shares or share instances. New in version 2.35
export_location_path (Optional)	query	string	The export location path that can be used to filter shares or share instances. New in version 2.35
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
description~ (Optional)	query	string	The description pattern that can be used to filter shares, share snapshots, share networks or share groups. New in version 2.36
with_count (Optional)	query	boolean	Whether to show `count` in share list API response or not, default is `False`. This query parameter is useful with pagination. New in version 2.42
is_soft_deleted (Optional)	query	boolean	A boolean query parameter that, when set to True, will return all shares in recycle bin. Default is False, will return all shares not in recycle bin. New in version 2.69
limit (Optional)	query	integer	The maximum number of resource records to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of shares. A valid value is `id`, `status`, `size`, `host`, `share_proto`, `export_location`, `availability_zone`, `user_id`, `project_id`, `created_at`, `updated_at`, `display_name`, `name`, `share_type_id`, `share_type`, `share_network_id`, `share_network`, `snapshot_id`, or `snapshot`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share.
links	body	array	Pagination and bookmark links for the resource.
name	body	string	The user defined name of the resource.
count (Optional)	body	integer	The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query. New in version 2.42

Response example¶

{
    "shares": [
        {
            "id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/shares/d94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/d94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "bookmark"
                }
            ],
            "name": "My_share"
        },
        {
            "id": "406ea93b-32e9-4907-a117-148b3945749f",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/shares/406ea93b-32e9-4907-a117-148b3945749f",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/406ea93b-32e9-4907-a117-148b3945749f",
                    "rel": "bookmark"
                }
            ],
            "name": "Share1"
        }
    ],
    "count": 10
}

GET

/v2/shares/detail

List shares with details

Lists all shares, with details.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
status (Optional)	query	string	Filters by a share status. For valid statuses, see the section above.
share_server_id (Optional)	query	string	The UUID of the share server.
metadata (Optional)	query	object	One or more metadata key and value pairs as a url encoded dictionary of strings.
extra_specs (Optional)	query	string	The extra specifications as a set of one or more key-value pairs. In each pair, the key is the name of the extra specification and the value is the share type that was used to filter search share type list. The query must be a “percent-encoded” string, for example, the following query parameters: {‘extra-specs’: {‘snapshot_support’: ‘true’, ‘availability_zones’: ‘az1’}} is encoded as ‘extra_specs=%7B%27snapshot_support%27%3A+%27true%27%2C+%27availability_zones%27%3A+%27az1%27%7D’ New in version 2.43
share_type_id (Optional)	query	string	The UUID of a share type to query resources by.
name (Optional)	query	string	The user defined name of the resource to filter resources by.
snapshot_id (Optional)	query	string	The UUID of the share’s base snapshot to filter the request based on.
source_backup_id (Optional)	query	string	The UUID of the share’s backup to filter the request based on.
host (Optional)	query	string	The host name of the resource to query with. Querying by hostname is a privileged operation. If restricted by API policy, this query parameter may be silently ignored by the server.
share_network_id (Optional)	query	string	The UUID of the share network to filter resources by.
project_id (Optional)	query	string	The ID of the project that owns the resource. This query parameter is useful in conjunction with the `all_tenants` parameter.
is_public (Optional)	query	boolean	A boolean query parameter that, when set to true, allows retrieving public resources that belong to all projects.
share_group_id (Optional)	query	string	The UUID of a share group to filter resource. New in version 2.31
export_location_id (Optional)	query	string	The export location UUID that can be used to filter shares or share instances. New in version 2.35
export_location_path (Optional)	query	string	The export location path that can be used to filter shares or share instances. New in version 2.35
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
description~ (Optional)	query	string	The description pattern that can be used to filter shares, share snapshots, share networks or share groups. New in version 2.36
with_count (Optional)	query	boolean	Whether to show `count` in share list API response or not, default is `False`. This query parameter is useful with pagination. New in version 2.42
is_soft_deleted (Optional)	query	boolean	A boolean query parameter that, when set to True, will return all shares in recycle bin. Default is False, will return all shares not in recycle bin. New in version 2.69
limit (Optional)	query	integer	The maximum number of resource records to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of shares. A valid value is `id`, `status`, `size`, `host`, `share_proto`, `export_location`, `availability_zone`, `user_id`, `project_id`, `created_at`, `updated_at`, `display_name`, `name`, `share_type_id`, `share_type`, `share_network_id`, `share_network`, `snapshot_id`, or `snapshot`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share.
size	body	integer	The share size, in GiBs.
availability_zone	body	string	The name of the availability zone the share exists within.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share or share instance status. Possible values are listed in the section above.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
snapshot_id	body	string	The UUID of the snapshot that was used to create the share.
source_backup_id	body	string	The UUID of the backup that was restored in the share. New in version 2.80
share_network_id	body	string	The share network ID where the resource is exported to.
share_proto	body	string	The Shared File Systems protocol. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS`, `MAPRFS`, `CephFS` supported is starting with API v2.13.
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.
share_type	body	string	The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.
links	body	array	Pagination and bookmark links for the resource.
is_public	body	boolean	Whether the share is visible publicly (by all projects in the cloud) or not.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
snapshot_support	body	boolean	Whether or not this share supports snapshots. Snapshots are point in time backups of the share. New in version 2.2
task_state	body	string	For the share migration, the migration task state. A valid value is `null`, `migration_starting`, `migration_error`, `migration_success`, `migration_completing`, or `migrating`. The `task_state` is `null` unless the share is migrated from one back-end to another. New in version 2.5
share_type_name	body	string	Name of the share type.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
replication_type	body	string	The share replication type. The value can be: `null`, if the share cannot be replicated. `readable`, if one or more read-only replicas of the share can be created `writable`, if one or more active replicas of the share can be created `dr`, if one or more replicas of the share can be created that will remain inaccessible until they are promoted. New in version 2.11
has_replicas	body	boolean	Indicates whether a share has replicas or not. New in version 2.11
user_id	body	string	ID of the user that the share was created by. New in version 2.16
create_share_from_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”) New in version 2.24
revert_to_snapshot_support	body	boolean	Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.27
share_group_id	body	string	The UUID of the share group. New in version 2.31
source_share_group_snapshot_member_id	body	string	ID of the group snapshot instance that was the source of this share. New in version 2.31
mount_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.32
progress	body	string	The progress of the share creation. New in version 2.54
count (Optional)	body	integer	The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query. New in version 2.42
volume_type	body	string	The share type ID. This is a legacy parameter that contains the same value as the `share_type` parameter. Do not rely on this parameter as it may be removed in a future API revision.
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
is_soft_deleted (Optional)	body	boolean	Whether the share has been soft deleted to recycle bin or not. New in version 2.69
scheduled_to_be_deleted_at (Optional)	body	string	Estimated time at which the share in the recycle bin will be deleted automatically. New in version 2.69

Response example¶

{
    "shares": [
        {
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "share_network_id": "f9b2e754-ac01-4466-86e1-5c569424754e",
            "export_locations": [],
            "share_server_id": "87d8943a-f5da-47a4-b2f2-ddfa6794aa82",
            "share_group_id": null,
            "snapshot_id": null,
            "source_backup_id": null,
            "id": "f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc",
            "size": 1,
            "share_type": "25747776-08e5-494f-ab40-a64b9d20d8f7",
            "share_type_name": "default",
            "export_location": null,
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "metadata": {},
            "status": "error",
            "progress": null,
            "access_rules_status": "active",
            "description": "There is a share description.",
            "host": "manila2@generic1#GENERIC1",
            "task_state": null,
            "is_public": true,
            "snapshot_support": true,
            "user_id": "66ffd308757e44b9a8bec381322b0b88",
            "name": "my_share4",
            "has_replicas": false,
            "replication_type": null,
            "created_at": "2015-09-16T18:19:50.000000",
            "share_proto": "NFS",
            "volume_type": "default"
        },
        {
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/c4a2ced4-2c9f-4ae1-adaa-6171833e64df",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/c4a2ced4-2c9f-4ae1-adaa-6171833e64df",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "share_network_id": "f9b2e754-ac01-4466-86e1-5c569424754e",
            "export_locations": [
                "10.254.0.5:/shares/share-50ad5e7b-f6f1-4b78-a651-0812cef2bb67"
            ],
            "share_server_id": "87d8943a-f5da-47a4-b2f2-ddfa6794aa82",
            "snapshot_id": null,
            "source_backup_id": null,
            "id": "c4a2ced4-2c9f-4ae1-adaa-6171833e64df",
            "size": 1,
            "share_type": "25747776-08e5-494f-ab40-a64b9d20d8f7",
            "share_type_name": "default",
            "export_location": "10.254.0.5:/shares/share-50ad5e7b-f6f1-4b78-a651-0812cef2bb67",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "metadata": {},
            "status": "available",
            "progress": "100%",
            "access_rules_status": "active",
            "description": "Changed description.",
            "host": "manila2@generic1#GENERIC1",
            "task_state": null,
            "is_public": true,
            "snapshot_support": true,
            "name": "my_share4",
            "has_replicas": false,
            "replication_type": null,
            "created_at": "2015-09-16T17:26:28.000000",
            "user_id": "66ffd308757e44b9a8bec381322b0b88",
            "share_proto": "NFS",
            "volume_type": "default"
        }
    ],
    "count": 10
}

Shows details for a share.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share.
size	body	integer	The share size, in GiBs.
availability_zone	body	string	The name of the availability zone the share exists within.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share or share instance status. Possible values are listed in the section above.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
snapshot_id	body	string	The UUID of the snapshot that was used to create the share.
share_network_id	body	string	The share network ID where the resource is exported to.
share_proto	body	string	The Shared File Systems protocol. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS`, `MAPRFS`, `CephFS` supported is starting with API v2.13.
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.
share_type	body	string	The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.
links	body	array	Pagination and bookmark links for the resource.
is_public	body	boolean	Whether the share is visible publicly (by all projects in the cloud) or not.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
snapshot_support	body	boolean	Whether or not this share supports snapshots. Snapshots are point in time backups of the share. New in version 2.2
task_state	body	string	For the share migration, the migration task state. A valid value is `null`, `migration_starting`, `migration_error`, `migration_success`, `migration_completing`, or `migrating`. The `task_state` is `null` unless the share is migrated from one back-end to another. New in version 2.5
share_type_name	body	string	Name of the share type.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
replication_type	body	string	The share replication type. The value can be: `null`, if the share cannot be replicated. `readable`, if one or more read-only replicas of the share can be created `writable`, if one or more active replicas of the share can be created `dr`, if one or more replicas of the share can be created that will remain inaccessible until they are promoted. New in version 2.11
has_replicas	body	boolean	Indicates whether a share has replicas or not. New in version 2.11
user_id	body	string	ID of the user that the share was created by. New in version 2.16
create_share_from_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”) New in version 2.24
revert_to_snapshot_support	body	boolean	Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.27
share_group_id	body	string	The UUID of the share group. New in version 2.31
source_share_group_snapshot_member_id	body	string	ID of the group snapshot instance that was the source of this share. New in version 2.31
mount_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.32
progress	body	string	The progress of the share creation. New in version 2.54
count (Optional)	body	integer	The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query. New in version 2.42
volume_type	body	string	The share type ID. This is a legacy parameter that contains the same value as the `share_type` parameter. Do not rely on this parameter as it may be removed in a future API revision.
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
is_soft_deleted (Optional)	body	boolean	Whether the share has been soft deleted to recycle bin or not. New in version 2.69
scheduled_to_be_deleted_at (Optional)	body	string	Estimated time at which the share in the recycle bin will be deleted automatically. New in version 2.69

Response example¶

{
    "share": {
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "export_locations": [],
        "share_server_id": "e268f4aa-d571-43dd-9ab3-f49ad06ffaef",
        "share_group_id": null,
        "snapshot_id": null,
        "id": "011d21e2-fbc3-4e4a-9993-9ea223f73264",
        "size": 1,
        "share_type": "25747776-08e5-494f-ab40-a64b9d20d8f7",
        "share_type_name": "default",
        "export_location": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "metadata": {
            "project": "my_app",
            "aim": "doc"
        },
        "status": "available",
        "progress": "100%",
        "description": "My custom share London",
        "host": "manila2@generic1#GENERIC1",
        "user_id": "66ffd308757e44b9a8bec381322b0b88",
        "access_rules_status": "active",
        "has_replicas": false,
        "replication_type": null,
        "task_state": null,
        "is_public": true,
        "snapshot_support": true,
        "name": "share_London",
        "created_at": "2015-09-18T10:25:24.000000",
        "share_proto": "NFS",
        "volume_type": "default"
    }
}

Added in version 2.3.

Lists instances of a share.

A share instance is an internal representation for a share. A share that is replicated or is in the process of being migrated is physically stored in multiple locations. Each of these individual locations is called an “instance” within the Shared File Systems service. End users need not be concerned with this internal representation. As an administrator, you can list all instances of a share through this endpoint resource. Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Response parameters¶

Name	In	Type	Description
status	body	string	The share or share instance status. Possible values are listed in the section above.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
share_id	body	string	The UUID of the share to which the share instance belongs to.
progress	body	string	The progress of the share creation. New in version 2.54
availability_zone	body	string	The name of the availability zone the share exists within.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
replica_state	body	string	The share replica state. Has set value only when replication is used. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`. New in version 2.11
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
cast_rules_to_readonly	body	boolean	If the share instance has its `cast_rules_to_readonly` attribute set to True, all existing access rules will be cast to read/only. New in version 2.30
share_network_id	body	string	The share network ID where the resource is exported to.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
share_type_id	path	string	The UUID of the share type.
id	body	string	The share instance ID.

Response example¶

{
    "share_instances": [
        {
            "status": "error",
            "progress": null,
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T08:41:20.000000",
            "updated_at": "2015-09-07T08:43:10.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "access_rules_status": "active",
            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
            "id": "081f7030-c54f-42f5-98ee-93a37393e0f2"
        },
        {
            "status": "available",
            "progress": "100%",
            "share_id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T08:51:34.000000",
            "updated_at": "2015-09-10T02:01:22.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "access_rules_status": "active",
            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
            "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
        },
        {
            "status": "creating_from_snapshot",
            "progress": "30%",
            "share_id": "9bb15af4-27e5-4174-ae15-dc549d4a3b51",
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T09:01:15.000000",
            "updated_at": "2015-09-07T09:02:30.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "access_rules_status": "active",
            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
            "id": "48155648-2fd3-480d-b02b-44b995c24bab"
        }
    ]
}

Creates a share.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_proto	body	string	The Shared File Systems protocol. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS`, `MAPRFS`, `CephFS` supported is starting with API v2.13.
size	body	integer	The share size, in GiBs. The requested share size cannot be greater than the allowed GiB quota. To view the allowed quota, issue a get limits request.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
display_name (Optional)	body	string	The user defined name of the resource. This field sets the `name` parameter.
display_description (Optional)	body	string	The user defined description of the resource. This field sets the `description` parameter.
share_type (Optional)	body	string	The name or ID of the share type to be used to create the resource. If you omit this parameter, the default share type is used. To view the default share type set by the administrator, issue a list default share types request.
snapshot_id (Optional)	body	string	The UUID of the share’s base snapshot.
is_public (Optional)	body	boolean	The level of visibility for the share. Set to `true` to make share visible to all projects in the cloud. Set to `false` to make it private to your project. Default value is `false`.
share_group_id (Optional)	body	string	The UUID of the share group. New in version 2.31
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.
share_network_id (Optional)	body	string	The ID of a share network that the resource must be exported to. Note that when using a share type with the `driver_handles_share_servers` extra spec as `False`, you should not provide a `share_network_id`.
availability_zone (Optional)	body	string	The UUID or name of an availability zone for resource to be created within.
scheduler_hints (Optional)	body	object	One or more scheduler_hints key and value pairs as a dictionary of strings. Accepted hints are: - `same_host` or `different_host`: values must be a comma separated list of Share IDs - `only_host`: value must be a manage-share service host in `host@backend#POOL` format (admin only). Only available in and beyond API version 2.67 New in version 2.65

Request example¶

{
    "share": {
        "description": "My custom share London",
        "share_type": null,
        "share_proto": "nfs",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "share_group_id": null,
        "name": "share_London",
        "snapshot_id": null,
        "is_public": true,
        "size": 1,
        "metadata": {
            "project": "my_app",
            "aim": "doc"
        },
        "scheduler_hints": {
            "same_host": "d9c66489-cf02-4156-b0f2-527f3211b243,4ffee55f-ba98-42d2-a8ce-e7cecb169182",
            "different_host": "903685eb-f242-4105-903d-4bef2db94be4"
        }
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share.
size	body	integer	The share size, in GiBs.
availability_zone	body	string	The name of the availability zone the share exists within.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share or share instance status. Possible values are listed in the section above.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
snapshot_id	body	string	The UUID of the snapshot that was used to create the share.
share_network_id	body	string	The share network ID where the resource is exported to.
share_proto	body	string	The Shared File Systems protocol. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS`, `MAPRFS`, `CephFS` supported is starting with API v2.13.
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.
share_type	body	string	The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.
links	body	array	Pagination and bookmark links for the resource.
is_public	body	boolean	Whether the share is visible publicly (by all projects in the cloud) or not.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
snapshot_support	body	boolean	Whether or not this share supports snapshots. Snapshots are point in time backups of the share. New in version 2.2
task_state	body	string	For the share migration, the migration task state. A valid value is `null`, `migration_starting`, `migration_error`, `migration_success`, `migration_completing`, or `migrating`. The `task_state` is `null` unless the share is migrated from one back-end to another. New in version 2.5
share_type_name	body	string	Name of the share type.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
replication_type	body	string	The share replication type. The value can be: `null`, if the share cannot be replicated. `readable`, if one or more read-only replicas of the share can be created `writable`, if one or more active replicas of the share can be created `dr`, if one or more replicas of the share can be created that will remain inaccessible until they are promoted. New in version 2.11
has_replicas	body	boolean	Indicates whether a share has replicas or not. New in version 2.11
user_id	body	string	ID of the user that the share was created by. New in version 2.16
create_share_from_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”) New in version 2.24
revert_to_snapshot_support	body	boolean	Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.27
share_group_id	body	string	The UUID of the share group. New in version 2.31
source_share_group_snapshot_member_id	body	string	ID of the group snapshot instance that was the source of this share. New in version 2.31
mount_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.32
progress	body	string	The progress of the share creation. New in version 2.54
count (Optional)	body	integer	The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query. New in version 2.42
volume_type	body	string	The share type ID. This is a legacy parameter that contains the same value as the `share_type` parameter. Do not rely on this parameter as it may be removed in a future API revision.
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
is_soft_deleted (Optional)	body	boolean	Whether the share has been soft deleted to recycle bin or not. New in version 2.69
scheduled_to_be_deleted_at (Optional)	body	string	Estimated time at which the share in the recycle bin will be deleted automatically. New in version 2.69

Response example¶

{
    "share": {
        "status": null,
        "progress": null,
        "share_server_id": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "name": "share_London",
        "share_type": "25747776-08e5-494f-ab40-a64b9d20d8f7",
        "share_type_name": "default",
        "availability_zone": null,
        "created_at": "2015-09-18T10:25:24.533287",
        "export_location": null,
        "links": [
            {
                "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "bookmark"
            }
        ],
        "share_network_id": null,
        "share_group_id": null,
        "export_locations": [],
        "share_proto": "NFS",
        "host": null,
        "access_rules_status": "active",
        "has_replicas": false,
        "replication_type": null,
        "task_state": null,
        "snapshot_support": true,
        "volume_type": "default",
        "snapshot_id": null,
        "is_public": true,
        "metadata": {
            "project": "my_app",
            "aim": "doc"
        },
        "id": "011d21e2-fbc3-4e4a-9993-9ea223f73264",
        "size": 1,
        "description": "My custom share London"
    }
}

Added in version 2.7.

Use this API to bring a share under the management of the Shared File Systems service.

Administrator only. Use the policy.yaml file to grant permissions for this action to other roles.

Note

Managing shares that are created on top of managed share servers (i.e. with parameter share_server_id) is not supported prior to API version 2.49.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share	body	object	A `share` object.
protocol	body	string	The Shared File Systems protocol of the share to manage. A valid value is `NFS`, `CIFS`, `GlusterFS`, `CEPHFS`, `HDFS` or `MAPRFS`.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
share_type (Optional)	body	string	The name or ID of the share type to be used to create the resource. If you omit this parameter, the default share type is used. To view the default share type set by the administrator, issue a list default share types request.
driver_options (Optional)	body	object	A set of one or more key and value pairs, as a dictionary of strings, that describe driver options. Details for driver options should be taken from appropriate share driver documentation.
export_path	body	string	The share export path in the format appropriate for the protocol: NFS protocol. `10.0.0.1:/foo_path`. For example, `10.254.0 .5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5`. CIFS protocol. For example, `\\10.0.0.1\foo_name_of_cifs_share`.
service_host	body	string	The manage-share service host in this format: `host@backend#POOL`: `host`. The host name for the back end. `backend`. The name of the back end. `POOL`. The pool name for the back end.
share_server_id	body	string	The UUID of the share server. New in version 2.49
is_public (Optional)	body	boolean	The level of visibility for the share. Set to `true` to make share visible to all projects in the cloud. Set to `false` to make it private to your project. Default value is `false`. New in version 2.8
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.

Request example¶

{
    "share": {
        "protocol": "nfs",
        "name": "accounting_p8787",
        "share_type": "gold",
        "driver_options": {
            "opt1": "opt1",
            "opt2": "opt2"
        },
        "export_path": "192.162.10.6:/shares/share-accounting_p8787",
        "service_host": "manila2@openstackstor01#accountingpool",
        "is_public": true,
        "description": "Common storage for spreadsheets and presentations. Please contact John Accessman to be added to the users of this drive.",
        "share_server_id": "00137b40-ca06-4ae8-83a3-2c5989eebcce"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share.
size	body	integer	The share size, in GiBs.
availability_zone	body	string	The name of the availability zone the share exists within.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share or share instance status. Possible values are listed in the section above.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
snapshot_id	body	string	The UUID of the snapshot that was used to create the share.
share_network_id	body	string	The share network ID where the resource is exported to.
share_proto	body	string	The Shared File Systems protocol. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS`, `MAPRFS`, `CephFS` supported is starting with API v2.13.
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.
share_type	body	string	The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.
links	body	array	Pagination and bookmark links for the resource.
is_public	body	boolean	Whether the share is visible publicly (by all projects in the cloud) or not.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
snapshot_support	body	boolean	Whether or not this share supports snapshots. Snapshots are point in time backups of the share. New in version 2.2
task_state	body	string	For the share migration, the migration task state. A valid value is `null`, `migration_starting`, `migration_error`, `migration_success`, `migration_completing`, or `migrating`. The `task_state` is `null` unless the share is migrated from one back-end to another. New in version 2.5
share_type_name	body	string	Name of the share type.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
replication_type	body	string	The share replication type. The value can be: `null`, if the share cannot be replicated. `readable`, if one or more read-only replicas of the share can be created `writable`, if one or more active replicas of the share can be created `dr`, if one or more replicas of the share can be created that will remain inaccessible until they are promoted. New in version 2.11
has_replicas	body	boolean	Indicates whether a share has replicas or not. New in version 2.11
user_id	body	string	ID of the user who brought the share under manila management. New in version 2.16
create_share_from_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”) New in version 2.24
revert_to_snapshot_support	body	boolean	Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.27
share_group_id	body	string	The UUID of the share group. New in version 2.31
source_share_group_snapshot_member_id	body	string	ID of the group snapshot instance that was the source of this share. New in version 2.31
mount_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.32
progress	body	string	The progress of the share creation. New in version 2.54
count (Optional)	body	integer	The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query. New in version 2.42
volume_type	body	string	The share type ID. This is a legacy parameter that contains the same value as the `share_type` parameter. Do not rely on this parameter as it may be removed in a future API revision.
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
is_soft_deleted (Optional)	body	boolean	Whether the share has been soft deleted to recycle bin or not. New in version 2.69
scheduled_to_be_deleted_at (Optional)	body	string	Estimated time at which the share in the recycle bin will be deleted automatically. New in version 2.69

Response example¶

{
    "share": {
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/00137b40-ca06-4ae8-83a3-2c5989eebcce",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/00137b40-ca06-4ae8-83a3-2c5989eebcce",
                "rel": "bookmark"
            }
        ],
        "availability_zone": null,
        "share_network_id": null,
        "export_locations": [],
        "share_server_id": "00137b40-ca06-4ae8-83a3-2c5989eebcce",
        "share_group_id": null,
        "snapshot_id": null,
        "id": "00137b40-ca06-4ae8-83a3-2c5989eebcce",
        "size": null,
        "share_type": "14747856-08e5-494f-ab40-a64b9d20d8f7",
        "share_type_name": "d",
        "export_location": "10.254.0.5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "metadata": {},
        "status": "manage_starting",
        "description": "Lets manage share.",
        "user_id": "66ffd308757e44b9a8bec381322b0b88",
        "host": "manila2@unmanage1#UNMANAGE1",
        "access_rules_status": "active",
        "has_replicas": false,
        "replication_type": null,
        "is_public": false,
        "snapshot_support": true,
        "name": "share_texas1",
        "created_at": "2019-03-05T10:00:00.000000",
        "share_proto": "NFS",
        "volume_type": "d"
    }
}

Updates a share.

You can update these attributes:

display_name, which also changes the name of the share.
display_description, which also changes the description of the share.
is_public. Changes the level of visibility.

If you try to update other attributes, they retain their previous values.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
is_public (Optional)	body	boolean	The level of visibility for the share. Set to `true` to make share visible to all projects in the cloud. Set to `false` to make it private to your project. Default value is `false`.
display_name (Optional)	body	string	The user defined name of the resource. This field sets the `name` parameter.
display_description (Optional)	body	string	The user defined description of the resource. This field sets the `description` parameter.

Request example¶

{
    "share": {
        "is_public": true,
        "display_description": "Changing the share description."
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share.
size	body	integer	The share size, in GiBs.
availability_zone	body	string	The name of the availability zone the share exists within.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share or share instance status. Possible values are listed in the section above.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
snapshot_id	body	string	The UUID of the snapshot that was used to create the share.
share_network_id	body	string	The share network ID where the resource is exported to.
share_proto	body	string	The Shared File Systems protocol. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS`, `MAPRFS`, `CephFS` supported is starting with API v2.13.
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.
share_type	body	string	The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.
links	body	array	Pagination and bookmark links for the resource.
is_public	body	boolean	Whether the share is visible publicly (by all projects in the cloud) or not.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
snapshot_support	body	boolean	Whether or not this share supports snapshots. Snapshots are point in time backups of the share. New in version 2.2
task_state	body	string	For the share migration, the migration task state. A valid value is `null`, `migration_starting`, `migration_error`, `migration_success`, `migration_completing`, or `migrating`. The `task_state` is `null` unless the share is migrated from one back-end to another. New in version 2.5
share_type_name	body	string	Name of the share type.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
replication_type	body	string	The share replication type. The value can be: `null`, if the share cannot be replicated. `readable`, if one or more read-only replicas of the share can be created `writable`, if one or more active replicas of the share can be created `dr`, if one or more replicas of the share can be created that will remain inaccessible until they are promoted. New in version 2.11
has_replicas	body	boolean	Indicates whether a share has replicas or not. New in version 2.11
user_id	body	string	ID of the user that the share was created by. New in version 2.16
create_share_from_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”) New in version 2.24
revert_to_snapshot_support	body	boolean	Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.27
share_group_id	body	string	The UUID of the share group. New in version 2.31
source_share_group_snapshot_member_id	body	string	ID of the group snapshot instance that was the source of this share. New in version 2.31
mount_snapshot_support	body	boolean	Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”). New in version 2.32
progress	body	string	The progress of the share creation. New in version 2.54
count (Optional)	body	integer	The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query. New in version 2.42
volume_type	body	string	The share type ID. This is a legacy parameter that contains the same value as the `share_type` parameter. Do not rely on this parameter as it may be removed in a future API revision.
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
is_soft_deleted (Optional)	body	boolean	Whether the share has been soft deleted to recycle bin or not. New in version 2.69
scheduled_to_be_deleted_at (Optional)	body	string	Estimated time at which the share in the recycle bin will be deleted automatically. New in version 2.69

Response example¶

{
    "share": {
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "export_locations": [],
        "share_server_id": "e268f4aa-d571-43dd-9ab3-f49ad06ffaef",
        "share_group_id": null,
        "snapshot_id": null,
        "id": "011d21e2-fbc3-4e4a-9993-9ea223f73264",
        "size": 1,
        "share_type": "25747776-08e5-494f-ab40-a64b9d20d8f7",
        "share_type_name": "default",
        "export_location": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "metadata": {
            "project": "my_app",
            "aim": "doc"
        },
        "status": "error",
        "description": "Changing the share description.",
        "host": "manila2@generic1#GENERIC1",
        "task_state": null,
        "is_public": true,
        "snapshot_support": true,
        "name": "share_London",
        "created_at": "2015-09-18T10:25:24.000000",
        "share_proto": "NFS",
        "volume_type": "default",
        "user_id": "66ffd308757e44b9a8bec381322b0b88"
    }
}

Deletes a share.

Preconditions

Share status must be available, error or inactive
You cannot already have a snapshot of the share.
You cannot already have a group snapshot of the share.
You cannot already have a replica of the share.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Share export locations (since API v2.9)¶

Set of APIs used for viewing export locations of shares.

These APIs allow retrieval of export locations belonging to non-active share replicas until API version 2.46. In and beyond API version 2.47, export locations of non-active share replicas can only be retrieved using the Share Replica Export Locations APIs.

GET

/v2/shares/{share_id}/export_locations

List export locations

Added in version 2.9.

Lists all export locations for a share.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Response parameters¶

Name	In	Type	Description
id	body	string	The share export location UUID.
share_instance_id	body	string	The UUID of the share instance that this export location belongs to. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy.yaml.
path	body	string	The export location path that should be used for mount operation.
is_admin_only	body	boolean	Defines purpose of an export location. If set to `true`, then it is expected to be used for service needs and by administrators only. If it is set to `false`, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.
preferred	body	boolean	Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to `false` value. New in version 2.14

Response example¶

{
    "export_locations": [
        {
            "path": "10.254.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "is_admin_only": false,
            "id": "b6bd76ce-12a2-42a9-a30a-8a43b503867d",
            "preferred": false
        },
        {
            "path": "10.0.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "is_admin_only": true,
            "id": "6921e862-88bc-49a5-a2df-efeed9acd583",
            "preferred": false
        }
    ]
}

GET

/v2/shares/{share_id}/export_locations/{export_location_id}

Show single export location

Added in version 2.9.

Show details of an export location belonging to a share.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
export_location_id	path	string	The UUID of the export location.

Response parameters¶

Name	In	Type	Description
id	body	string	The share export location UUID.
share_instance_id	body	string	The UUID of the share instance that this export location belongs to. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy.yaml.
path	body	string	The export location path that should be used for mount operation.
is_admin_only	body	boolean	Defines purpose of an export location. If set to `true`, then it is expected to be used for service needs and by administrators only. If it is set to `false`, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.
preferred	body	boolean	Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to `false` value. New in version 2.14
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.

Response example¶

{
    "export_location": {
        "created_at": "2016-03-24T14:20:47.000000",
        "updated_at": "2016-03-24T14:20:47.000000",
        "preferred": false,
        "is_admin_only": true,
        "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
        "path": "10.0.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
        "id": "6921e862-88bc-49a5-a2df-efeed9acd583"
    }
}

Share metadata¶

Shows, sets, updates, and unsets share metadata.

Shows all the metadata for a share, as key and value pairs.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "project": "my_app",
        "aim": "doc"
    }
}

Retrieves a specific metadata item from a share’s metadata by its key. If the specified key does not represent a valid metadata item, the API will respond with HTTP 404.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
key	body	object	The key of a metadata item. For example, if the metadata on an existing resource is as follows: `"project": "my_test", "aim": "testing"`, the keys are “project” and “aim”.

Response parameters¶

Name	In	Type	Description
metadata	body	object	A single metadata key and value pair.

Response example¶

{
    "meta": {
        "project": "my_app"
    }
}

Allows adding new metadata items as key-value pairs. This API will not delete pre-existing metadata items. If the request object contains metadata items that already exist, they will be updated with new values as specified in the request object.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
metadata	body	object	One or more metadata key-value pairs, as a dictionary of strings. For example, `"project": "my_test", "aim": "testing"`. The share server does not respect case-sensitive key names. For example, `"key": "v1"` and `"KEY": "V1"` are equivalent. If you specify both key-value pairs, the server sets and returns only the `"KEY": "V1"` key-value pair.

Request example¶

{
    "metadata": {
        "key1": "value1"
    }
}

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "key1": "value1",
        "new_metadata_key": "new_information",
        "key": "value"
    }
}

Replaces the metadata for a given share with the metadata (specified as key-value pairs) in the request object. All pre-existing metadata of the share will be deleted and replaced with the new metadata supplied.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
metadata	body	object	One or more metadata key-value pairs, as a dictionary of strings. For example, `"project": "my_test", "aim": "testing"`. The share server does not respect case-sensitive key names. For example, `"key": "v1"` and `"KEY": "V1"` are equivalent. If you specify both key-value pairs, the server sets and returns only the `"KEY": "V1"` key-value pair.

Request example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "new_metadata_key": "new_information"
    }
}

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "new_metadata_key": "new_information"
    }
}

To delete all existing metadata items on a given share, the request object needs to specify an empty metadata object:

Request example¶

{
    "metadata": null
}

Response example¶

{
    "metadata": null
}

Deletes a single metadata item on a share, idetified by its key. If the specified key does not represent a valid metadata item, the API will respond with HTTP 404.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
key	body	object	The key of a metadata item. For example, if the metadata on an existing resource is as follows: `"project": "my_test", "aim": "testing"`, the keys are “project” and “aim”.

Share actions¶

Share actions include granting or revoking share access, listing the available access rules for a share, explicitly updating the state of a share, resizing a share and un-managing a share.

As administrator, you can reset the state of a share and force- delete a share in any state. Use the policy.yaml file to grant permissions for this action to other roles.

You can set the state of a share to one of these supported states:

available
error
creating
deleting
error_deleting

If API version 1.0-2.6 is used then all share actions, defined below, should include prefix os- in top element of request JSON’s body.

For example: {“access_list”: null} is valid for v2.7+. And {“os- access_list”: null} is valid for v1.0-2.6

POST

/v2/shares/{share_id}/action

Grant access

All manila shares begin with no access. Clients must be provided with explicit access via this API.

To grant access, specify one of these supported share access levels:

rw. Read and write (RW) access.
ro. Read-only (RO) access.

You must also specify one of these supported authentication methods:

ip. Authenticates an instance through its IP address. The value specified should be a valid IPv4 or an IPv6 address, or a subnet in CIDR notation. A valid format is X:X:X:X:X:X:X:X, X:X:X:X:X:X:X:X/XX, XX.XX.XX.XX, or XX.XX.XX.XX/XX, etc. For example 0.0.0.0/0 or ::/0.

Important

IPv6 based access is only supported with API version 2.38 and beyond.

Note

Starting from API version 2.82, it is possible to lock the deletion, restrict the visibility of sensible fields of the access rules, and specify a reason for such locks while invoking the grant access API through the parameters lock_deletion, lock_visibility and lock_reason respectively.

cert. Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.
user. Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 255 characters long.

Grants access to a share.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
allow_access	body	object	The object of grant access.
access_level	body	string	The access level to the share. To grant or deny access to a share, you specify one of the following share access levels: `rw`. Read and write (RW) access. `ro`. Read-only (RO) access.
access_type	body	string	The access rule type. A valid value for the share access rule type is one of the following values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_to	body	string	The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
metadata	body	object	One or more access rule metadata key and value pairs as a dictionary of strings. New in version 2.45
lock_visibility (Optional)	body	string	Whether the resource should have its sensitive fields restricted or not. When enabled, other users will see the “access_to” and “access_secret” fields set to New in version 2.82**
lock_deletion (Optional)	body	string	Whether the resource should have its deletion locked or not. New in version 2.82
lock_reason	body	string	A blob of text representing the reason for the specific resource lock.

Request example¶

{
    "allow_access": {
        "access_level": "rw",
        "access_type": "ip",
        "access_to": "0.0.0.0/0",
        "metadata":{
            "key1": "value1",
            "key2": "value2"
        },
        "lock_visibility": false,
        "lock_deletion": true,
        "lock_reason": "Locked for deletion until year end audit."
    }
}

Response parameters¶

Name	In	Type	Description
share_id	body	string	The UUID of the share to which you are granted or denied access.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
access_type	body	string	The access rule type. A valid value for the share access rule type is one of the following values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_to	body	string	The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_key	body	string	The access credential of the entity granted share access. New in version 2.21
access	body	object	The `access` object.
access_level	body	string	The access level to the share. To grant or deny access to a share, you specify one of the following share access levels: `rw`. Read and write (RW) access. `ro`. Read-only (RO) access.
id	body	string	The access rule ID.
metadata	body	object	One or more access rule metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "access": {
        "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
        "created_at": "2015-09-07T09:14:48.000000",
        "updated_at": null,
        "access_type": "ip",
        "access_to": "0.0.0.0/0",
        "access_level": "rw",
        "access_key": null,
        "id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452",
        "metadata":{
            "key1": "value1",
            "key2": "value2"
        }
    }
}

POST

/v2/shares/{share_id}/action

Revoke access

The shared file systems service stores each access rule in its database and assigns it a unique ID. This ID can be used to revoke access after access has been requested.

Note

In case the access rule had its deletion locked, it will be necessary to provide the unrestrict parameter in the revoke access request.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
deny_access	body	object	The `deny_access` object.
access_id	body	string	The UUID of the access rule to which access is granted.
unrestrict (Optional)	body	string	Whether the service should attempt to remove deletion restrictions during the access rule deletion or not. New in version 2.82

Request example¶

{
    "deny_access": {
        "access_id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452",
        "unrestrict": true
    }
}

POST

/v2/shares/{share_id}/action

List access rules (DEPRECATED)

Warning

This API is deprecated starting with microversion 2.45 and requests to this API will fail with a 404 starting from microversion 2.45. Use List share access rules API instead of this API from version 2.45.

Lists access rules for a share. The Access ID returned is necessary to deny access.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
access_list	body	string	The object of the access rule. To list access rules, set this value to `null`.

Request example¶

{
    "access_list": null
}

Response parameters¶

Name	In	Type	Description
access_type	body	string	The access rule type. A valid value for the share access rule type is one of the following values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_key	body	string	The access credential of the entity granted share access. New in version 2.21
access_to	body	string	The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_level	body	string	The access level to the share. To grant or deny access to a share, you specify one of the following share access levels: `rw`. Read and write (RW) access. `ro`. Read-only (RO) access.
state	body	string	Prior to versions 2.28, the state of all access rules of a given share is the same at all times. This could be `new`, `active` or `error`. Since 2.28, the state of each access rule of a share is independent of the others and can be `queued_to_apply`, `applying`, `active`, `error`, `queued_to_deny` or `denying`. A new rule starts out in `queued_to_apply` state and is successfully applied if it transitions to `active` state.
access_list	body	string	The object of the access rule. To list access rules, set this value to `null`.
id	body	string	The access rule ID.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.

Response example¶

{
    "access_list": [
        {
            "access_level": "rw",
            "state": "error",
            "id": "507bf114-36f2-4f56-8cf4-857985ca87c1",
            "access_type": "cert",
            "access_to": "example.com",
            "access_key": null
        },
        {
            "access_level": "rw",
            "state": "active",
            "id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452",
            "access_type": "ip",
            "access_to": "0.0.0.0/0",
            "access_key": null
        }
    ]
}

Administrator only. Explicitly updates the state of a share.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
reset_status	body	object	The `reset_status` object.
status	body	string	The share or share instance status to be set. Possible values are listed in the section above.

Request example¶

{
    "reset_status": {
        "status": "error"
    }
}

Administrator only. Force-deletes a share in any state.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
force_delete	body	string	To force-delete a share or share group, set this value to `null`. The force-delete action, unlike the delete action, ignores the share or share group status.

Request example¶

{
    "force_delete": null
}

Increases the size of a share.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
extend	body	object	The `extend` object.
new_size	body	integer	New size of the share, in GiBs.
force (Optional)	body	boolean	(Admin only). Defines whether to go through scheduler, Set to True will extend share directly. Set to False will go through scheduler, default is False. New in version 2.64

Request example¶

{
    "extend": {
        "new_size": 2,
        "force": "true"
    }
}

Shrinks the size of a share.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
shrink	body	object	The `shrink` object.
new_size	body	integer	New size of the share, in GiBs.

Request example¶

{
    "shrink": {
        "new_size": 1
    }
}

Added in version 2.7.

Use this API to remove a share from the management of the Shared File Systems service without deleting the share.

Administrator only. Use the policy.yaml file to grant permissions for this action to other roles.

Preconditions:

You should remove any snapshots and share replicas before attempting to unmanage a share.

Note

Unmanaging shares that are created on top of share servers (i.e. created with share networks) is not supported prior to API version 2.49.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
unmanage	body	string	To unmanage a share, set this value to `null`.

Request example¶

{
    "unmanage": null
}

Response parameters¶

There is no body content for the response.

Added in version 2.27.

Reverts a share to the specified snapshot, which must be the most recent one known to manila.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.
snapshot_id	body	string	The UUID of the snapshot.

Request example¶

{
    "revert": {
        "snapshot_id": "6020af24-a305-4155-9a29-55e20efcb0e8"
    }
}

Added in version 2.69.

Soft delete a share to recycle bin.

Preconditions

Share status must be available, error or inactive
Share can’t have any snapshot.
Share can’t have a share group snapshot.
Share can’t have dependent replicas.
You cannot soft delete share that already is in the Recycle Bin..
You cannot soft delete a share that doesn’t belong to your project.
You cannot soft delete a share is busy with an active task.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Request example¶

{
    "soft_delete": null
}

Added in version 2.69.

Restore a share from recycle bin.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Request example¶

{
    "restore": null
}

Share snapshots¶

Use the Shared File Systems service to make snapshots of shares. A share snapshot is a point-in-time, read-only copy of the data that is contained in a share. The APIs below allow controlling share snapshots. They are represented by a “snapshot” resource in the Shared File Systems service, and they can have user-defined metadata such as a name and description.

You can create, manage, update, and delete share snapshots. After you create or manage a share snapshot, you can create a share from it. You can also revert a share to its most recent snapshot.

You can update a share snapshot to rename it, change its description, or update its state to one of these supported states:

available
error
creating
deleting
error_deleting
manage_starting
manage_error
unmanage_starting
unmanage_error
restoring

As administrator, you can also reset the state of a snapshot and force-delete a share snapshot in any state. Use the policy.yaml file to grant permissions for these actions to other roles.

Lists all share snapshots.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
description~ (Optional)	query	string	The description pattern that can be used to filter shares, share snapshots, share networks or share groups. New in version 2.36
with_count (Optional)	query	boolean	Whether to show `count` in share snapshot list API response or not, default is `False`. This query parameter is useful with pagination. New in version 2.79

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the snapshot.
name	body	string	The user defined name of the resource.

Response example¶

{
    "snapshots": [
        {
            "id": "086a1aa6-c425-4ecd-9612-391a3b1b9375",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/086a1aa6-c425-4ecd-9612-391a3b1b9375",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/086a1aa6-c425-4ecd-9612-391a3b1b9375",
                    "rel": "bookmark"
                }
            ],
            "name": "snapshot_My_share"
        },
        {
            "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                    "rel": "bookmark"
                }
            ],
            "name": "snapshot_share1"
        }
    ]
}

Lists all share snapshots with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
description~ (Optional)	query	string	The description pattern that can be used to filter shares, share snapshots, share networks or share groups. New in version 2.36
with_count (Optional)	query	boolean	Whether to show `count` in share snapshot list API response or not, default is `False`. This query parameter is useful with pagination. New in version 2.79

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the snapshot.
status	body	string	The snapshot status, which can be `available`, `error`, `creating`, `deleting`, `manage_starting`, `manage_error`, `unmanage_starting`, `unmanage_error` or `error_deleting`.
share_id	body	string	The UUID of the source share that was used to create the snapshot.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
share_proto	body	string	The file system protocol of a share snapshot. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS` or `MAPRFS`. `CephFS` is supported starting with API v2.13.
share_size	body	integer	The share snapshot size, in GiBs.
size	body	integer	The snapshot size, in GiBs.
project_id	body	string	ID of the project that the snapshot belongs to. New in version 2.17
user_id	body	string	ID of the user that the snapshot was created by. New in version 2.17
provider_location (Optional)	body	string	Provider location of the snapshot on the backend. This parameter is only available to users with an “administrator” role by virtue of default RBAC. This behavior can be modified by overriding the `context_is_admin` policy via a custom `policy.yaml`. New in version 2.12

Response example¶

{
    "snapshots": [
        {
            "status": "creating",
            "share_id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
            "user_id": "5c7bdb6eb0504d54a619acf8375c08ce",
            "name": "snapshot_My_share",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/086a1aa6-c425-4ecd-9612-391a3b1b9375",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/086a1aa6-c425-4ecd-9612-391a3b1b9375",
                    "rel": "bookmark"
                }
            ],
            "created_at": "2015-09-07T11:55:09.000000",
            "description": "Here is a snapshot of share My_share",
            "share_proto": "NFS",
            "share_size": 1,
            "id": "086a1aa6-c425-4ecd-9612-391a3b1b9375",
            "project_id": "cadd7139bc3148b8973df097c0911016",
            "size": 1
        },
        {
            "status": "available",
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "user_id": "5c7bdb6eb0504d54a619acf8375c08ce",
            "name": "snapshot_share1",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                    "rel": "bookmark"
                }
            ],
            "created_at": "2015-09-07T11:50:39.000000",
            "description": "Here is a snapshot of share Share1",
            "share_proto": "NFS",
            "share_size": 1,
            "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
            "project_id": "cadd7139bc3148b8973df097c0911016",
            "size": 1
        }
    ]
}

Shows details for a share snapshot.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the snapshot.
status	body	string	The snapshot status, which can be `available`, `error`, `creating`, `deleting`, `manage_starting`, `manage_error`, `unmanage_starting`, `unmanage_error` or `error_deleting`.
share_id	body	string	The UUID of the source share that was used to create the snapshot.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
share_proto	body	string	The file system protocol of a share snapshot. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS` or `MAPRFS`. `CephFS` is supported starting with API v2.13.
share_size	body	integer	The share snapshot size, in GiBs.
size	body	integer	The snapshot size, in GiBs.
project_id	body	string	ID of the project that the snapshot belongs to. New in version 2.17
user_id	body	string	ID of the user that the snapshot was created by. New in version 2.17
provider_location (Optional)	body	string	Provider location of the snapshot on the backend. This parameter is only available to users with an “administrator” role by virtue of default RBAC. This behavior can be modified by overriding the `context_is_admin` policy via a custom `policy.yaml`. New in version 2.12

Response example¶

{
    "snapshot": {
        "status": "available",
        "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
        "user_id": "5c7bdb6eb0504d54a619acf8375c08ce",
        "name": "snapshot_share1",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                "rel": "bookmark"
            }
        ],
        "created_at": "2015-09-07T11:50:39.000000",
        "description": "Here is a snapshot of share Share1",
        "share_proto": "NFS",
        "share_size": 1,
        "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
        "project_id": "cadd7139bc3148b8973df097c0911016",
        "size": 1
    }
}

Creates a snapshot from a share.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	body	string	The UUID of the share from which to create a snapshot.
force (Optional)	body	boolean	Indicates whether snapshot creation must be attempted when a share’s status is not `available`. Set to `true` to force snapshot creation when the share is busy performing other operations. Default is `false`.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
display_name (Optional)	body	string	The user defined name of the resource. This field sets the `name` parameter.
display_description (Optional)	body	string	The user defined description of the resource. This field sets the `description` parameter.

Request example¶

{
    "snapshot": {
        "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
        "force": "True",
        "name": "snapshot_share1",
        "description": "Here is a snapshot of share Share1"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the snapshot.
share_id	body	string	The UUID of the source share that was used to create the snapshot.
status	body	string	The snapshot status, which can be `available`, `error`, `creating`, `deleting`, `manage_starting`, `manage_error`, `unmanage_starting`, `unmanage_error` or `error_deleting`.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
share_proto	body	string	The file system protocol of a share snapshot. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS` or `MAPRFS`. `CephFS` is supported starting with API v2.13.
share_size	body	integer	The share snapshot size, in GiBs.
provider_location (Optional)	body	string	Provider location of the snapshot on the backend. This parameter is only available to users with an “administrator” role by virtue of default RBAC. This behavior can be modified by overriding the `context_is_admin` policy via a custom `policy.yaml`. New in version 2.12
size	body	integer	The snapshot size, in GiBs.
project_id	body	string	ID of the project that the snapshot belongs to. New in version 2.17
user_id	body	string	ID of the user that the snapshot was created by. New in version 2.17

Response example¶

{
    "snapshot": {
        "status": "creating",
        "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
        "user_id": "5c7bdb6eb0504d54a619acf8375c08ce",
        "name": "snapshot_share1",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                "rel": "bookmark"
            }
        ],
        "created_at": "2015-09-07T11:50:39.756808",
        "description": "Here is a snapshot of share Share1",
        "share_proto": "NFS",
        "share_size": 1,
        "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
        "project_id": "cadd7139bc3148b8973df097c0911016",
        "size": 1
    }
}

Added in version 2.12.

Configures Shared File Systems to manage a share snapshot.

Note

Managing snapshots of shares that are created on top of share servers (i.e. created with share networks) is not supported prior to API version 2.49.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	body	string	The UUID of the share that has snapshot which should be managed.
provider_location	body	string	Provider location of the snapshot on the backend.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
display_name (Optional)	body	string	The user defined name of the resource. This field sets the `name` parameter.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
display_description (Optional)	body	string	The user defined description of the resource. This field sets the `description` parameter.
driver_options (Optional)	body	object	A set of one or more key and value pairs, as a dictionary of strings, that describe driver options. Details for driver options should be taken from appropriate share driver documentation.

Request example¶

{
    "snapshot": {
        "share_id": "dd6c5d35-9db1-4662-a7ae-8b52f880aeba",
        "provider_location": "4045fee5-4e0e-408e-97f3-15e25239dbc9",
        "name": "managed_snapshot",
        "description": "description_of_managed_snapshot",
        "driver_options": {
            "opt1": "opt1",
            "opt2": "opt2"
        }
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the snapshot.
share_id	body	string	The UUID of the source share that was used to create the snapshot.
status	body	string	The snapshot status, which could be `manage_starting`, `manage_error`, `unmanage_starting`, or `unmanage_error`.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
share_proto	body	string	The file system protocol of a share snapshot. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS` or `MAPRFS`. `CephFS` is supported starting with API v2.13.
share_size	body	integer	The share snapshot size, in GiBs.
provider_location	body	string	Provider location of the snapshot on the backend.
size	body	integer	The snapshot size, in GiBs.
project_id	body	string	ID of the project that the snapshot belongs to. New in version 2.17
user_id	body	string	ID of the user that the snapshot was created by. New in version 2.17

Response example¶

{
    "snapshot": {
        "id": "22de7000-3a32-4fe1-bd0c-38d03f93dec3",
        "share_id": "dd6c5d35-9db1-4662-a7ae-8b52f880aeba",
        "share_size": 1,
        "created_at": "2016-04-01T15:16:17.000000",
        "status": "manage_starting",
        "name": "managed_snapshot",
        "description": "description_of_managed_snapshot",
        "size": 1,
        "share_proto": "NFS",
        "user_id": "5c7bdb6eb0504d54a619acf8375c08ce",
        "project_id": "cadd7139bc3148b8973df097c0911016",
        "links": [
            {
                "href": "http://127.0.0.1:8786/v2/907004508ef4447397ce6741a8f037c1/snapshots/22de7000-3a32-4fe1-bd0c-38d03f93dec3",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:8786/907004508ef4447397ce6741a8f037c1/snapshots/22de7000-3a32-4fe1-bd0c-38d03f93dec3",
                "rel": "bookmark"
            }
        ],
        "provider_location": "4045fee5-4e0e-408e-97f3-15e25239dbc9"
    }
}

Added in version 2.12.

Configures Shared File Systems to stop managing a share snapshot.

Note

Unmanaging snapshots of shares that are created on top of share servers (i.e. created with share networks) is not supported prior to API version 2.49.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.
unmanage	body	string	To unmanage a share snapshot, include this parameter and set its value to `null`.

Request example¶

{
    "unmanage": null
}

Response parameters¶

There is no body content for the response.

Administrator only. Explicitly updates the state of a share snapshot.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.
status (Optional)	body	string	The snapshot status, which can be `available`, `error`, `creating`, `deleting`, `manage_starting`, `manage_error`, `unmanage_starting`, `unmanage_error` or `error_deleting`.

Request example¶

{
    "reset_status": {
        "status": "error"
    }
}

Administrator only. Force-deletes a share snapshot in any state.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.
force_delete	body	string	To force-delete a snapshot, include this param and set its value to `null`. The force-delete action, unlike the delete action, ignores the snapshot status.

Request example¶

{
    "force_delete": null
}

Updates a share snapshot.

You can update these attributes:

display_name, which also changes the name of the share snapshot.
display_description, which also changes the description of the share snapshot.

If you try to update other attributes, they retain their previous values.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.
display_name (Optional)	body	string	The user defined name of the resource. This field sets the `name` parameter.
display_description (Optional)	body	string	The user defined description of the resource. This field sets the `description` parameter.

Request example¶

{
    "snapshot": {
        "display_name": "snapshot_Share1",
        "display_description": "I am changing a description also. Here is a snapshot of share Share1"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the snapshot.
status	body	string	The snapshot status, which can be `available`, `error`, `creating`, `deleting`, `manage_starting`, `manage_error`, `unmanage_starting`, `unmanage_error` or `error_deleting`.
share_id	body	string	The UUID of the source share that was used to create the snapshot.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
share_proto	body	string	The file system protocol of a share snapshot. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS` or `MAPRFS`. `CephFS` is supported starting with API v2.13.
share_size	body	integer	The share snapshot size, in GiBs.
size	body	integer	The snapshot size, in GiBs.
project_id	body	string	ID of the project that the snapshot belongs to. New in version 2.17
user_id	body	string	ID of the user that the snapshot was created by. New in version 2.17

Response example¶

{
    "snapshot": {
        "status": "available",
        "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
        "name": "snapshot_Share1",
        "user_id": "5c7bdb6eb0504d54a619acf8375c08ce",
        "project_id": "cadd7139bc3148b8973df097c0911016",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb",
                "rel": "bookmark"
            }
        ],
        "created_at": "2015-09-07T11:50:39.000000",
        "description": "I am changing a description also. Here is a snapshot of share Share1",
        "share_proto": "NFS",
        "share_size": 1,
        "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
        "size": 1
    }
}

Deletes a share snapshot.

Preconditions

Share snapshot status must be available or error.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.

Snapshot metadata (Since API v2.73)¶

Shows, sets, updates, and unsets snapshot metadata.

GET

/v2/snapshots/{snapshot_id}/metadata

Show all snapshot metadata

Added in version 2.73.

Shows all the metadata for a snapshot, as key and value pairs.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "project": "my_app",
        "aim": "doc"
    }
}

GET

/v2/snapshots/{snapshot_id}/metadata/{key}

Show snapshot metadata item

Added in version 2.73.

Retrieves a specific metadata item from a snapshot’s metadata by its key. If the specified key does not represent a valid metadata item, the API will respond with HTTP 404.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.
key (Optional)	path	string	The key of a metadata item. For example, if the metadata on an existing share or access rule is as follows: `"project": "my_test", "aim": "testing"`, the keys are “project” and “aim”.

Response parameters¶

Name	In	Type	Description
metadata	body	object	A single metadata key and value pair.

Response example¶

{
    "meta": {
        "project": "my_app"
    }
}

POST

/v2/snapshots/{snapshot_id}/metadata

Set snapshot metadata

Added in version 2.73.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.
metadata	body	object	One or more metadata key-value pairs, as a dictionary of strings. For example, `"project": "my_test", "aim": "testing"`. The share server does not respect case-sensitive key names. For example, `"key": "v1"` and `"KEY": "V1"` are equivalent. If you specify both key-value pairs, the server sets and returns only the `"KEY": "V1"` key-value pair.

Request example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "key1": "value1",
        "new_metadata_key": "new_information",
        "key": "value"
    }
}

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "key1": "value1",
        "new_metadata_key": "new_information",
        "key": "value"
    }
}

PUT

/v2/snapshots/{snapshot_id}/metadata

Update snapshot metadata

Added in version 2.73.

Replaces the metadata for a given snapshot with the metadata (specified as key-value pairs) in the request object. All pre-existing metadata of the snapshot will be deleted and replaced with the new metadata supplied.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.
metadata	body	object	One or more metadata key-value pairs, as a dictionary of strings. For example, `"project": "my_test", "aim": "testing"`. The share server does not respect case-sensitive key names. For example, `"key": "v1"` and `"KEY": "V1"` are equivalent. If you specify both key-value pairs, the server sets and returns only the `"KEY": "V1"` key-value pair.

Request example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "new_metadata_key": "new_information"
    }
}

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "new_metadata_key": "new_information"
    }
}

To delete all existing metadata items on a given snapshot, the request object needs to specify an empty metadata object:

Request example¶

{
    "metadata": null
}

Response example¶

{
    "metadata": null
}

DELETE

/v2/snapshots/{snapshot_id}/metadata/{key}

Delete snapshot metadata item

Added in version 2.73.

Deletes a single metadata item on a snapshot, idetified by its key. If the specified key does not represent a valid metadata item, the API will respond with HTTP 404.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id	path	string	The UUID of the snapshot.
key (Optional)	path	string	The key of a metadata item. For example, if the metadata on an existing share or access rule is as follows: `"project": "my_test", "aim": "testing"`, the keys are “project” and “aim”.

Share snapshot instances (since API v2.19)¶

A share snapshot instance is an internal representation for a snapshot of a share. A single snapshot can have multiple snapshot instances if the parent share has multiple instances. When a share is replicated or is in the process of being migrated, it can live in multiple places and each individual location is called an “instance”, internally within the Shared File Systems service.

By default administrators can list, show information for and explicitly set the state of share snapshot instances. Use the policy.yaml file to grant permissions for these actions to other roles.

Added in version 2.19.

Lists all share snapshot instances.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id (Optional)	query	string	The UUID of the share’s base snapshot to filter the request based on.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share snapshot instance.
snapshot_id	body	string	The UUID of the snapshot.
status	body	string	The snapshot instance status. A valid value is `available`, `error`, `creating`, `deleting`, and `error_deleting`, `restoring`, `unmanage_starting`, `unmanage_error`, `manage_starting`, `manage_error`.

Response example¶

{
    "snapshot_instances": [
        {
            "status": "available",
            "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924",
            "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd"
        }
    ]
}

Added in version 2.19.

Lists all share snapshot instances with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_id (Optional)	query	string	The UUID of the share’s base snapshot to filter the request based on.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share snapshot instance.
snapshot_id	body	string	The UUID of the snapshot.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
status	body	string	The snapshot instance status. A valid value is `available`, `error`, `creating`, `deleting`, and `error_deleting`, `restoring`, `unmanage_starting`, `unmanage_error`, `manage_starting`, `manage_error`.
share_id	path	string	The UUID of the share.
share_instance_id	body	string	The UUID of the share instance.
progress	body	string	The progress of the snapshot creation.
provider_location	body	string	Provider location of the snapshot on the backend.

Response example¶

{
    "snapshot_instances": [
        {
            "status": "available",
            "share_id": "618599ab-09a1-432d-973a-c102564c7fec",
            "share_instance_id": "8edff0cb-e5ce-4bab-aa99-afe02ed6a76a",
            "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924",
            "progress": "100%",
            "created_at": "2017-08-04T00:44:52.000000",
            "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd",
            "provider_location": "/path/to/fake/snapshot/snapshot_d447de19_a6d3_40b3_ae9f_895c86798924_275516e8_c998_4e78_a41e_7dd3a03e71cd",
            "updated_at": "2017-08-04T00:44:54.000000"
        }
    ]
}

Added in version 2.19.

Shows details for a share snapshot instance.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_instance_id	path	string	The UUID of the share snapshot instance.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share snapshot instance.
snapshot_id	body	string	The UUID of the snapshot.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
status	body	string	The snapshot instance status. A valid value is `available`, `error`, `creating`, `deleting`, and `error_deleting`, `restoring`, `unmanage_starting`, `unmanage_error`, `manage_starting`, `manage_error`.
share_id	path	string	The UUID of the share.
share_instance_id	body	string	The UUID of the share instance.
progress	body	string	The progress of the snapshot creation.
provider_location	body	string	Provider location of the snapshot on the backend.

Response example¶

{
    "snapshot_instance":
    {
        "status": "available",
        "share_id": "618599ab-09a1-432d-973a-c102564c7fec",
        "share_instance_id": "8edff0cb-e5ce-4bab-aa99-afe02ed6a76a",
        "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924",
        "progress": "100%",
        "created_at": "2017-08-04T00:44:52.000000",
        "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd",
        "provider_location": "/path/to/fake/snapshot/snapshot_d447de19_a6d3_40b3_ae9f_895c86798924_275516e8_c998_4e78_a41e_7dd3a03e71cd",
        "updated_at": "2017-08-04T00:44:54.000000"
    }
}

Added in version 2.19.

Administrator only. Explicitly updates the state of a share snapshot instance.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
snapshot_instance_id	path	string	The UUID of the share snapshot instance.
status	body	string	The snapshot instance status. A valid value is `available`, `error`, `creating`, `deleting`, and `error_deleting`, `restoring`, `unmanage_starting`, `unmanage_error`, `manage_starting`, `manage_error`.

Request example¶

{
    "reset_status": {
        "status": "available"
    }
}

Share replicas (since API v2.11)¶

Share replicas are the replicated copies of the existing share. You can use Share Replicas to sync data so that each share replica has an identical copy of the same share. Share replication can be used as a disaster recovery solution or as a load sharing mirroring solution.

Manila supports replication of shares between different storage pools. These pools may be on different back-end storage systems or within the same back end, depending upon the replication style chosen, the capability of the driver and the configuration of back ends. To ensure that a secondary copy is scheduled to a distinct back end, you must specify the availability_zone attribute.

Note

You can create a replicated share with the help of a share type that has an extra-spec replication_type specified with a valid replication style. Once a replicated share has been created, it always starts out with an active replica. You may then create secondary copies of the share. A secondary copy can be “promoted” to fail-over to becoming the active replica.

To create a share that supports replication, the share type must specify one of these supported replication types:

writable

Synchronously replicated shares where all replicas are writable. Promotion is not supported and not needed because all copies are already exported and can be accessed simultaneously.
readable

Mirror-style replication with a primary (writable) copy and one or more secondary (read-only) copies which can become writable after a promotion.
dr (for Disaster Recovery)

Generalized replication with secondary copies that are inaccessible until they are promoted to become the active replica.

Important

The term active replica refers to the primary share. In writable style of replication, all replicas are active, and there could be no distinction of a primary share. In readable and dr styles of replication, a secondary replica may be referred to as passive, non-active or simply replica.

Added in version 2.11.

Create a share replica for the share.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	body	string	The UUID of the share from which to create a share replica.
availability_zone (Optional)	body	string	The availability zone.
share_network_id (Optional)	body	string	The UUID of the share network.
scheduler_hints (Optional)	body	object	One or more scheduler_hints key and value pairs as a dictionary of strings. Accepted hints are: - `only_host`: value must be a share manager service host in `host@backend#POOL` format (admin only) New in version 2.67

Request example¶

{
    "share_replica": {
        "share_id": "50a6a566-6bac-475c-ad69-5035c86696c0",
        "availability_zone": "nova",
        "scheduler_hints": {
            "only_host": "host1@generic1#GENERIC1"
        }
    }
}

Note

Since API version 2.72, the parameter share_network_id is added which was earlier supported but later deprecated from version 2.51. In case, the parameter is not specified, it will be inherited from its parent share, and the Shared File Systems service will automatically choose which share network subnet your share replica will be placed, according to the specified availability zone.

Response parameters¶

Name	In	Type	Description
share_id	body	string	The UUID of the share from which to create a share replica.
status	body	string	The status of a share replica. List of possible values: `available`, `error`, `creating`, `deleting`, or `error_deleting`.
cast_rules_to_readonly	body	boolean	If the share replica has its `cast_rules_to_readonly` attribute set to True, all existing access rules will be cast to read/only. New in version 2.30
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
share_network_id	body	string	The share network ID where the resource is exported to.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the share replica.
id	body	string	The UUID of the share replica.
replica_state	body	string	The replica state of a share replica. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "share_replica": {
        "status": "creating",
        "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
        "availability_zone": null,
        "cast_rules_to_readonly": true,
        "updated_at": null,
        "share_network_id": null,
        "share_server_id": null,
        "host": "",
        "id": "c9f52e33-d780-41d8-89ba-fc06869f465f",
        "replica_state": null,
        "created_at": "2017-08-15T20:21:43.493731"
    }
}

Added in version 2.11.

Promotes a replica to active replica state.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name

Type

Description

project_id (Optional)

path

string

The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).

share_replica_id

path

string

The UUID of the share replica.

quiesce_wait_time (Optional)

body

integer

The quiesce wait time in seconds used during replica promote.

New in version 2.75

Request example¶

{
    "promote": {
        "quiesce_wait_time": 30
    }
}

Added in version 2.11.

Resync a replica with its active mirror.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_replica_id	path	string	The UUID of the share replica.

Request example¶

{
    "resync": null
}

Added in version 2.11.

Lists share replicas.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Response parameters¶

Name	In	Type	Description
share_id	body	string	The UUID of the share from which to create a share replica.
status	body	string	The status of a share replica. List of possible values: `available`, `error`, `creating`, `deleting`, or `error_deleting`.
id	body	string	The UUID of the share replica.
replica_state	body	string	The replica state of a share replica. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`.

Response example¶

{
    "share_replicas": [
        {
            "status": "available",
            "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
            "id": "57f5c47a-0216-4ee0-a517-0460d63301a6",
            "replica_state": "active"
        },
        {
            "status": "available",
            "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
            "id": "c9f52e33-d780-41d8-89ba-fc06869f465f",
            "replica_state": "in_sync"
        }
    ]
}

Added in version 2.11.

Lists share replicas with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id (Optional)	query	string	The share ID to filter share replicas with.

Response parameters¶

Name	In	Type	Description
share_id	body	string	The UUID of the share from which to create a share replica.
status	body	string	The status of a share replica. List of possible values: `available`, `error`, `creating`, `deleting`, or `error_deleting`.
cast_rules_to_readonly	body	boolean	If the share replica has its `cast_rules_to_readonly` attribute set to True, all existing access rules will be cast to read/only. New in version 2.30
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
share_network_id	body	string	The share network ID where the resource is exported to.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the share replica.
id	body	string	The UUID of the share replica.
replica_state	body	string	The replica state of a share replica. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "share_replicas": [
        {
            "status": "available",
            "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
            "availability_zone": "nova",
            "cast_rules_to_readonly": false,
            "updated_at": "2017-08-15T20:20:50.000000",
            "share_network_id": null,
            "share_server_id": null,
            "host": "ubuntu@generic3#fake_pool_for_DummyDriver",
            "id": "57f5c47a-0216-4ee0-a517-0460d63301a6",
            "replica_state": "active",
            "created_at": "2017-08-15T20:20:45.000000"
        },
        {
            "status": "available",
            "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
            "availability_zone": "nova",
            "cast_rules_to_readonly": true,
            "updated_at": "2017-08-15T20:21:49.000000",
            "share_network_id": null,
            "share_server_id": null,
            "host": "ubuntu@generic2#fake_pool_for_DummyDriver",
            "id": "c9f52e33-d780-41d8-89ba-fc06869f465f",
            "replica_state": "in_sync",
            "created_at": "2017-08-15T20:21:43.000000"
        }
    ]
}

Added in version 2.11.

Show a share replica.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_replica_id	path	string	The UUID of the share replica.

Response parameters¶

Name	In	Type	Description
share_id	body	string	The UUID of the share from which to create a share replica.
status	body	string	The status of a share replica. List of possible values: `available`, `error`, `creating`, `deleting`, or `error_deleting`.
cast_rules_to_readonly	body	boolean	If the share replica has its `cast_rules_to_readonly` attribute set to True, all existing access rules will be cast to read/only. New in version 2.30
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
share_network_id	body	string	The share network ID where the resource is exported to.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the share replica.
id	body	string	The UUID of the share replica.
replica_state	body	string	The replica state of a share replica. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "share_replica": {
         "status": "available",
         "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
         "availability_zone": "nova",
         "cast_rules_to_readonly": false,
         "updated_at": "2017-08-15T20:20:50.000000",
         "share_network_id": null,
         "share_server_id": null,
         "host": "ubuntu@generic3#fake_pool_for_DummyDriver",
         "id": "57f5c47a-0216-4ee0-a517-0460d63301a6",
         "replica_state": "active",
         "created_at": "2017-08-15T20:20:45.000000"
    }
}

Added in version 2.11.

Administrator only. Explicitly updates the status of a share replica.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_replica_id	path	string	The UUID of the share replica.
reset_status	body	object	The `reset_status` object.
status	body	string	The status of a share replica. List of possible values: `available`, `error`, `creating`, `deleting`, or `error_deleting`.

Request example¶

{
    "reset_status": {
        "status": "available"
    }
}

Added in version 2.11.

Administrator only. Explicitly updates the replica state of a share replica.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_replica_id	path	string	The UUID of the share replica.
reset_replica_state	body	object	The `reset_replica_state` object.
replica_state	body	string	The replica state of a share replica. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`.

Request example¶

{
    "reset_replica_state": {
        "replica_state": "out_of_sync"
    }
}

Added in version 2.11.

Deletes a share replica.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Note

The active replica cannot be deleted with this API.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_replica_id	path	string	The UUID of the share replica.

Added in version 2.11.

Administrator only. Force-deletes a share replica in any state.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Note

The active replica cannot be deleted with this API.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_replica_id	path	string	The UUID of the share replica.
force_delete	body	string	To force-delete a share replica, set this value to `null`. The force-delete action, unlike the delete action, ignores the share replica status.

Request example¶

{
    "force_delete": null
}

Share replica export locations (since API v2.47)¶

Set of APIs used to view export locations of share replicas.

GET

/v2/share-replicas/{share_replica_id}/export-locations

List export locations

Added in version 2.47.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_replica_id	path	string	The UUID of the share replica.

Response parameters¶

Name	In	Type	Description
id	body	string	The share export location UUID.
share_instance_id	body	string	The UUID of the share instance that this export location belongs to. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy.yaml.
path	body	string	The export location path that should be used for mount operation.
is_admin_only	body	boolean	Defines purpose of an export location. If set to `true`, then it is expected to be used for service needs and by administrators only. If it is set to `false`, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.
preferred	body	boolean	Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to `false` value.
availability_zone	body	string	The name of the availability zone that the export location belongs to.
replica_state	body	string	The replica state of a share replica. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`.

Response example¶

{
    "export_locations": [
        {
            "path": "10.254.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "is_admin_only": false,
            "id": "b6bd76ce-12a2-42a9-a30a-8a43b503867d",
            "preferred": false,
            "replica_state": "in_sync",
            "availability_zone": "paris"
        },
        {
            "path": "10.0.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "is_admin_only": true,
            "id": "6921e862-88bc-49a5-a2df-efeed9acd583",
            "preferred": false,
            "replica_state": "in_sync",
            "availability_zone": "paris"
        }
    ]
}

GET

/v2/share-replicas/{share_replica_id}/export-locations/{export-location-id}

Show single export location

Added in version 2.47.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_replica_id	path	string	The UUID of the share replica.
export_location_id	path	string	The UUID of the export location.

Response parameters¶

Name	In	Type	Description
id	body	string	The share export location UUID.
share_instance_id	body	string	The UUID of the share instance that this export location belongs to. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy.yaml.
path	body	string	The export location path that should be used for mount operation.
is_admin_only	body	boolean	Defines purpose of an export location. If set to `true`, then it is expected to be used for service needs and by administrators only. If it is set to `false`, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.
preferred	body	boolean	Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to `false` value.
availability_zone	body	string	The name of the availability zone that the export location belongs to.
replica_state	body	string	The replica state of a share replica. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.

Response example¶

{
    "export_location": {
        "created_at": "2016-03-24T14:20:47.000000",
        "updated_at": "2016-03-24T14:20:47.000000",
        "preferred": false,
        "is_admin_only": true,
        "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
        "path": "10.0.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
        "id": "6921e862-88bc-49a5-a2df-efeed9acd583",
        "replica_state": "in_sync",
        "availability_zone": "paris"
    }
}

Share networks¶

A share network resource stores network information to create and manage share servers. Shares created with share networks are exported on these networks with the help of share servers.

You can create, update, view, and delete a share network.

When you create a share network, you may optionally specify an associated neutron network and subnetwork.

For more information about supported plug-ins for share networks, see Manila Network Plugins.

A share network resource has these attributes:

The IP block in Classless Inter-Domain Routing (CIDR) notation from which to allocate the network.
The IP version of the network.
The network type, which is vlan, vxlan, gre, or flat.
If the network uses segmentation, a segmentation identifier. For example, VLAN, VXLAN, and GRE networks use segmentation.

A share network resource can also have a user defined name and description.

Note

Since API version 2.51, a share network is allowed to span multiple subnets and the fields neutron_net_id, neutron_subnet_id, network_type, cidr, ip_version, gateway, segmentation_id and mtu were moved from the share network to the subnet. The share network subnet also contains a an attribute called availability_zone.

Lists all share networks.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
description~ (Optional)	query	string	The description pattern that can be used to filter shares, share snapshots, share networks or share groups. New in version 2.36
name (Optional)	query	string	The user defined name of the resource to filter resources by.
description (Optional)	query	string	The user defined description text that can be used to filter resources.
created_since (Optional)	query	string	Search for the list of resources that were created after the specified date. The date is in ‘yyyy-mm-dd’ format.
created_before (Optional)	query	string	Search for the list of resources that were created prior to the specified date. The date is in ‘yyyy-mm-dd’ format.
security_service_id (Optional)	query	string	The security service ID to filter out share networks.
nova_net_id (Optional)	query	string	The ID of a Nova network to filter out share networks. Available until version 2.26
neutron_net_id (Optional)	query	string	The neutron network id to filter out share networks.
neutron_subnet_id (Optional)	query	string	The neutron network subnet id to filter out share networks.
network_type (Optional)	query	string	The network type to filter out share networks.
segmentation_id (Optional)	query	string	The segmentation id to filter out share networks.
cidr (Optional)	query	string	The CIDR to filter share networks.
ip_version (Optional)	query	string	The IP version to filter share networks.
offset (Optional)	query	integer	The offset to define start point of resource listing.
limit (Optional)	query	integer	The maximum number of resource records to return.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of a share network resource.
name	body	string	The user defined name of the resource.

Response example¶

{
    "share_networks": [
        {
            "id": "32763294-e3d4-456a-998d-60047677c2fb",
            "name": "net_my1"
        },
        {
            "id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "name": "net_my"
        },
        {
            "id": "fa158a3d-6d9f-4187-9ca5-abbb82646eb2",
            "name": null
        }
    ]
}

Lists all share networks with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
description~ (Optional)	query	string	The description pattern that can be used to filter shares, share snapshots, share networks or share groups. New in version 2.36
created_since (Optional)	query	string	Search for the list of resources that were created after the specified date. The date is in ‘yyyy-mm-dd’ format.
created_before (Optional)	query	string	Search for the list of resources that were created prior to the specified date. The date is in ‘yyyy-mm-dd’ format.
nova_net_id (Optional)	query	string	The ID of a Nova network to filter out share networks. Available until version 2.26
neutron_net_id (Optional)	query	string	The neutron network id to filter out share networks.
neutron_subnet_id (Optional)	query	string	The neutron network subnet id to filter out share networks.
network_type (Optional)	query	string	The network type to filter out share networks.
segmentation_id (Optional)	query	string	The segmentation id to filter out share networks.
cidr (Optional)	query	string	The CIDR to filter share networks.
ip_version (Optional)	query	string	The IP version to filter share networks.
offset (Optional)	query	integer	The offset to define start point of resource listing.
limit (Optional)	query	integer	The maximum number of resource records to return.
security_service_id (Optional)	query	string	The security service ID to filter out share networks.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of a share network resource.
project_id	body	string	The ID of the project that owns the resource.
neutron_net_id	body	string	The neutron network ID. Available until version 2.50
neutron_subnet_id	body	string	The neutron subnet ID. Available until version 2.50
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295. Available until version 2.50
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network. New in version 2.18 Available until version 2.50
mtu	body	integer	The MTU value of a share network. New in version 2.20 Available until version 2.50
share_network_subnets	body	array	A list of share network subnets that pertain to the related share network. New in version 2.51
security_service_update_support	body	boolean	Whether the share network supports its security services being updated when it is already being used. New in version 2.63
status	body	string	The status of a share network. Possible values are: `active`, `error` or `network_change`. New in version 2.63

Response example¶

{
    "share_networks": [
        {
            "name": "net_my1",
            "segmentation_id": null,
            "created_at": "2015-09-04T14:57:13.000000",
            "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
            "updated_at": null,
            "id": "32763294-e3d4-456a-998d-60047677c2fb",
            "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
            "ip_version": null,
            "cidr": null,
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "network_type": null,
            "description": "descr",
            "gateway": null,
            "mtu": null
        },
        {
            "name": "net_my",
            "segmentation_id": null,
            "created_at": "2015-09-04T14:54:25.000000",
            "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
            "updated_at": null,
            "id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
            "ip_version": null,
            "cidr": null,
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "network_type": null,
            "description": "desecr",
            "gateway": null,
            "mtu": null
        },
        {
            "name": null,
            "segmentation_id": null,
            "created_at": "2015-09-04T14:51:41.000000",
            "neutron_subnet_id": null,
            "updated_at": null,
            "id": "fa158a3d-6d9f-4187-9ca5-abbb82646eb2",
            "neutron_net_id": null,
            "ip_version": null,
            "cidr": null,
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "network_type": null,
            "description": null,
            "gateway": null,
            "mtu": null
        }
    ]
}

Note

{
    "share_networks": [
        {
            "id": "03987b5f-cb79-4f5f-a590-f6936b91b49e",
            "name": "net_my1",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "created_at": "2019-10-02T12:33:36.000000",
            "updated_at": null,
            "description": null,
            "share_network_subnets": [
                {
                    "id": "022aa495-845e-42a6-9d83-a38f164053c9",
                    "availability_zone": null,
                    "created_at": "2019-10-02T12:33:36.000000",
                    "updated_at": null,
                    "segmentation_id": null,
                    "neutron_net_id": "f00732aa-7721-455d-ba14-ec37619ea13f",
                    "neutron_subnet_id": "eb7adcf8-ce71-43e3-b4c2-cf81da9f89a",
                    "ip_version": null,
                    "cidr": null,
                    "network_type": null,
                    "mtu": null,
                    "gateway": null
                }
            ]
        },
        {
            "id": "1324e7d3-fba8-45e4-bb37-b59c12eb06dc",
            "name": "net_my2",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "created_at": "2019-07-01T17:49:43.000000",
            "updated_at": "2019-07-02T12:17:39.000000",
            "description": null,
            "share_network_subnets": [
                {
                    "id": "8ebe964d-ac48-4e43-93ed-b1768148f8f4",
                    "availability_zone": "manila-zone-0",
                    "created_at": "2019-10-03T02:25:12.000000",
                    "updated_at": null,
                    "segmentation_id": null,
                    "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
                    "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea3050128b5",
                    "ip_version": null,
                    "cidr": null,
                    "network_type": null,
                    "mtu": null,
                    "gateway": null
                },
                {
                    "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
                    "availability_zone": null,
                    "created_at": "2019-07-01T17:49:43.000000",
                    "updated_at": "2019-07-02T12:17:39.000000",
                    "segmentation_id": null,
                    "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
                    "neutron_subnet_id": "2276888a-27c1-47c2-820-ea33050128b5",
                    "ip_version": 4,
                    "cidr": "172.24.5.0/24",
                    "network_type": "flat",
                    "mtu": 1500,
                    "gateway": "172.24.5.1"
                }
            ]
        }
    ]
}

Shows details for a share network.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of a share network resource.
project_id	body	string	The ID of the project that owns the resource.
neutron_net_id	body	string	The neutron network ID. Available until version 2.50
neutron_subnet_id	body	string	The neutron subnet ID. Available until version 2.50
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295. Available until version 2.50
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network. New in version 2.18 Available until version 2.50
mtu	body	integer	The MTU value of a share network. New in version 2.20 Available until version 2.50
share_network_subnets	body	array	A list of share network subnets that pertain to the related share network. New in version 2.51
security_service_update_support	body	boolean	Whether the share network supports its security services being updated when it is already being used. New in version 2.63
status	body	string	The status of a share network. Possible values are: `active`, `error` or `network_change`. New in version 2.63

Response example¶

{
    "share_network": {
        "name": "net_my1",
        "segmentation_id": null,
        "created_at": "2015-09-04T14:56:45.000000",
        "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
        "updated_at": null,
        "id": "7f950b52-6141-4a08-bbb5-bb7ffa3ea5fd",
        "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
        "ip_version": null,
        "cidr": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "network_type": null,
        "description": "descr",
        "gateway": null,
        "mtu": null,
        "security_service_update_support": true,
        "status": "active"
    }
}

Note

{
    "share_network": {
        "id": "1324e7d3-fba8-45e4-bb37-b59c12eb06dc",
        "name": "net_my1",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "created_at": "2019-10-02T17:49:43.000000",
        "description": null,
        "security_service_update_support": true,
        "status": "active",
        "share_network_subnets": [
            {
                "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
                "availability_zone": null,
                "created_at": "2019-10-02T17:49:43.000000",
                "updated_at": "2019-10-03T12:17:39.000000",
                "segmentation_id": null,
                "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
                "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
                "ip_version": 4,
                "cidr": "172.24.5.0/24",
                "network_type": "flat",
                "mtu": 1500,
                "gateway": "172.24.5.1"
            }
        ]
    }
}

Creates a share network.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`413 - Request Entity Too Large`	This operation cannot be completed.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.
`500 - Internal Server Error`	Something went wrong with the service which prevents it from fulfilling the request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
neutron_net_id (Optional)	body	string	The UUID of a neutron network when setting up or updating a share network subnet with neutron. Specify both a neutron network and a neutron subnet that belongs to that neutron network.
neutron_subnet_id (Optional)	body	string	The UUID of the neutron subnet when setting up or updating a share network subnet with neutron. Specify both a neutron network and a neutron subnet that belongs to that neutron network.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
availability_zone (Optional)	body	string	The UUID or name of an availability zone for the share network subnet. New in version 2.51

Request example¶

{
    "share_network": {
        "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
        "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
        "name": "my_network",
        "description": "This is my share network",
        "availability_zone": "manila-zone-0"
    }
}

Note

Since API version 2.51, an availability_zone can be specified with the share network creation request. In case you do not specify an avaiability zone, this field will be set to null and the subnet created will be considered a default subnet by the Shared File Systems service. You can have only one default subnet per share network. If you attempt to create another default subnet in a share network that already has a default one, the Shared File Systems Service will deny the operation.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of a share network resource.
project_id	body	string	The ID of the project that owns the resource.
neutron_net_id	body	string	The neutron network ID. Available until version 2.50
neutron_subnet_id	body	string	The neutron subnet ID. Available until version 2.50
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295. Available until version 2.50
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network. New in version 2.18 Available until version 2.50
mtu	body	integer	The MTU value of a share network. New in version 2.20 Available until version 2.50
share_network_subnets	body	array	A list of share network subnets that pertain to the related share network. New in version 2.51
security_service_update_support	body	boolean	Whether the share network supports its security services being updated when it is already being used. New in version 2.63
status	body	string	The status of a share network. Possible values are: `active`, `error` or `network_change`. New in version 2.63

Response example¶

{
    "share_network": {
        "name": "my_network",
        "segmentation_id": null,
        "created_at": "2015-09-07T14:37:00.583656",
        "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
        "updated_at": null,
        "id": "77eb3421-4549-4789-ac39-0d5185d68c29",
        "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
        "ip_version": null,
        "cidr": null,
        "project_id": "e10a683c20da41248cfd5e1ab3d88c62",
        "network_type": null,
        "description": "This is my share network",
        "gateway": null,
        "mtu": null,
        "security_service_update_support": true,
        "status": "active"
    }
}

Note

Since API version 2.51, share networks are able to span multiple subnets, so when creating a share network, a new subnet will automatically be created by the Shared File Systems service and attached into the share network.

{
    "share_network": {
        "name": "my_network",
        "created_at": "2019-09-07T14:37:00.583656",
        "updated_at": null,
        "id": "77eb3421-4549-4789-ac39-0d5185d68c29",
        "project_id": "e10a683c20da41248cfd5e1ab3d88c62",
        "description": "This is my share network",
        "security_service_update_support": true,
        "status": "active",
        "share_network_subnets": [
            {
                "id": "91cc63b5-6c61-4078-b054-560923709654",
                "availability_zone": "manila-zone-0",
                "created_at": "2019-10-04T20:49:11.000000",
                "updated_at": null,
                "segmentation_id": null,
                "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
                "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
                "ip_version": null,
                "cidr": null,
                "network_type": null,
                "mtu": null,
                "gateway": null
            }
        ]
    }
}

Adds a security service to a share network.

Note

As of API version 2.63, manila allows adding security services to share networks that are being used if supported by the share backends. Before requesting to add a security service to a share network that is in use, make sure to use the check add API.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id	body	string	The ID of the project that owns the resource.
share_network_id	path	string	The UUID of the share network.
security_service_id	body	string	The security service ID.

Request example¶

{
    "add_security_service": {
        "security_service_id": "3c829734-0679-4c17-9637-801da48c0d5f"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of a share network resource.
project_id	body	string	The ID of the project that owns the resource.
neutron_net_id	body	string	The neutron network ID. Available until version 2.50
neutron_subnet_id	body	string	The neutron subnet ID. Available until version 2.50
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295. Available until version 2.50
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network. New in version 2.18 Available until version 2.50
mtu	body	integer	The MTU value of a share network. New in version 2.20 Available until version 2.50
share_network_subnets	body	array	A list of share network subnets that pertain to the related share network. New in version 2.51
security_service_update_support	body	boolean	Whether the share network supports its security services being updated when it is already being used. New in version 2.63
status	body	string	The status of a share network. Possible values are: `active`, `error` or `network_change`. New in version 2.63

Response example¶

{
    "share_network": {
        "name": "net2",
        "segmentation_id": null,
        "created_at": "2015-09-07T12:31:12.000000",
        "neutron_subnet_id": null,
        "updated_at": null,
        "id": "d8ae6799-2567-4a89-aafb-fa4424350d2b",
        "neutron_net_id": null,
        "ip_version": null,
        "cidr": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "network_type": null,
        "description": null,
        "gateway": null,
        "mtu": null,
        "security_service_update_support": true,
        "status": "active"
    }
}

Note

{
    "share_network": {
        "name": "net2",
        "created_at": "2019-11-10T12:31:12.000000",
        "updated_at": null,
        "id": "d8ae6799-2567-4a89-aafb-fa4424350d2b",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "description": null,
        "share_network_subnets": [
            {
                "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
                "availability_zone": null,
                "created_at": "2019-11-10T12:31:12.000000",
                "updated_at": "2019-11-10T12:31:12.000000",
                "segmentation_id": null,
                "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
                "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
                "ip_version": 4,
                "cidr": "172.24.5.0/24",
                "network_type": "flat",
                "mtu": 1500,
                "gateway": "172.24.5.1"
            }
        ]
    }
}

Removes a security service from a share network.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
security_service_id	body	string	The UUID of the security service to remove from the share network. For details, see the security service section.

Request example¶

{
    "remove_security_service": {
        "security_service_id": "3c829734-0679-4c17-9637-801da48c0d5f"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of a share network resource.
project_id	body	string	The ID of the project that owns the resource.
neutron_net_id	body	string	The neutron network ID. Available until version 2.50
neutron_subnet_id	body	string	The neutron subnet ID. Available until version 2.50
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295. Available until version 2.50
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network. New in version 2.18 Available until version 2.50
mtu	body	integer	The MTU value of a share network. New in version 2.20 Available until version 2.50
security_service_update_support	body	boolean	Whether the share network supports its security services being updated when it is already being used. New in version 2.63
status	body	string	The status of a share network. Possible values are: `active`, `error` or `network_change`. New in version 2.63

Response example¶

{
    "share_network": {
        "name": "net2",
        "segmentation_id": null,
        "created_at": "2015-09-07T12:31:12.000000",
        "neutron_subnet_id": null,
        "updated_at": null,
        "id": "d8ae6799-2567-4a89-aafb-fa4424350d2b",
        "neutron_net_id": null,
        "ip_version": null,
        "cidr": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "network_type": null,
        "description": null,
        "gateway": null,
        "mtu": null,
        "security_service_update_support": true,
        "status": "active"
    }
}

Note

{
    "share_network": {
        "name": "net2",
        "created_at": "2019-11-07T12:31:12.000000",
        "updated_at": null,
        "id": "d8ae6799-2567-4a89-aafb-fa4424350d2b",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "description": null,
        "security_service_update_support": true,
        "status": "active",
        "share_network_subnets": [
            {
                "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
                "availability_zone": null,
                "created_at": "2019-11-07T12:31:12.000000",
                "updated_at": "2019-12-12T12:31:12.000000",
                "segmentation_id": null,
                "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
                "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
                "ip_version": 4,
                "cidr": "172.24.5.0/24",
                "network_type": "flat",
                "mtu": 1500,
                "gateway": "172.24.5.1"
            }
        ]
    }
}

Updates a share network.

Note that if the share network is used by any share server, you can update only the name and description attributes.

Note

Since API version 2.51, can only able to update the neutron_net_id and neutron_subnet_id of the default subnet.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
neutron_net_id (Optional)	body	string	The UUID of a neutron network when setting up or updating a share network subnet with neutron. Specify both a neutron network and a neutron subnet that belongs to that neutron network.
neutron_subnet_id (Optional)	body	string	The UUID of the neutron subnet when setting up or updating a share network subnet with neutron. Specify both a neutron network and a neutron subnet that belongs to that neutron network.

Request example¶

{
    "share_network": {
        "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
        "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
        "name": "update my network",
        "description": "i'm adding a description"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of a share network resource.
project_id	body	string	The ID of the project that owns the resource.
neutron_net_id	body	string	The neutron network ID. Available until version 2.50
neutron_subnet_id	body	string	The neutron subnet ID. Available until version 2.50
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295. Available until version 2.50
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network. New in version 2.18 Available until version 2.50
mtu	body	integer	The MTU value of a share network. New in version 2.20 Available until version 2.50
security_service_update_support	body	boolean	Whether the share network supports its security services being updated when it is already being used. New in version 2.63
status	body	string	The status of a share network. Possible values are: `active`, `error` or `network_change`. New in version 2.63

Response example¶

{
    "share_network": {
        "name": "net_my",
        "segmentation_id": null,
        "created_at": "2015-09-04T14:54:25.000000",
        "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
        "updated_at": "2015-09-07T08:02:53.512184",
        "id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
        "ip_version": "4",
        "cidr": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "network_type": null,
        "description": "i'm adding a description",
        "gateway": null,
        "mtu": null,
        "security_service_update_support": true,
        "status": "active"
    }
}

Note

{
    "share_network":{
        "id": "2b33cd3a-3049-4f36-a2fd-f7a211eb9202",
        "name": "update my network",
        "project_id": "79ed3be75dbb4d03afd687b758fcc2c0",
        "created_at": "2019-11-12T17:18:10.000000",
        "updated_at": null,
        "description": "i'm adding a description",
        "security_service_update_support": true,
        "status": "active",
        "share_network_subnets": [
            {
                "id": "687ab361-5c40-406e-945c-6326254782d4",
                "availability_zone": null,
                "created_at": "2019-11-13T17:18:10.000000",
                "updated_at": "2019-11-13T17:18:56.000000",
                "segmentation_id": null,
                "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
                "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
                "ip_version": 4,
                "cidr": "172.24.5.0/24",
                "network_type": "flat",
                "mtu": 1500,
                "gateway": "172.24.5.1"
            }
        ]
    }
}

Deletes a share network.

Preconditions

You cannot delete a share network if it has shares created/exported on it.
You cannot delete a share network if it has share groups created on it.
You cannot delete a share network if it has more than one share network subnet on it (since API version 2.51).

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.

Added in version 2.63.

Replaces a security service in a share network. Both current and the new security service must have the same type and must have the security_service_update_support capability set to True.

Important

Before calling the update share network security service API, make sure to check if the share backends within the share network can hold the operation, through the check update API.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
current_security_service	body	string	The ID of a security service that is currently attached to a share network.
new_security_service	body	string	The ID of a security service that must be attached to a share network after a share network security service update operation.

Request example¶

{
    "update_security_service": {
        "current_service_id": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e",
        "new_service_id": "6cff8d33-f73b-483f-88af-e5429ad9daef"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The share network ID where the resource is exported to.
project_id	body	string	The ID of the project that owns the resource.
neutron_net_id	body	string	The neutron network ID. Available until version 2.50
neutron_subnet_id	body	string	The neutron subnet ID. Available until version 2.50
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295. Available until version 2.50
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider. Available until version 2.50
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network. New in version 2.18 Available until version 2.50
mtu	body	integer	The MTU value of a share network. New in version 2.20 Available until version 2.50
share_network_subnets	body	array	A list of share network subnets that pertain to the related share network. New in version 2.51
security_service_update_support	body	boolean	Whether the share network supports its security services being updated when it is already being used. New in version 2.63
status	body	string	The status of a share network. Possible values are: `active`, `error` or `network_change`. New in version 2.63

Response example¶

{
    "share_network": {
        "id": "1e3f43b2-2290-4fb8-bdc3-fb741c336c2a",
        "name": "my_share_network",
        "project_id": "838f27f65c1d43baa37743c6884958ce",
        "created_at": "2021-03-25T17: 48: 51.925433",
        "updated_at": "2021-03-29T15: 06: 19.464021",
        "description": null,
        "share_network_subnets": [
            {
                "id": "14f7f4f6-b6b6-4b7e-a89c-1040700f3166",
                "availability_zone": null,
                "created_at": "2021-03-25T17: 48: 52.014525",
                "updated_at": "2021-03-29T14: 50: 56.993391",
                "segmentation_id": 1010,
                "neutron_net_id": null,
                "neutron_subnet_id": null,
                "ip_version": 4,
                "cidr": "10.0.0.0/24",
                "network_type": "vlan",
                "mtu": 1500,
                "gateway": "10.0.0.1"
            }
        ],
        "status": "network_change",
        "security_service_update_support": true
    }
}

Added in version 2.63.

Checks if an existing security service can be replaced on a share network that is in use. This operation must be triggered before an actual request to update a share network security service is requested.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
current_service_id	body	string	The ID of a security service that is currently attached to a share network.
new_service_id	body	string	The ID of a security service that must be attached to a share network after a share network security service update operation.
reset_operation	body	boolean	Whether a share network security service check update or add operation for a given share network should ignore previous check results, and check the operation’s compatibility again.

Request example¶

{
    "update_security_service_check": {
        "current_service_id": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e",
        "new_service_id": "6cff8d33-f73b-483f-88af-e5429ad9daef",
        "reset_operation": false
    }
}

Response parameters¶

Name	In	Type	Description
operation	body	string	The name of the check operation that was triggered, being `add_security_service` or `update_security_service`.
current_security_service	body	string	The ID of a security service that is currently attached to a share network.
new_security_service	body	string	The ID of a security service that must be attached to a share network after a share network security service update operation.
compatible	body	boolean	Indicates the result of a check operation. If `True` indicates that the addition/update of security service is possible.
requested_operation	body	object	Information about the requested operation.
hosts_check_result	body	object	(Admin only). Result received from each host in a security service update check operation.

Response example¶

{
    "compatible": true,
    "requested_operation": {
        "operation": "update_security_service",
        "current_security_service": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e",
        "new_security_service": "6cff8d33-f73b-483f-88af-e5429ad9daef"
    },
    "hosts_check_result": {
        "ubuntu@dummy2": true
    }
}

Added in version 2.63.

Checks if a new security service can be added to a share network that’s already in use. This operation must be triggered before an actual request to add a security service to an in use share network.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
security_service_id	body	string	The ID of a security service that is currently attached to a share network.
reset_operation	body	boolean	Whether a share network security service check update or add operation for a given share network should ignore previous check results, and check the operation’s compatibility again.

Request example¶

{
    "add_security_service_check": {
        "security_service_id": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e",
        "reset_operation": false
    }
}

Response parameters¶

Name	In	Type	Description
operation	body	string	The name of the check operation that was triggered, being `add_security_service` or `update_security_service`.
current_security_service	body	string	The ID of a security service that is currently attached to a share network.
new_security_service	body	string	The ID of a security service that must be attached to a share network after a share network security service update operation.
compatible	body	boolean	Indicates the result of a check operation. If `True` indicates that the addition/update of security service is possible.
requested_operation	body	object	Data about the operation that was requested.
hosts_check_result	body	object	(Admin only). Result received from each host in a security service update check operation.

Response example¶

{
    "compatible": true,
    "requested_operation": {
        "operation": "add_security_service",
        "current_security_service": null,
        "new_security_service": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e"
    },
    "hosts_check_result": {
        "ubuntu@dummy2": true
    }
}

POST

/v2/share-networks/{share_network_id}/action

Reset status (since API v2.63)

Added in version 2.63.

Resets a share network status.

Administrator only. Explicitly updates the state of a share network.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request parameters¶

Name

Type

Description

project_id (Optional)

path

string

share_network_id

path

string

The UUID of the share network.

status

body

string

The status of a share network. Possible values are: active, error or network_change.

New in version 2.63

Request example¶

{
    "reset_status": {
        "status": "active"
    }
}

Response parameters¶

There is no body content for the response.

Share network subnets (since API v2.51)¶

A share network subnet stores network information to create and manage share servers.

You can list all subnets that pertain to a share network, also create, delete and view a share network subnet.

When you create a share network, you may optionally specify an associated neutron network, subnetwork and an availability zone. If you do not specify an availability zone, the subnet you are creating will have the availability zone field empty and this subnet will be considered default. The default subnet is recognized by the Shared File Systems service as a subnet that spans all the available storage availability zones.

Note

A share network can have only one default subnet. Likewise, a share network cannot have more than one subnet in a given availability zone.

For more information about supported plug-ins for share network subnets, see Manila Network Plugins.

A share network subnet resource has these attributes:

The IP block in Classless Inter-Domain Routing (CIDR) notation from which to allocate the network.
The IP version of the network.
The network type, which is vlan, vxlan, gre, or flat.
If the network uses segmentation, a segmentation identifier. For example, VLAN, VXLAN, and GRE networks use segmentation.
The availability zone, when null signifies that the share network subnet is available across all storage availability zones known to the Shared File Systems Service.

Added in version 2.51.

Lists all share network subnets in the given share network.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share network subnet.
availability_zone	body	string	The name of the availability zone that the share network subnet belongs to.
share_network_id	body	string	The UUID of the share network that the share network subnet belongs to.
share_network_name	body	string	The name of the share network that the share network subnet belongs to.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295.
neutron_net_id	body	string	The neutron network ID.
neutron_subnet_id	body	string	The neutron subnet ID.
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider.
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider.
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider.
gateway	body	string	The gateway of a share network subnet.
mtu	body	string	The MTU of a share network subnet.

Response example¶

{
    "share_network_subnets": [
    {
        "id": "a7507a16-98bb-476c-ba90-487e4b4775fa",
        "availability_zone": null,
        "share_network_id": "8bc488d8-52f7-46cb-91b1-89dd92cae972",
        "share_network_name": "sn_test",
        "created_at": "2019-10-03T18:30:15.000000",
        "segmentation_id": null,
        "neutron_subnet_id": "dc0a37f0-81b0-4eb5-aad8-deffda5ff4ca",
        "updated_at": null,
        "neutron_net_id": "70bc8f03-525c-4334-a51b-261a024681c5",
        "ip_version": 4,
        "cidr": "10.190.5.0/24",
        "network_type": "flat",
        "mtu": 1500,
        "gateway": "10.190.5.1"
    },
    {
        "id": "8ebe964d-ac48-4e43-93ed-b1768148f8f4",
        "availability_zone": "manila-zone-0",
        "share_network_id": "8bc488d8-52f7-46cb-91b1-89dd92cae972",
        "share_network_name": "sn_test",
        "created_at": "2019-10-02T01:35:10.000000",
        "segmentation_id": null,
        "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
        "updated_at": null,
        "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
        "ip_version": 4,
        "cidr": "172.24.5.0/24",
        "network_type": "flat",
        "mtu": 1500,
        "gateway": "172.24.5.1"
    }
    ]
}

Added in version 2.51.

Shows details of a share network subnet.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
share_network_subnet_id	path	string	The UUID of the share network subnet.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share network subnet.
neutron_net_id	body	string	The neutron network ID.
neutron_subnet_id	body	string	The neutron subnet ID.
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider.
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295.
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider.
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network subnet.
mtu	body	string	The MTU of a share network subnet.
availability_zone	body	string	The name of the availability zone that the share network subnet belongs to.
share_network_id	body	string	The UUID of the share network that the share network subnet belongs to.
share_network_name	body	string	The name of the share network that the share network subnet belongs to.

Response example¶

{
    "share_network_subnet": {
        "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
        "availability_zone": null,
        "share_network_id":"1324e7d3-fba8-45e4-bb37-b59c12eb06dc",
        "share_network_name": "net_my1",
        "created_at": "2019-10-01T17:49:43.000000",
        "segmentation_id": null,
        "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
        "updated_at": "2019-11-02T12:17:39.000000",
        "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
        "ip_version": 4,
        "cidr": "172.24.5.0/24",
        "network_type": "flat",
        "mtu": 1500,
        "gateway": "172.24.5.1"
    }
}

Added in version 2.51.

Creates a share network subnet in the given share network.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.
`500 - Internal Server Error`	Something went wrong with the service which prevents it from fulfilling the request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
neutron_net_id (Optional)	body	string	The UUID of a neutron network when setting up or updating a share network subnet with neutron. Specify both a neutron network and a neutron subnet that belongs to that neutron network.
neutron_subnet_id (Optional)	body	string	The UUID of the neutron subnet when setting up or updating a share network subnet with neutron. Specify both a neutron network and a neutron subnet that belongs to that neutron network.
availability_zone (Optional)	body	string	The UUID or name of an availability zone for resource to be created within.

Request example¶

{
    "share-network-subnet": {
        "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
        "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
        "availability_zone": "manila-zone-0"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share network subnet.
neutron_net_id	body	string	The neutron network ID.
neutron_subnet_id	body	string	The neutron subnet ID.
network_type	body	string	The network type. A valid value is `VLAN`, `VXLAN`, `GRE`, or `flat`. This parameter is automatically set to a value determined by the network provider.
segmentation_id	body	integer	The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295.
cidr	body	string	The IP block from which to allocate the network, in CIDR notation. For example, `172.16.0.0/24` or `2001:DB8::/64`. This parameter is automatically set to a value determined by the network provider.
ip_version	body	integer	The IP version of the network. A valid value is `4` or `6`. This parameter is automatically set to a value determined by the network provider.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
gateway	body	string	The gateway of a share network subnet.
mtu	body	string	The MTU of a share network subnet.
availability_zone	body	string	The name of the availability zone that the share network subnet belongs to.
share_network_id	body	string	The UUID of the share network that the share network subnet belongs to.
share_network_name	body	string	The name of the share network that the share network subnet belongs to.

Response example¶

{
    "share_network_subnet": {
        "id": "8ebe964d-ac48-4e43-93ed-b1768148f8f4",
        "availability_zone": "manila-zone-0",
        "share_network_id": "1324e7d3-fba8-45e4-bb37-b59c12eb06dc",
        "share_network_name": "net_my1",
        "created_at": "2019-10-03T02:25:12.000000",
        "segmentation_id": null,
        "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
        "updated_at": null,
        "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
        "ip_version": null,
        "cidr": null,
        "network_type": null,
        "mtu": null,
        "gateway": null
    }
}

Added in version 2.51.

Deletes a share network subnet.

Preconditions

You cannot delete a share network subnet if it has shares created/exported on it.
You cannot delete a share network subnet if it has share servers with the flag is_auto_deletable set to False.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
share_network_subnet_id	path	string	The UUID of the share network subnet.

Share network subnets metadata (since API v2.78)¶

Shows, sets, updates, and unsets share network subnets metadata.

Shows all share network subnet metadata in the given share network subnet.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
share_network_subnet_id	path	string	The UUID of the share network subnet.

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "project": "my_app",
        "key": "value"
    }
}

Retrieves a specific metadata item from a share network subnet’s metadata by its key. If the specified key does not represent a valid metadata item, the API will respond with HTTP 404.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
share_network_subnet_id	path	string	The UUID of the share network subnet.
key	body	object	The key of a metadata item. For example, if the metadata on an existing resource is as follows: `"project": "my_test", "aim": "testing"`, the keys are “project” and “aim”.

Response parameters¶

Name	In	Type	Description
meta	body	object	A single metadata key and value pair.

Response example¶

{
    "meta": {
        "project": "my_app"
    }
}

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
share_network_subnet_id	path	string	The UUID of the share network subnet.
metadata	body	object	One or more metadata key-value pairs, as a dictionary of strings. For example, `"project": "my_test", "aim": "testing"`. The share server does not respect case-sensitive key names. For example, `"key": "v1"` and `"KEY": "V1"` are equivalent. If you specify both key-value pairs, the server sets and returns only the `"KEY": "V1"` key-value pair.

Request example¶

{
    "metadata": {
        "key1": "value1"
    }
}

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "key1": "value1",
        "new_metadata_key": "new_information",
        "key": "value"
    }
}

Replaces the metadata for a given share network subnet with the metadata (specified as key-value pairs) in the request object. All pre-existing metadata of the share network subnet will be deleted and replaced with the new metadata supplied.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
share_network_subnet_id	path	string	The UUID of the share network subnet.
metadata	body	object	One or more metadata key-value pairs, as a dictionary of strings. For example, `"project": "my_test", "aim": "testing"`. The share server does not respect case-sensitive key names. For example, `"key": "v1"` and `"KEY": "V1"` are equivalent. If you specify both key-value pairs, the server sets and returns only the `"KEY": "V1"` key-value pair.

Request example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "new_metadata_key": "new_information"
    }
}

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "new_metadata_key": "new_information"
    }
}

To delete all existing metadata items on a given share network subnet, the request object needs to specify an empty metadata object:

Request example¶

{
    "metadata": null
}

Response example¶

{
    "metadata": null
}

Deletes a single metadata item on a share network subnet, identified by its key. If the specified key does not represent a valid metadata item, the API will respond with HTTP 404.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_network_id	path	string	The UUID of the share network.
share_network_subnet_id	path	string	The UUID of the share network subnet.
key	body	object	The key of a metadata item. For example, if the metadata on an existing resource is as follows: `"project": "my_test", "aim": "testing"`, the keys are “project” and “aim”.

Security services¶

You can create, update, view, and delete security services. A security service resource represents configuration information for clients for authentication and authorization (AuthN/AuthZ). For example, a share server will be the client for an existing security service such as LDAP, Kerberos, or Microsoft Active Directory.

The Shared File Systems service supports three security service types:

ldap. LDAP.
kerberos. Kerberos.
active_directory. Microsoft Active Directory.

You can configure a security service with these options:

A DNS IP address. Some drivers may allow a comma separated list of multiple addresses, e.g. NetApp ONTAP.
An IP address or host name.
A domain.
An ou, the organizational unit. (available starting with API version 2.44)
A user or group name.
The password for the user, if you specify a user name.
A default AD site, optional (available starting with API version 2.76)

A security service resource can also be given a user defined name and description.

GET

/v2/security-services

List security services

Lists all security services.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

Response parameters¶

Name	In	Type	Description
status	body	string	The security service status.
type	body	string	The security service type. A valid value is `ldap`, `kerberos`, or `active_directory`.
id	body	string	The security service ID.
name	body	string	The user defined name of the resource.

Response example¶

{
    "security_services": [
        {
            "status": "new",
            "type": "kerberos",
            "id": "3c829734-0679-4c17-9637-801da48c0d5f",
            "name": "SecServ1"
        },
        {
            "status": "new",
            "type": "ldap",
            "id": "5a1d3a12-34a7-4087-8983-50e9ed03509a",
            "name": "SecServ2"
        }
    ]
}

GET

/v2/security-services/detail

List security services with details

Lists all security services with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

Response parameters¶

Name	In	Type	Description
status	body	string	The security service status.
id	body	string	The security service ID.
project_id	body	string	The ID of the project that owns the resource.
type	body	string	The security service type. A valid value is `ldap`, `kerberos`, or `active_directory`.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
dns_ip	body	string	The DNS IP address that is used inside the project network.
user	body	string	The security service user or group name that is used by the project.
password	body	string	The user password, if you specify a `user`.
domain	body	string	The security service domain.
ou	body	string	The security service ou. New in version 2.44
server	body	string	The security service host name or IP address.
default_ad_site	body	string	The security service default AD site. New in version 2.76
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "security_services": [
        {
            "status": "new",
            "domain": null,
            "ou": null,
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "name": "SecServ1",
            "created_at": "2015-09-07T12:19:10.000000",
            "description": "Creating my first Security Service",
            "updated_at": null,
            "server": null,
            "default_ad_site": null,
            "dns_ip": "10.0.0.0/24",
            "user": "demo",
            "password": "supersecret",
            "type": "kerberos",
            "id": "3c829734-0679-4c17-9637-801da48c0d5f",
            "share_networks": []
        },
        {
            "status": "new",
            "domain": null,
            "ou": null,
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "name": "SecServ2",
            "created_at": "2015-09-07T12:25:03.000000",
            "description": "Creating my second Security Service",
            "updated_at": null,
            "server": null,
            "default_ad_site": null,
            "dns_ip": "10.0.0.0/24",
            "user": null,
            "password": null,
            "type": "ldap",
            "id": "5a1d3a12-34a7-4087-8983-50e9ed03509a",
            "share_networks": []
        }
    ]
}

GET

/v2/security-services/{security_service_id}

Show security service details

Shows details for a security service.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
security_service_id	path	string	The UUID of the security service.

Response parameters¶

Name	In	Type	Description
status	body	string	The security service status.
id	body	string	The security service ID.
project_id	body	string	The ID of the project that owns the resource.
type	body	string	The security service type. A valid value is `ldap`, `kerberos`, or `active_directory`.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
dns_ip	body	string	The DNS IP address that is used inside the project network.
user	body	string	The security service user or group name that is used by the project.
password	body	string	The user password, if you specify a `user`.
domain	body	string	The security service domain.
ou	body	string	The security service ou. New in version 2.44
server	body	string	The security service host name or IP address.
default_ad_site	body	string	The security service default AD site. New in version 2.76
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "security_service": {
        "status": "new",
        "domain": null,
        "ou": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "name": "SecServ1",
        "created_at": "2015-09-07T12:19:10.000000",
        "updated_at": null,
        "server": null,
        "default_ad_site": null,
        "dns_ip": "10.0.0.0/24",
        "user": "demo",
        "password": "supersecret",
        "type": "kerberos",
        "id": "3c829734-0679-4c17-9637-801da48c0d5f",
        "description": "Creating my first Security Service"
    }
}

POST

/v2/security-services

Create security service

Creates a security service.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
type	body	string	The security service type. A valid value is `ldap`, `kerberos`, or `active_directory`.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
dns_ip (Optional)	body	string	The DNS IP address that is used inside the project network.
user (Optional)	body	string	The security service user or group name that is used by the project.
password (Optional)	body	string	The user password, if you specify a `user`.
domain (Optional)	body	string	The security service domain.
ou (Optional)	body	string	The security service ou. An organizational unit can be added to specify where the share ends up. New in version 2.44
server (Optional)	body	string	The security service host name or IP address.
default_ad_site (Optional)	body	string	The security service default AD site. New in version 2.76

Request example¶

{
    "security_service": {
        "description": "Creating my first Security Service",
        "dns_ip": "10.0.0.0/24",
        "user": "demo",
        "password": "***",
        "type": "kerberos",
        "name": "SecServ1"
    }
}

Response parameters¶

Name	In	Type	Description
status	body	string	The security service status.
id	body	string	The security service ID.
project_id	body	string	The ID of the project that owns the resource.
type	body	string	The security service type. A valid value is `ldap`, `kerberos`, or `active_directory`.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
dns_ip	body	string	The DNS IP address that is used inside the project network.
user	body	string	The security service user or group name that is used by the project.
password	body	string	The user password, if you specify a `user`.
domain	body	string	The security service domain.
ou	body	string	The security service ou. New in version 2.44
server	body	string	The security service host name or IP address.
default_ad_site	body	string	The security service default AD site. New in version 2.76
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "security_service": {
        "status": "new",
        "domain": null,
        "ou": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "name": "SecServ1",
        "created_at": "2015-09-07T12:19:10.695211",
        "updated_at": null,
        "server": null,
        "default_ad_site": null,
        "dns_ip": "10.0.0.0/24",
        "user": "demo",
        "password": "supersecret",
        "type": "kerberos",
        "id": "3c829734-0679-4c17-9637-801da48c0d5f",
        "description": "Creating my first Security Service"
    }
}

PUT

/v2/security-services/{security_service_id}

Update security service

Updates a security service.

If the security service is in active state, you can update only the name and description attributes. A security service in active state is attached to a share network with an associated share server.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
security_service_id	path	string	The UUID of the security service.
type	body	string	The security service type. A valid value is `ldap`, `kerberos`, or `active_directory`.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
dns_ip (Optional)	body	string	The DNS IP address that is used inside the project network.
user (Optional)	body	string	The security service user or group name that is used by the project.
password (Optional)	body	string	The user password, if you specify a `user`.
domain (Optional)	body	string	The security service domain.
ou (Optional)	body	string	The security service ou. An organizational unit can be added to specify where the share ends up. New in version 2.44
server (Optional)	body	string	The security service host name or IP address.
default_ad_site (Optional)	body	string	The security service default AD site. New in version 2.76

Request example¶

{
    "security_service": {
        "domain": "my_domain",
        "ou": "CN=Computers",
        "password": "***",
        "user": "new_user",
        "description": "Adding a description"
    }
}

Response parameters¶

Name	In	Type	Description
status	body	string	The security service status.
id	body	string	The security service ID.
project_id	body	string	The ID of the project that owns the resource.
type	body	string	The security service type. A valid value is `ldap`, `kerberos`, or `active_directory`.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
dns_ip	body	string	The DNS IP address that is used inside the project network.
user	body	string	The security service user or group name that is used by the project.
password	body	string	The user password, if you specify a `user`.
domain	body	string	The security service domain.
ou	body	string	The security service ou. New in version 2.44
server	body	string	The security service host name or IP address.
default_ad_site	body	string	The security service default AD site. New in version 2.76
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "security_service": {
        "status": "new",
        "domain": "my_domain",
        "ou": "CN=Computers",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "name": "SecServ1",
        "created_at": "2015-09-07T12:19:10.000000",
        "updated_at": "2015-09-07T12:47:21.858737",
        "server": null,
        "dns_ip": "10.0.0.0/24",
        "user": "new_user",
        "password": "pass",
        "type": "kerberos",
        "id": "3c829734-0679-4c17-9637-801da48c0d5f",
        "description": "Adding a description"
    }
}

DELETE

/v2/security-services/{security_service_id}

Delete security service

Deletes a security service.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
security_service_id	path	string	The UUID of the security service.

Share servers¶

A share server is created by multi-tenant back-end drivers where shares are hosted. For example, with the generic driver, shares are hosted on Compute VMs.

Administrators can perform read and delete actions for share servers. An administrator can delete an active share server only if it contains no dependent shares. If an administrator deletes the share server, the Shared File Systems service creates a share server in response to a subsequent create share request.

An administrator can use the policy.yaml file to grant permissions for share server actions to other roles.

The status of a share server indicates its current state. After you successfully set up a share server, its status is active. If errors occur during set up such as when server data is not valid, its status is error.

The possible share servers statuses are:

Share server statuses

Status	Description
`active`	Share server was successfully set up.
`error`	The set up or deletion of the share server failed.
`deleting`	The share server has no dependent shares and is being deleted.
`creating`	The share server is being created on the back end with data from the database.

Lists all share servers.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share server.
project_id	body	string	The ID of the project that owns the resource.
status	body	string	The share server status, which is `active`, `error`, `creating`, or `deleting`.
share_network_id	body	string	The UUID of a share network that is associated with the share server.
share_network_name	body	string	The name of a share network that is associated with the share server.
host	body	string	The share server host name or IP address.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
share_network_subnet_id	body	string	The UUID of the share network subnet that the share server pertains to. New in version 2.51
security_service_update_support	body	boolean	Whether the share server supports its security services being updated after its creation. New in version 2.63

Response example¶

{
    "share_servers": [
        {
            "status": "active",
            "updated_at": "2015-09-07T08:52:15.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "host": "manila2@generic1",
            "share_network_name": "net_my",
            "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "security_service_update_support": true
        }
    ]
}

Show a share server’s details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_server_id	body	string	The UUID of the share server.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share server.
project_id	body	string	The ID of the project that owns the resource.
status	body	string	The share server status, which is `active`, `error`, `creating`, or `deleting`.
backend_details	body	object	The back-end details for a server. Each back end can store any key-value information that it requires. For example, the generic back-end driver might store the router ID.
share_network_id	body	string	The UUID of a share network that is associated with the share server.
share_network_name	body	string	The name of a share network that is associated with the share server.
host	body	string	The share server host name or IP address.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
identifier	body	string	The identifier of the share server in the back-end storage system. New in version 2.49
is_auto_deletable	body	boolean	Defines if a share server can be deleted automatically by the service. Share server deletion can be automated with configuration. However, Share servers that have ever had a share removed from service management cannot be automatically deleted by the service. New in version 2.49
share_network_subnet_id	body	string	The UUID of the share network subnet that the share server pertains to. New in version 2.51
security_service_update_support	body	boolean	Whether a share network or server supports security service updates or not. New in version 2.63

Response example¶

{
    "share_server": {
        "status": "active",
        "backend_details": {
            "username": "manila",
            "router_id": "4b62ce91-56c5-45c1-b0ef-8cbbe5dd34f4",
            "pk_path": "/opt/stack/.ssh/id_rsa",
            "subnet_id": "16e99ad6-5191-461c-9f34-ac84a39c3adb",
            "ip": "10.254.0.3",
            "instance_id": "75f2f282-af65-49ba-a7b1-525705b1bf1a",
            "public_address": "10.254.0.3",
            "service_port_id": "8ff21760-961e-4b83-a032-03fd559bb1d3"
        },
        "created_at": "2015-09-07T08:37:19.000000",
        "updated_at": "2015-09-07T08:52:15.000000",
        "share_network_name": "net_my",
        "host": "manila2@generic1",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
        "security_service_update_support": true
    }
}

Shows back end details of a share server.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_server_id	body	string	The UUID of the share server.

Response parameters¶

Response parameters can differ based on the back end used. Each back end can store any key-value information that it requires. For example, the generic back end driver might store the router ID.

Response example¶

{
    "details": {
        "username": "manila",
        "router_id": "4b62ce91-56c5-45c1-b0ef-8cbbe5dd34f4",
        "pk_path": "/opt/stack/.ssh/id_rsa",
        "subnet_id": "16e99ad6-5191-461c-9f34-ac84a39c3adb",
        "ip": "10.254.0.3",
        "instance_id": "75f2f282-af65-49ba-a7b1-525705b1bf1a",
        "public_address": "10.254.0.3",
        "service_port_id": "8ff21760-961e-4b83-a032-03fd559bb1d3"
    }
}

Deletes a share server.

An administrator can delete an active share server only if it contains no dependent shares.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_server_id	body	string	The UUID of the share server.

Added in version 2.49.

Manages a share server

An administrator can bring a pre-existing share server if the back end driver is operating in driver_handles_share_servers=True mode.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
host	body	string	The host of the destination back end, in this format: `host@backend`. `host`: The host name for the destination back end. `backend`: The name of the destination back end.
identifier	body	string	The identifier of the share server in the back-end storage system.
share_network	body	string	The UUID of the share network that the share server will pertain to.
driver_options (Optional)	body	object	A set of one or more key and value pairs, as a dictionary of strings, that describe driver options. Details for driver options should be taken from appropriate share driver documentation.
share_network_subnet_id (Optional)	body	string	The UUID of the share network subnet that the share server will pertain to. If not specified, the share network’s default subnet UUID will be used. New in version 2.51

Request example¶

{
    "share_server": {
        "host": "myhost@mybackend",
        "share_network_id": "78cef6eb-648a-4bbd-9ae1-d2eaaf594cc0",
        "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3",
        "identifier": "4ef3507e-0513-4140-beda-f619ab30d424",
        "driver_options": {
            "opt1": "opt1_value"
        }
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share server.
project_id	body	string	The ID of the project that owns the resource.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
status	body	string	The share server status, which can be `active`, `error`, `creating`, `deleting`, `manage_starting`, `manage_error`, `unmanage_starting`, `unmanage_error` or `error_deleting`.
host	body	string	The host of the destination back end, in this format: `host@backend`. `host`: The host name for the destination back end. `backend`: The name of the destination back end.
share_network_name	body	string	The name of a share network that is associated with the share server.
share_network_id	body	string	The UUID of a share network that is associated with the share server.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
backend_details	body	object	The back-end details for a server. Each back end can store any key-value information that it requires. For example, the generic back-end driver might store the router ID.
is_auto_deletable	body	boolean	Defines if a share server can be deleted automatically by the service. Share server deletion can be automated with configuration. However, Share servers that have ever had a share removed from service management cannot be automatically deleted by the service.
identifier	body	string	The identifier of the share server in the back-end storage system.
share_network_subnet_id	body	string	The UUID of the share network subnet that the share server pertain to. New in version 2.51
security_service_update_support	body	boolean	Whether a share network or server supports security service updates or not. New in version 2.63

Response examples¶

{
    "share_server": {
        "id": "dd218d97-6b16-45b7-9b23-19681ccdec3a",
        "project_id": "5b23075b4b504261a5987b18588f86cf",
        "updated_at": null,
        "status": "manage_starting",
        "host": "myhost@mybackend",
        "share_network_name": "share-net-name",
        "share_network_id": "78cef6eb-648a-4bbd-9ae1-d2eaaf594cc0",
        "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3",
        "created_at": "2019-03-06T11:59:41.000000",
        "backend_details": {},
        "is_auto_deletable": false,
        "identifier": "4ef3507e-0513-4140-beda-f619ab30d424",
        "security_service_update_support": true
    }
}

Added in version 2.49.

Unmanages a share server

An administrator can remove a share server from the Shared File System service’s management if there are no associated shares that the service is aware of. The share server will not be torn down in the back end.

Preconditions

Share server status must be either error, manage_error, active or unmanage_error.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`404 - Not Found`	The requested resource could not be found.

Request parameters¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_server_id	body	string	The UUID of the share server.
force (Optional)	body	boolean	Indicates whether to permit or deny the force- update of a quota that is already used and the requested value exceeds the configured quota. Set to `True` to permit the force-update of the quota. Set to `False` to deny the force- update of the quota.
unmanage	body	object	To unmanage a share server, either set this value to `null` or {}. Optionally, the `force` attribute can be included in this object.

Request example¶

{
  "unmanage": {
    "force": "false"
  }
}

Response parameters¶

There is no body content for the response.

POST

/v2/share-servers/{share_server_id}/action

Reset status (since API v2.49)

Added in version 2.49.

Resets a share server status

Administrator only. Explicitly updates the state of a share server.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`404 - Not Found`	The requested resource could not be found.

Request parameters¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_server_id	body	string	The UUID of the share server.
status	body	string	The share server status, which can be `active`, `error`, `creating`, `deleting`, `manage_starting`, `manage_error`, `unmanage_starting`, `unmanage_error` or `error_deleting`.

Request example¶

{
    "reset_status": {
        "status": "active"
    }
}

Response parameters¶

There is no body content for the response.

Share instances (since API v2.3)¶

A share instance is an internal representation for a share. A share that is replicated or is in the process of being migrated is physically stored in multiple locations. Each of these individual locations is called an “instance” within the Shared File Systems service. End users need not be concerned with this internal representation. As an administrator, you can list, show information for, explicitly set the state of, and force-delete share instances. Use the policy.yaml file to grant permissions for these actions to other roles.

GET

/v2/share_instances

List share instances

Added in version 2.3.

Lists all share instances.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name

Type

Description

project_id (Optional)

path

string

export_location_id (Optional)

query

string

The export location UUID that can be used to filter shares or share instances.

New in version 2.35

export_location_path (Optional)

query

string

The export location path that can be used to filter shares or share instances.

New in version 2.35

Response parameters¶

Name	In	Type	Description
status	body	string	The share or share instance status. Possible values are listed in the section above.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
share_id	body	string	The UUID of the share to which the share instance belongs to.
progress	body	string	The progress of the share creation. New in version 2.54
availability_zone	body	string	The name of the availability zone the share exists within.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
replica_state	body	string	The share replica state. Has set value only when replication is used. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`. New in version 2.11
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
cast_rules_to_readonly	body	boolean	If the share instance has its `cast_rules_to_readonly` attribute set to True, all existing access rules will be cast to read/only. New in version 2.30
share_network_id	body	string	The share network ID where the resource is exported to.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
share_type_id	path	string	The UUID of the share type.
id	body	string	The share instance ID.

Response example¶

{
    "share_instances": [
        {
            "status": "error",
            "progress": null,
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T08:41:20.000000",
            "updated_at": "2015-09-07T08:43:10.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "access_rules_status": "active",
            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
            "id": "081f7030-c54f-42f5-98ee-93a37393e0f2"
        },
        {
            "status": "available",
            "progress": "100%",
            "share_id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T08:51:34.000000",
            "updated_at": "2015-09-10T02:01:22.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "access_rules_status": "active",
            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
            "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
        },
        {
            "status": "creating_from_snapshot",
            "progress": "30%",
            "share_id": "9bb15af4-27e5-4174-ae15-dc549d4a3b51",
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T09:01:15.000000",
            "updated_at": "2015-09-07T09:02:30.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "access_rules_status": "active",
            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
            "id": "48155648-2fd3-480d-b02b-44b995c24bab"
        }
    ]
}

Added in version 2.3.

Shows details for a share instance.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_instance_id	path	string	The UUID of the share instance.

Response parameters¶

Name	In	Type	Description
status	body	string	The share or share instance status. Possible values are listed in the section above.
access_rules_status	body	string	The share instance access rules status. A valid value is `active`, `error`, or `syncing`. In versions prior to 2.28, `syncing` was represented with status `out_of_sync`. New in version 2.10
share_id	body	string	The UUID of the share to which the share instance belongs to.
progress	body	string	The progress of the share creation. New in version 2.54
availability_zone	body	string	The name of the availability zone the share exists within.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
replica_state	body	string	The share replica state. Has set value only when replication is used. List of possible values: `active`, `in_sync`, `out_of_sync`, and `error`. New in version 2.11
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
cast_rules_to_readonly	body	boolean	If the share instance has its `cast_rules_to_readonly` attribute set to True, all existing access rules will be cast to read/only. New in version 2.30
share_network_id	body	string	The share network ID where the resource is exported to.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
id	body	string	The share instance ID.

Response example¶

{
    "share_instance": {
        "status": "available",
        "progress": "100%",
        "share_id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
        "availability_zone": "nova",
        "replica_state": null,
        "created_at": "2015-09-07T08:51:34.000000",
        "updated_at": "2015-09-07T08:52:20.000000",
        "cast_rules_to_readonly": false,
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
        "host": "manila2@generic1#GENERIC1",
        "access_rules_status": "active",
        "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
    }
}

Added in version 2.3.

Administrator only. Explicitly updates the state of a share instance.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_instance_id	path	string	The UUID of the share instance.
status	body	string	The share or share instance status to be set. Possible values are listed in the section above.

Request example¶

{
    "reset_status": {
        "status": "available"
    }
}

Added in version 2.3.

Administrator only. Force-deletes a share instance.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_instance_id	path	string	The UUID of the share instance.
force_delete	body	string	To force-delete a share instance, set this value to `null`. The force-delete action, unlike the delete action, ignores the share instance status.

Request example¶

{
    "force_delete": null
}

Share instance export locations (since API v2.9)¶

Set of APIs used to view export locations of share instances.

By default, these APIs are admin-only. Use the policy.yaml file to grant permissions for these actions to other roles.

Lists all export locations for a share instance.

Show details of an export location belonging to a share instance.

GET

/v2/share_instances/{share_instance_id}/export_locations

List export locations

Added in version 2.9.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_instance_id	path	string	The UUID of the share instance.

Response parameters¶

Name	In	Type	Description
id	body	string	The share export location UUID.
share_instance_id	body	string	The UUID of the share instance that this export location belongs to. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy.yaml.
path	body	string	The export location path that should be used for mount operation.
is_admin_only	body	boolean	Defines purpose of an export location. If set to `true`, then it is expected to be used for service needs and by administrators only. If it is set to `false`, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.
preferred	body	boolean	Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to `false` value. New in version 2.14

Response example¶

{
    "export_locations": [
        {
            "path": "10.254.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "is_admin_only": false,
            "id": "b6bd76ce-12a2-42a9-a30a-8a43b503867d",
            "preferred": false
        },
        {
            "path": "10.0.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
            "is_admin_only": true,
            "id": "6921e862-88bc-49a5-a2df-efeed9acd583",
            "preferred": false
        }
    ]
}

GET

/v2/share_instances/{share_instance_id}/export_locations/{export_location_id}

Show single export location

Added in version 2.9.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_instance_id	path	string	The UUID of the share instance.
export_location_id	path	string	The UUID of the export location.

Response parameters¶

Name	In	Type	Description
id	body	string	The share export location UUID.
share_instance_id	body	string	The UUID of the share instance that this export location belongs to. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy.yaml.
path	body	string	The export location path that should be used for mount operation.
is_admin_only	body	boolean	Defines purpose of an export location. If set to `true`, then it is expected to be used for service needs and by administrators only. If it is set to `false`, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.
preferred	body	boolean	Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to `false` value. New in version 2.14
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.

Response example¶

{
    "export_location": {
        "created_at": "2016-03-24T14:20:47.000000",
        "updated_at": "2016-03-24T14:20:47.000000",
        "preferred": false,
        "is_admin_only": true,
        "share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",
        "path": "10.0.0.3:/shares/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d",
        "id": "6921e862-88bc-49a5-a2df-efeed9acd583"
    }
}

Share types¶

A share type provides hints to the scheduler service to aid placement of new workloads. It contains extra specifications that can either match back end storage capabilities or provide instructions to the Shared File Systems service with regard to the workload being requested. A share type behaves in the same way as a Block Storage volume type behaves. See the administration reference on share types for more information.

You can create publicly visible share type that are visible to all projects and users within the cloud, or make them private and control which projects can access them.

When you issue a create a share type request, you can submit a request body with either a share_type or volume_type object.

Important

The use of the volume_type object is deprecated but supported. It is recommended that you use the share_type object when you create a share type.

No matter which object type you include in the request, the API creates both a volume_type object and a share_type object. Both objects have the same ID. When you issue a list share types request, the response shows both share_type and volume_type objects.

You can set share types as either public or private. By default a share type is created as publicly accessible. Set share_type_access:is_public (os-share-type-access:is_public for API versions 1.0-2.6) to False to make the share type private.

You can manage the access to the private share types for the different projects. You can add access, remove access, and get information about access for a private share type.

Administrators can create share types with these extra specifications that are used to filter back ends:

driver_handles_share_servers. Required. Defines the driver mode for share server, or storage, life cycle management. The Shared File Systems service creates a share server for the export of shares.

Set to True when the share driver manages or handles the share server life cycle.

Set to False when an administrator rather than a share driver manages the share server life cycle.
snapshot_support. Filters back ends by whether they do or do not support share snapshots.

Set to True to find back ends that support share snapshots.

Set to False to find back ends that do not support share snapshots.

Administrators can also set additional extra specifications for a share type for the following purposes:

Filter back ends. Specify these unqualified extra specifications in this format: extra_spec=value. For example, netapp_raid_type=raid4.
Set data for the driver. Except for the special capabilities prefix, you specify these qualified extra specifications with its prefix followed by a colon: vendor:extra_spec=value. For example, netapp:thin_provisioned=true.

The scheduler uses the special capabilities prefix for filtering. The scheduler can only create a share on a back end that reports capabilities that match the un-scoped extra-spec keys for the share type. For details, see Capabilities and Extra-Specs.

Each driver implementation determines which extra specification keys it uses. For details, see the documentation for the driver.

An administrator can use the policy.yaml file to grant permissions for share type creation with extra specifications to other roles.

Lists all share types.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Request¶

Name

Type

Description

project_id (Optional)

path

string

is_public (Optional)

query

boolean

A boolean query parameter that, when set to true, allows retrieving public resources that belong to all projects.

extra_specs (Optional)

query

string

The extra specifications as a set of one or more key-value pairs. In each pair, the key is the name of the extra specification and the value is the share type that was used to filter search share type list. The query must be a “percent-encoded” string, for example, the following query parameters: {‘extra-specs’: {‘snapshot_support’: ‘true’, ‘availability_zones’: ‘az1’}} is encoded as ‘extra_specs=%7B%27snapshot_support%27%3A+%27true%27%2C+%27availability_zones%27%3A+%27az1%27%7D’

New in version 2.43

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share type.
name	body	string	Name of the share type.
required_extra_specs	body	object	The required extra specifications for the share type: `driver_handles_share_servers`. `snapshot_support` was treated as a required extra-specification until api version 2.24.
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. Some examples include: `driver_handles_share_servers`, `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`
share_type_access:is_public	body	boolean	Indicates whether a share type is accessible by all projects (tenants) in the cloud.
description	body	string	The description of the share type. New in version 2.41
is_default	body	boolean	Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default. New in version 2.46

Response example¶

{
    "volume_types": [
        {
            "required_extra_specs": {
                "driver_handles_share_servers": "True"
            },
            "share_type_access:is_public": true,
            "extra_specs": {
                "driver_handles_share_servers": "True"
            },
            "id": "420e6a31-3f3d-4ed7-9d11-59450372182a",
            "name": "default",
            "is_default": true,
            "description": "share type description"
        },
        {
            "required_extra_specs": {
                "driver_handles_share_servers": "True"
            },
            "share_type_access:is_public": true,
            "extra_specs": {
                "replication_type": "readable",
                "driver_handles_share_servers": "True",
                "mount_snapshot_support": "False",
                "revert_to_snapshot_support": "False",
                "create_share_from_snapshot_support": "True",
                "snapshot_support": "True"
            },
            "id": "7fa1342b-de9d-4d89-bdc8-af67795c0e52",
            "name": "testing",
            "is_default": false,
            "description": "share type description"
        }
    ],
    "share_types": [
        {
            "required_extra_specs": {
                "driver_handles_share_servers": "True"
            },
            "share_type_access:is_public": true,
            "extra_specs": {
                "driver_handles_share_servers": "True"
            },
            "id": "420e6a31-3f3d-4ed7-9d11-59450372182a",
            "name": "default",
            "is_default": true,
            "description": "share type description"
        },
        {
            "required_extra_specs": {
                "driver_handles_share_servers": "True"
            },
            "share_type_access:is_public": true,
            "extra_specs": {
                "replication_type": "readable",
                "driver_handles_share_servers": "True",
                "mount_snapshot_support": "False",
                "revert_to_snapshot_support": "False",
                "create_share_from_snapshot_support": "True",
                "snapshot_support": "True"
            },
            "id": "7fa1342b-de9d-4d89-bdc8-af67795c0e52",
            "name": "testing",
            "is_default": false,
            "description": "share type description"
        }
    ]
}

Lists default share types.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share type.
required_extra_specs	body	object	The required extra specifications for the share type: `driver_handles_share_servers`. `snapshot_support` was treated as a required extra-specification until api version 2.24.
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. Some examples include: `driver_handles_share_servers`, `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`
share_type_access:is_public	body	boolean	Indicates whether a share type is accessible by all projects (tenants) in the cloud.
name	body	string	Name of the share type.
description	body	string	The description of the share type. New in version 2.41
is_default	body	boolean	Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default. New in version 2.46

Response example¶

{
    "share_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "id": "420e6a31-3f3d-4ed7-9d11-59450372182a",
        "name": "default",
        "is_default": true,
        "description": "share type description"
    },
    "volume_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "id": "420e6a31-3f3d-4ed7-9d11-59450372182a",
        "name": "default",
        "is_default": true,
        "description": "share type description"
    }
}

Shows details for a specified share type.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.

Response Parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share type.
required_extra_specs	body	object	The required extra specifications for the share type: `driver_handles_share_servers`. `snapshot_support` was treated as a required extra-specification until api version 2.24.
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. Some examples include: `driver_handles_share_servers`, `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`
share_type_access:is_public	body	boolean	Indicates whether a share type is accessible by all projects (tenants) in the cloud.
name	body	string	Name of the share type.
description	body	string	The description of the share type. New in version 2.41
is_default	body	boolean	Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default. New in version 2.46

Response Example¶

{
    "share_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "id": "2780fc88-526b-464a-a72c-ecb83f0e3929",
        "name": "default-share-type",
        "is_default": true,
        "description": "manila share type"
    },
    "volume_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "id": "2780fc88-526b-464a-a72c-ecb83f0e3929",
        "name": "default-share-type",
        "is_default": true,
        "description": "manila share type"
    }
}

GET

/v2/types/{share_type_id}/extra_specs

List extra specs

Lists the extra specifications for a share type.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.

Response parameters¶

Name	In	Type	Description
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. Some examples include: `driver_handles_share_servers`, `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`

Response example¶

{
    "extra_specs": {
        "replication_type": "readable",
        "driver_handles_share_servers": "True",
        "create_share_from_snapshot_support": "True",
        "revert_to_snapshot_support": "False",
        "mount_snapshot_support": "False",
        "snapshot_support": "True"
    }
}

Creates a share type.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. When creating a new share type, required extra-specifications must be provided. `driver_handles_share_servers` is a required extra-specification, and `snapshot_support` was considered a required extra-specification until API version 2.24. When updating extra-specs of a share type, there’s no need to provide required extra specifications unless they need to be updated. Some examples of extra-specifications include: `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`
os-share-type-access:is_public (Optional)	body	boolean	Indicates whether a share type is publicly accessible. Default is `true`, or publicly accessible. Available until version 2.6
name	body	string	Name of the share type.
description (Optional)	body	string	The description of the share type. The value of this field is limited to 255 characters. New in version 2.41

Request example¶

{
    "share_type": {
        "extra_specs": {
            "replication_type": "readable",
            "driver_handles_share_servers": true,
            "mount_snapshot_support": false,
            "revert_to_snapshot_support": false,
            "create_share_from_snapshot_support": true,
            "snapshot_support": true
        },
        "share_type_access:is_public": true,
        "name": "testing",
        "description": "share type description"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share type.
required_extra_specs	body	object	The required extra specifications for the share type: `driver_handles_share_servers`. `snapshot_support` was treated as a required extra-specification until api version 2.24.
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. Some examples include: `driver_handles_share_servers`, `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`
os-share-type-access:is_public (Optional)	body	boolean	Indicates whether a share type is publicly accessible. Default is `true`, or publicly accessible. Available until version 2.6
share_type_access:is_public (Optional)	body	boolean	Indicates whether a share type is publicly accessible. Default is `true`, or publicly accessible. New in version 2.7
name	body	string	Name of the share type.
description	body	string	The description of the share type. New in version 2.41
is_default	body	boolean	Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default. New in version 2.46

Response example¶

{
    "share_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": true
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "replication_type": "readable",
            "driver_handles_share_servers": "True",
            "mount_snapshot_support": "False",
            "revert_to_snapshot_support": "False",
            "create_share_from_snapshot_support": "True",
            "snapshot_support": "True"
        },
        "id": "7fa1342b-de9d-4d89-bdc8-af67795c0e52",
        "name": "testing",
        "is_default": false,
        "description": "share type description"
    },
    "volume_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": true
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "replication_type": "readable",
            "driver_handles_share_servers": "True",
            "mount_snapshot_support": "False",
            "revert_to_snapshot_support": "False",
            "create_share_from_snapshot_support": "True",
            "snapshot_support": "True"
        },
        "id": "7fa1342b-de9d-4d89-bdc8-af67795c0e52",
        "name": "testing",
        "is_default": false,
        "description": "share type description"
    }
}

Shows access details for a share type.

You can view access details for private share types only.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.

Response parameters¶

Name	In	Type	Description
project_id	body	string	The ID of the project that has been granted access to the type resource.
share_type_id	body	string	The UUID of the share type.

Response example¶

{
    "share_type_access": [
        {
            "share_type_id": "1732f284-401d-41d9-a494-425451e8b4b8",
            "project_id": "818a3f48dcd644909b3fa2e45a399a27"
        },
        {
            "share_type_id": "1732f284-401d-41d9-a494-425451e8b4b8",
            "project_id": "e1284adea3ee4d2482af5ed214f3ad90"
        }
    ]
}

Sets an extra specification for the share type.

Each driver implementation determines which extra specification keys it uses. For details, see Capabilities and Extra-Specs and documentation for your driver.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. When creating a new share type, required extra-specifications must be provided. `driver_handles_share_servers` is a required extra-specification, and `snapshot_support` was considered a required extra-specification until API version 2.24. When updating extra-specs of a share type, there’s no need to provide required extra specifications unless they need to be updated. Some examples of extra-specifications include: `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`

Request example¶

{
    "extra_specs": {
        "my_key": "my_value"
    }
}

Response parameters¶

Name	In	Type	Description
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. Some examples include: `driver_handles_share_servers`, `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`

Response example¶

{
    "extra_specs": {
        "my_key": "my_value"
    }
}

DELETE

/v2/types/{share_type_id}/extra_specs/{extra-spec-key}

Unset an extra spec

Unsets an extra specification for the share type.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.
extra-spec-key	path	string	The extra specification key

Adds share type access for a project.

You can add access to private share types only.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.
addProjectAccess	body	object	An object representing the project resource that access should be granted to.
project	body	string	The ID of the project that needs to have access to the type resource.

Request example¶

{
    "addProjectAccess": {
        "project": "e1284adea3ee4d2482af5ed214f3ad90"
    }
}

Removes share type access from a project.

You can remove access from private share types only.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.
removeProjectAccess	body	object	An object representing the project resource that access should be revoked from.
project	body	string	The ID of the project whose access to the type resource must be revoked.

Request example¶

{
    "removeProjectAccess": {
        "project": "818a3f48dcd644909b3fa2e45a399a27"
    }
}

Deletes a share type.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.

Added in version 2.50.

Update a share type. Share type extra-specs cannot be updated with this API. Please use the respective APIs to set extra specs or unset extra specs.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_type_id	path	string	The UUID of the share type.
name (Optional)	body	string	Name of the share type. The value of this field is limited to 255 characters.
share_type_access:is_public (Optional)	body	boolean	Indicates whether the share type should be accessible by all projects (tenants) in the cloud. If not specified, the visibility of the share type is not altered.
description (Optional)	body	string	New description for the share type.

Request example¶

{
  "share_type":
  {
    "share_type_access:is_public": true,
    "name": "testing",
    "description": "share type description"
  }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share type.
required_extra_specs	body	object	The required extra specifications for the share type: `driver_handles_share_servers`. `snapshot_support` was treated as a required extra-specification until api version 2.24.
extra_specs	body	object	Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. Some examples include: `driver_handles_share_servers`, `replication_type`, `snapshot_support`, `mount_snapshot_support`, `revert_to_snapshot_support`, `create_share_from_snapshot_support`
share_type_access:is_public	body	boolean	Indicates whether a share type is accessible by all projects (tenants) in the cloud.
name	body	string	Name of the share type.
description	body	string	The description of the share type.
is_default	body	boolean	Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

Response example¶

{
    "share_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": true
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "replication_type": "readable",
            "driver_handles_share_servers": "True",
            "mount_snapshot_support": "False",
            "revert_to_snapshot_support": "False",
            "create_share_from_snapshot_support": "True",
            "snapshot_support": "True"
        },
        "id": "7fa1342b-de9d-4d89-bdc8-af67795c0e52",
        "name": "testing",
        "is_default": false,
        "description": "share type description"
    },
    "volume_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": true
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "replication_type": "readable",
            "driver_handles_share_servers": "True",
            "mount_snapshot_support": "False",
            "revert_to_snapshot_support": "False",
            "create_share_from_snapshot_support": "True",
            "snapshot_support": "True"
        },
        "id": "7fa1342b-de9d-4d89-bdc8-af67795c0e52",
        "name": "testing",
        "is_default": false,
        "description": "share type description"
    }
}

Scheduler Stats - Storage Pools¶

An administrator can list all back-end storage pools that are known to the scheduler service.

GET

/v2/scheduler-stats/pools?pool={pool_name}&host={host_name}&backend={backend_name}&capabilities={capabilities}&share_type={share_type}

List back-end storage pools

Lists all back-end storage pools. If search options are provided, the pool list that is returned is filtered with these options.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
pool_name (Optional)	query	string	The pool name for the back end.
host_name (Optional)	query	string	The host name for the back end.
backend_name (Optional)	query	string	The name of the back end.
capabilities (Optional)	query	string	The capabilities for the storage back end.
share_type (Optional)	query	string	The share type name or UUID. Allows filtering back end pools based on the extra-specs in the share type. New in version 2.23

Response parameters¶

Name	In	Type	Description
backend	body	string	The name of the back end.
host	body	string	The host name for the back end.
pool	body	string	The pool name for the back end.
name	body	string	The name of the back end in this format: `host@backend#POOL`: `host`. The host name for the back end. `backend`. The name of the back end. `POOL`. The pool name for the back end.

Response example¶

{
  "pools": [
    {
      "name": "opencloud@alpha#ALPHA_pool",
      "host": "opencloud",
      "backend": "alpha",
      "pool": "ALPHA_pool"
    },
    {
      "name": "opencloud@beta#BETA_pool",
      "host": "opencloud",
      "backend": "beta",
      "pool": "BETA_pool"
    },
    {
      "name": "opencloud@gamma#GAMMA_pool",
      "host": "opencloud",
      "backend": "gamma",
      "pool": "GAMMA_pool"
    },
    {
      "name": "opencloud@delta#DELTA_pool",
      "host": "opencloud",
      "backend": "delta",
      "pool": "DELTA_pool"
    }
  ]
}

GET

/v2/scheduler-stats/pools/detail?pool={pool_name}&host={host_name}&backend={backend_name}&capabilities={capabilities}&share_type={share_type}

List back-end storage pools with details

Lists all back-end storage pools with details. If search options are provided, the pool list that is returned is filtered with these options.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
pool_name (Optional)	query	string	The pool name for the back end.
host_name (Optional)	query	string	The host name for the back end.
backend_name (Optional)	query	string	The name of the back end.
capabilities (Optional)	query	string	The capabilities for the storage back end.
share_type (Optional)	query	string	The share type name or UUID. Allows filtering back end pools based on the extra-specs in the share type. New in version 2.23

Response parameters¶

Name	In	Type	Description
pools	body	string	The pools for the back end. This value is either `null` or a string value that indicates the capabilities for each pool. For example, `pool_name`, `total_capacity_gb`, `qos`, and so on.
name	body	string	The name of the back end in this format: `host@backend#POOL`: `host`. The host name for the back end. `backend`. The name of the back end. `POOL`. The pool name for the back end.
backend	body	string	The name of the back end.
pool	body	string	The pool name for the back end.
host	body	string	The host name for the back end.
capabilities	body	object	The back end capabilities which include `qos`, `total_capacity_gb`, etc.
qos	body	boolean	The quality of service (QoS) support.
timestamp	body	string	The date and time stamp when the API request was issued. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2015-08-27T09:49:58-05:00`.
share_backend_name	body	string	The name of the share back end.
server_pools_mapping	body	object	The mapping between servers and pools.
driver_handles_share_servers	body	boolean	Share server is usually a storage virtual machine or a lightweight container that is used to export shared file systems. Storage backends may be able to work with configured share servers or allow the share driver to create and manage the lifecycle of share servers. This capability specifies whether the pool’s associated share driver is responsible to create and manage the lifecycle of share servers. If `false`, the administrator of the shared file systems service has configured the share server as necessary for the given back end.
driver_version	body	string	The driver version of the back end.
total_capacity_gb	body	string	The total capacity for the back end, in GiBs. A valid value is a string, such as `unknown`, or an integer.
free_capacity_gb	body	string	The amount of free capacity for the back end, in GiBs. A valid value is a string, such as `unknown`, or an integer.
reserved_percentage	body	integer	The percentage of the total capacity that is reserved for the internal use by the back end.
vendor_name	body	string	The name of the vendor for the back end.
snapshot_support	body	boolean	The specification that filters back ends by whether they do or do not support share snapshots.
replication_domain	body	string	The back end replication domain.
storage_protocol	body	string	The storage protocol for the back end. For example, `NFS_CIFS`, `glusterfs`, `HDFS`, etc.

Response example¶

{
  "pools": [
    {
      "name": "opencloud@alpha#ALPHA_pool",
      "host": "opencloud",
      "backend": "alpha",
      "pool": "ALPHA_pool",
      "capabilities": {
        "pool_name": "ALPHA_pool",
        "total_capacity_gb": 1230.0,
        "free_capacity_gb": 1210.0,
        "reserved_percentage": 0,
        "share_backend_name": "ALPHA",
        "storage_protocol": "NFS_CIFS",
        "vendor_name": "Open Source",
        "driver_version": "1.0",
        "timestamp": "2019-05-07T00:28:02.935569",
        "driver_handles_share_servers": true,
        "snapshot_support": true,
        "create_share_from_snapshot_support": true,
        "revert_to_snapshot_support": true,
        "mount_snapshot_support": true,
        "dedupe": false,
        "compression": false,
        "replication_type": null,
        "replication_domain": null,
        "sg_consistent_snapshot_support": "pool",
        "ipv4_support": true,
        "ipv6_support": false
      }
    },
    {
      "name": "opencloud@beta#BETA_pool",
      "host": "opencloud",
      "backend": "beta",
      "pool": "BETA_pool",
      "capabilities": {
        "pool_name": "BETA_pool",
        "total_capacity_gb": 1230.0,
        "free_capacity_gb": 1210.0,
        "reserved_percentage": 0,
        "share_backend_name": "BETA",
        "storage_protocol": "NFS_CIFS",
        "vendor_name": "Open Source",
        "driver_version": "1.0",
        "timestamp": "2019-05-07T00:28:02.817309",
        "driver_handles_share_servers": true,
        "snapshot_support": true,
        "create_share_from_snapshot_support": true,
        "revert_to_snapshot_support": true,
        "mount_snapshot_support": true,
        "dedupe": false,
        "compression": false,
        "replication_type": null,
        "replication_domain": null,
        "sg_consistent_snapshot_support": "pool",
        "ipv4_support": true,
        "ipv6_support": false
      }
    },
    {
      "name": "opencloud@gamma#GAMMA_pool",
      "host": "opencloud",
      "backend": "gamma",
      "pool": "GAMMA_pool",
      "capabilities": {
        "pool_name": "GAMMA_pool",
        "total_capacity_gb": 1230.0,
        "free_capacity_gb": 1210.0,
        "reserved_percentage": 0,
        "replication_type": "readable",
        "share_backend_name": "GAMMA",
        "storage_protocol": "NFS_CIFS",
        "vendor_name": "Open Source",
        "driver_version": "1.0",
        "timestamp": "2019-05-07T00:28:02.899888",
        "driver_handles_share_servers": false,
        "snapshot_support": true,
        "create_share_from_snapshot_support": true,
        "revert_to_snapshot_support": true,
        "mount_snapshot_support": true,
        "dedupe": false,
        "compression": false,
        "replication_domain": "replica_domain_store1",
        "sg_consistent_snapshot_support": "pool",
        "ipv4_support": true,
        "ipv6_support": false
      }
    },
    {
      "name": "opencloud@delta#DELTA_pool",
      "host": "opencloud",
      "backend": "delta",
      "pool": "DELTA_pool",
      "capabilities": {
        "pool_name": "DELTA_pool",
        "total_capacity_gb": 1230.0,
        "free_capacity_gb": 1210.0,
        "reserved_percentage": 0,
        "replication_type": "readable",
        "share_backend_name": "DELTA",
        "storage_protocol": "NFS_CIFS",
        "vendor_name": "Open Source",
        "driver_version": "1.0",
        "timestamp": "2019-05-07T00:28:02.963660",
        "driver_handles_share_servers": false,
        "snapshot_support": true,
        "create_share_from_snapshot_support": true,
        "revert_to_snapshot_support": true,
        "mount_snapshot_support": true,
        "dedupe": false,
        "compression": false,
        "replication_domain": "replica_domain_store1",
        "sg_consistent_snapshot_support": "pool",
        "ipv4_support": true,
        "ipv6_support": false
      }
    }
  ]
}

Services¶

These APIs help in interacting with the Shared File Systems services, manila-scheduler, manila-share and manila-data.

Important

For API versions 2.6 and prior, replace services in the URLs with os-services.

Note

Starting from API version 2.83, disabled field will be replaced by status field in response of enable or disable service request. Re-enabling a disabled service will automatically clear disable reason.

GET

/v2/services?host={host}&binary={binary}&zone={zone}&state={state}&status={status}

List services

Lists all services optionally filtered with the specified search options.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
host (Optional)	query	string	The service host name.
binary (Optional)	query	string	The service binary name. Default is the base name of the executable.
zone (Optional)	query	string	The availability zone.
state (Optional)	query	string	The current state of the service. A valid value is `up` or `down`.
status (Optional)	query	string	The service status, which is `enabled` or `disabled`.

Response parameters¶

Name	In	Type	Description
services	body	string	Top element in the response body.
id	body	integer	The service ID.
status	body	string	The service status, which is `enabled` or `disabled`.
binary	body	string	The service binary name. Default is the base name of the executable.
zone	body	string	The service availability zone.
host	body	string	The service host name.
state	body	string	The current state of the service. A valid value is `up` or `down`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
disabled_reason	body	string	A reason for the service being disabled. New in version 2.83
ensuring	body	string	Whether the service is currently running ensure shares or not. New in version 2.86

Response example¶

{
    "services": [
        {
            "status": "enabled",
            "binary": "manila-share",
            "zone": "nova",
            "host": "manila2@generic1",
            "updated_at": "2015-09-07T13:03:57.000000",
            "state": "up",
            "id": 1
        },
        {
            "status": "enabled",
            "binary": "manila-scheduler",
            "zone": "nova",
            "host": "manila2",
            "updated_at": "2015-09-07T13:03:57.000000",
            "state": "up",
            "id": 2
        }
    ]
}

PUT

/v2/services/enable

Enable service

Enables a service.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
binary	body	string	The name of the service binary that you want to enable. Typically, this name is the base name of the executable.
host	body	string	The host name of the service that you want to enable.

Request example¶

{
    "binary": "manila-share",
    "host": "openstackhost@generic#pool_0"
}

Response parameters¶

Name	In	Type	Description
host	body	string	The host name of the enabled service.
binary	body	string	The service binary name. Default is the base name of the executable.
disabled	body	boolean	Indicates whether the service is disabled. Available until version 2.82
status	body	string	The service status, which is `enabled` or `disabled`. New in version 2.83
disabled_reason	body	string	A reason for the service being disabled. New in version 2.83

Response example¶

{
    "binary": "manila-share",
    "host": "openstackhost@generic#pool_0",
    "status": "enabled",
    "disabled_reason": ""
}

PUT

/v2/services/disable

Disable service

Disables a service.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
binary	body	string	The name of the service binary that you want to disable. Typically, this name is the base name of the executable.
host	body	string	The host name of the service that you want to disable.
disabled_reason (Optional)	body	string	A reason for the service being disabled. New in version 2.83

Request example¶

{
    "binary": "manila-share",
    "host": "openstackhost@generic#pool_0",
    "disabled_reason": "Service taken down for maintenance until May"
}

Response parameters¶

Name	In	Type	Description
host	body	string	The host name of the disabled service.
binary	body	string	The name of the disabled service binary. Typically, this name is the base name of the executable.
disabled	body	boolean	Indicates whether the service is disabled. Available until version 2.82
status	body	string	The service status, which is `enabled` or `disabled`. New in version 2.83
disabled_reason	body	string	A reason for the service being disabled. New in version 2.83

Response example¶

{
    "binary": "manila-share",
    "host": "openstackhost@generic#pool_0",
    "status": "disabled",
    "disabled_reason": "Service taken down for maintenance until May"
}

POST

/v2/services/ensure-shares

Ensure shares (Since API Version 2.86)

Starts the ensure shares procedure for a manila-share binary.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
host	body	string	The host name of the manila-share binary that you want to start the ensure shares procedure in the `host@backend` format.

Request example¶

{
    "host": "openstackhost@storagebackend"
}

Response parameters¶

There is no body content for the response.

Availability zones¶

Describes availability zones that the Shared File Systems service is configured with.

Important

For API versions 2.6 and prior, replace availability-zones in the URLs with os-availability-zone.

GET

/v2/availability-zones

List availability zones

Lists all availability zones.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).

Response parameters¶

Name	In	Type	Description
availability_zones	body	string	Top level response body element.
id	body	string	The availability zone ID the resource exists within.
name	body	string	The name of the availability zone.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.

Response example¶

{
    "availability_zones": [
        {
            "name": "nova",
            "created_at": "2015-09-18T09:50:55.000000",
            "updated_at": null,
            "id": "388c983d-258e-4a0e-b1ba-10da37d766db"
        }
    ]
}

Manage and unmanage shares (DEPRECATED)¶

Allows bringing shared file systems under service management.

Warning

This API is deprecated starting with microversion 2.7 and requests to this API will fail with a 404 starting from microversion 2.7. Use Share Manage API instead of this API from version 2.7.

Use this API to bring a share under the management of the Shared File Systems service. In the service, the share will be represented as a resource in the database. It can have a user defined name and description.

Administrator only. Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share	body	object	A `share` object.
protocol	body	string	The Shared File Systems protocol of the share to manage. A valid value is `NFS`, `CIFS`, `GlusterFS`, `CEPHFS`, `HDFS` or `MAPRFS`.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
display_name (Optional)	body	string	The user defined name of the resource. This field sets the `name` parameter.
share_type (Optional)	body	string	The name or ID of the share type to be used to create the resource. If you omit this parameter, the default share type is used. To view the default share type set by the administrator, issue a list default share types request.
driver_options (Optional)	body	object	A set of one or more key and value pairs, as a dictionary of strings, that describe driver options. Details for driver options should be taken from appropriate share driver documentation.
export_path	body	string	The share export path in the format appropriate for the protocol: NFS protocol. `10.0.0.1:/foo_path`. For example, `10.254.0 .5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5`. CIFS protocol. For example, `\\10.0.0.1\foo_name_of_cifs_share`.
service_host	body	string	The manage-share service host in this format: `host@backend#POOL`: `host`. The host name for the back end. `backend`. The name of the back end. `POOL`. The pool name for the back end.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
display_description (Optional)	body	string	The user defined description of the resource. This field sets the `description` parameter.

Request example¶

{
    "share": {
        "protocol": "nfs",
        "name": "accounting_p8787",
        "share_type": "gold",
        "driver_options": {
            "opt1": "opt1",
            "opt2": "opt2"
        },
        "export_path": "192.162.10.6:/shares/share-accounting_p8787",
        "service_host": "manila2@openstackstor01#accountingpool",
        "is_public": true,
        "description": "Common storage for spreadsheets and presentations. Please contact John Accessman to be added to the users of this drive.",
        "share_server_id": "00137b40-ca06-4ae8-83a3-2c5989eebcce"
    }
}

Response parameters¶

Name	In	Type	Description
share	body	object	A `share` object.
links	body	array	Pagination and bookmark links for the resource.
availability_zone	body	string	The name of the availability zone the share exists within.
share_network_id	body	string	The share network ID where the resource is exported to.
export_locations	body	array	A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
share_server_id	body	string	The UUID of the share server.
snapshot_id	body	string	The UUID of the snapshot that was used to create the share.
id	body	string	The UUID of the share.
size	body	integer	The share size, in GiBs.
share_type	body	string	The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.
share_type_name	body	string	Name of the share type.
export_location	body	string	The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations. Available until version 2.8
project_id	body	string	The ID of the project that owns the resource.
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.
status	body	string	The share or share instance status. Possible values are listed in the section above.
description	body	string	The user defined description of the resource.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
is_public	body	boolean	Whether the share is visible publicly (by all projects in the cloud) or not.
snapshot_support	body	boolean	An extra specification that filters back ends by whether they do or do not support share snapshots. New in version 2.2
name	body	string	The user defined name of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
share_proto	body	string	The Shared File Systems protocol. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS`, `MAPRFS`, `CephFS` supported is starting with API v2.13.

Response example¶

{
    "share": {
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/00137b40-ca06-4ae8-83a3-2c5989eebcce",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/00137b40-ca06-4ae8-83a3-2c5989eebcce",
                "rel": "bookmark"
            }
        ],
        "availability_zone": null,
        "share_network_id": null,
        "export_locations": [],
        "share_server_id": "00137b40-ca06-4ae8-83a3-2c5989eebcce",
        "share_group_id": null,
        "snapshot_id": null,
        "id": "00137b40-ca06-4ae8-83a3-2c5989eebcce",
        "size": null,
        "share_type": "14747856-08e5-494f-ab40-a64b9d20d8f7",
        "share_type_name": "d",
        "export_location": "10.254.0.5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "metadata": {},
        "status": "manage_starting",
        "description": "Lets manage share.",
        "user_id": "66ffd308757e44b9a8bec381322b0b88",
        "host": "manila2@unmanage1#UNMANAGE1",
        "access_rules_status": "active",
        "has_replicas": false,
        "replication_type": null,
        "is_public": false,
        "snapshot_support": true,
        "name": "share_texas1",
        "created_at": "2019-03-05T10:00:00.000000",
        "share_proto": "NFS",
        "volume_type": "d"
    }
}

Warning

This API is deprecated starting with microversion 2.7 and requests to this API will fail with a 404 starting from microversion 2.7. Use Share Unmanage API instead of this API from version 2.7.

Use this API to remove a share from the management of the Shared File Systems service without deleting the share.

Administrator only. Use the policy.yaml file to grant permissions for this action to other roles.

Preconditions:

This API does not support unmanaging shares that are created on top of share servers (i.e. created with share networks).
You should remove any snapshots and share replicas before attempting to unmanage a share.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	path	string	The UUID of the share.

Response parameters¶

There is no body content for the response.

Quota sets¶

Provides quotas management support.

Important

For API versions 2.6 and prior, replace quota-sets in the URLs with os-quota-sets.

Share type quotas were added in API version 2.39. It is possible to set quotas per share type for the following quota resources:

gigabytes
snapshots
shares
snapshot_gigabytes
share_groups (since API version 2.40)
share_group_snapshots (since API version 2.40)
share_replicas (since API version 2.53)
replica_gigabytes (since API version 2.53)
per_share_gigabytes (since API version 2.62)
backups (since API version 2.80)
backup_gigabytes (since API version 2.80)

In order to manipulate share type quotas, the requests will be similar to the examples below, except that the user_id={user_id} must be replaced by share_type={share_type_name_or_id} in the request path.

Share groups and share group snapshots were added to quota management APIs in API version 2.40.

Share replicas and replica gigabytes were added to quota management APIs in API version 2.53.

Per share gigabytes was added to quota management APIs in API version 2.62.

Share backups and backup gigabytes were added to quota management APIs in API version 2.80.

GET

/v2/quota-sets/{project_id_quota_request_path}/defaults

Show default quota set

Shows default quotas for a given project.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name

Type

Description

project_id (Optional)

path

string

project_id_quota_request_path (Optional)

path

string

The ID of the project whose quotas must be acted upon by the API. This is optional, and if it is not specified, the project ID is derived from the caller’s API token. System/Domain scoped users interacting with this API must specify the project ID for the project whose quotas they need to query or manipulate.

Note that this ID can be different from the project ID that precedes the resource name “quota-sets”. For example, in a multi-tenant cloud, the first ID in the URL is typically the project ID of a privileged user (such as a cloud administrator) that can create, query or delete quotas of other projects in the cloud. If a server supports API version 2.60, URLs no longer need the privileged user’s project ID prior to the resource name.

Response parameters¶

Name	In	Type	Description
quota_set	body	object	The `quota_set` object.
id	body	string	The ID of the project the quota pertains to.
gigabytes	body	integer	The number of gigabytes allowed for each project.
snapshots	body	integer	The number of snapshots allowed for each project.
shares	body	integer	The number of shares allowed for each project.
snapshot_gigabytes	body	integer	The number of gigabytes for the snapshots allowed for each project.
share_networks (Optional)	body	integer	The number of share networks allowed for user and project, but not share type.
share_groups	body	integer	The number of share groups allowed for each project or user. New in version 2.40
share_group_snapshots	body	integer	The number of share group snapshots allowed for each project or user. New in version 2.40
share_networks	body	integer	The number of share networks allowed for each project.
share_replicas	body	integer	The number of share replicas allowed for each project. New in version 2.53
replica_gigabytes	body	integer	The number of gigabytes for the share replicas allowed for each project. New in version 2.53
per_share_gigabytes	body	integer	The number of gigabytes per share allowed for each project. New in version 2.62
backups	body	integer	The number of backups allowed for each project. New in version 2.80
backup_gigabytes	body	integer	The number of gigabytes for the backups allowed for each project. New in version 2.80

Response example¶

{
    "quota_set": {
        "gigabytes": 1000,
        "shares": 50,
        "snapshot_gigabytes": 1000,
        "snapshots": 50,
        "id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_networks": 10,
        "share_groups": 10,
        "share_group_snapshots": 10,
        "share_replicas": 100,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 50,
        "backup_gigabytes": 1000
    }
}

GET

/v2/quota-sets/{project_id_quota_request_path}?user_id={user_id}

Show quota set

Shows quotas for a given project..

If you specify the optional user_id query parameter, you get the quotas for this user in the project. If you omit this parameter, you get the quotas for the project.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
project_id_quota_request_path (Optional)	path	string	The ID of the project whose quotas must be acted upon by the API. This is optional, and if it is not specified, the project ID is derived from the caller’s API token. System/Domain scoped users interacting with this API must specify the project ID for the project whose quotas they need to query or manipulate. Note that this ID can be different from the project ID that precedes the resource name “quota-sets”. For example, in a multi-tenant cloud, the first ID in the URL is typically the project ID of a privileged user (such as a cloud administrator) that can create, query or delete quotas of other projects in the cloud. If a server supports API version 2.60, URLs no longer need the privileged user’s project ID prior to the resource name.
user_id (Optional)	query	string	The ID of the user. If you specify this query parameter, you retrieve or update the quotas for this user in the project. If you omit this parameter, you query or update the quotas for the whole project. This parameter is mutually exclusive with the “share_type” parameter.
share_type (Optional)	path	string	The name or UUID of the share type. If you specify this parameter in the URI, you show, update, or delete quotas for this share type. This parameter is mutually exclusive with the “user_id” query parameter. New in version 2.39

Response parameters¶

Name	In	Type	Description
quota_set	body	object	The `quota_set` object.
id	body	string	The ID of the project the quota pertains to.
gigabytes	body	integer	The number of gigabytes allowed for each project.
snapshots	body	integer	The number of snapshots allowed for each project.
shares	body	integer	The number of shares allowed for each project.
snapshot_gigabytes	body	integer	The number of gigabytes for the snapshots allowed for each project.
share_networks (Optional)	body	integer	The number of share networks allowed for user and project, but not share type.
share_groups	body	integer	The number of share groups allowed for each project or user. New in version 2.40
share_group_snapshots	body	integer	The number of share group snapshots allowed for each project or user. New in version 2.40
share_replicas	body	integer	The number of share replicas allowed for each project. New in version 2.53
replica_gigabytes	body	integer	The number of gigabytes for the share replicas allowed for each project. New in version 2.53
per_share_gigabytes	body	integer	The number of gigabytes per share allowed for each project. New in version 2.62
backups	body	integer	The number of backups allowed for each project. New in version 2.80
backup_gigabytes	body	integer	The number of gigabytes for the backups allowed for each project. New in version 2.80

Response example¶

{
    "quota_set": {
        "gigabytes": 1000,
        "shares": 50,
        "snapshot_gigabytes": 1000,
        "snapshots": 50,
        "id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_networks": 10,
        "share_groups": 10,
        "share_group_snapshots": 10,
        "share_replicas": 100,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 50,
        "backup_gigabytes": 1000
    }
}

GET

/v2/quota-sets/{project_id_quota_request_path}/detail?user_id={user_id}

Show quota set in detail (since API v2.25)

Added in version 2.25.

Shows quotas for a project in detail.

If you specify the optional user_id query parameter, you get the quotas for this user in the project. If you omit this parameter, you get the quotas for the project.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
project_id_quota_request_path (Optional)	path	string	The ID of the project whose quotas must be acted upon by the API. This is optional, and if it is not specified, the project ID is derived from the caller’s API token. System/Domain scoped users interacting with this API must specify the project ID for the project whose quotas they need to query or manipulate. Note that this ID can be different from the project ID that precedes the resource name “quota-sets”. For example, in a multi-tenant cloud, the first ID in the URL is typically the project ID of a privileged user (such as a cloud administrator) that can create, query or delete quotas of other projects in the cloud. If a server supports API version 2.60, URLs no longer need the privileged user’s project ID prior to the resource name.
user_id (Optional)	query	string	The ID of the user. If you specify this query parameter, you retrieve or update the quotas for this user in the project. If you omit this parameter, you query or update the quotas for the whole project. This parameter is mutually exclusive with the “share_type” parameter.
share_type (Optional)	path	string	The name or UUID of the share type. If you specify this parameter in the URI, you show, update, or delete quotas for this share type. This parameter is mutually exclusive with the “user_id” query parameter. New in version 2.39

Response parameters¶

Name	In	Type	Description
quota_set	body	object	The `quota_set` object.
id	body	string	The ID of the project the quota pertains to.
gigabytes	body	object	The limit, in_use, reserved number of gigabytes allowed for each project. New in version 2.25
snapshots	body	object	The limit, in_use, reserved number of snapshots allowed for each project. New in version 2.25
shares	body	object	The limit, in_use, reserved number of shares allowed for each project. New in version 2.25
snapshot_gigabytes	body	object	The limit, in_use, reserved number of gigabytes for the snapshots allowed for each project. New in version 2.25
share_networks (Optional)	body	object	The limit, in_use, reserved number of share networks allowed for user and project, but not share type. New in version 2.25
share_groups	body	object	The limit, in_use, reserved number of share groups for each project or user. New in version 2.40
share_group_snapshots	body	object	The limit, in_use, reserved number of share group snapshots for each project or user. New in version 2.40
share_replicas	body	object	The limit, in_use, reserved number of share replicas for each project. New in version 2.53
replica_gigabytes	body	object	The limit, in_use, reserved number of replica gigabytes for each project. New in version 2.53
per_share_gigabytes	body	object	The limit, in_use, reserved number of per share gigabytes for each project. New in version 2.62
backups	body	object	The limit, in_use, reserved number of backups allowed for each project. New in version 2.80
backup_gigabytes	body	object	The limit, in_use, reserved number of gigabytes for the backups allowed for each project. New in version 2.80

Response example¶

{
    "quota_set": {
        "id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "gigabytes": {"in_use": 0,
                      "limit": 1000,
                      "reserved": 0},
        "shares": {"in_use": 0,
                   "limit": 50,
                   "reserved": 0},
        "snapshot_gigabytes": {"in_use": 0,
                               "limit": 1000,
                               "reserved": 0},
        "snapshots": {"in_use": 0,
                      "limit": 50,
                      "reserved": 0},
        "share_networks": {"in_use": 0,
                           "limit": 10,
                           "reserved": 0},
        "share_groups": {"in_use": 0,
                         "limit": 10,
                         "reserved": 0},
        "share_group_snapshots": {"in_use": 0,
                                  "limit": 10,
                                  "reserved": 0},
        "share_replicas": {"in_use": 0,
                           "limit": 100,
                           "reserved": 0},
        "replica_gigabytes": {"in_use": 0,
                              "limit": 1000,
                              "reserved": 0},
        "per_share_gigabytes": {"in_use": 0,
                                "limit": -1,
                                "reserved": 0},
        "backup_gigabytes": {"in_use": 0,
                             "limit": 1000,
                             "reserved": 0},
        "backups": {"in_use": 0,
                    "limit": 50,
                    "reserved": 0}
    }
}

PUT

/v2/quota-sets/{project_id_quota_request_path}?user_id={user_id}

Update quota set

Updates quotas for a project.

If you specify the optional user_id query parameter, you update the quotas for this user in the project. If you omit this parameter, you update the quotas for the project.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
project_id_quota_request_path (Optional)	path	string	The ID of the project whose quotas must be acted upon by the API. This is optional, and if it is not specified, the project ID is derived from the caller’s API token. System/Domain scoped users interacting with this API must specify the project ID for the project whose quotas they need to query or manipulate. Note that this ID can be different from the project ID that precedes the resource name “quota-sets”. For example, in a multi-tenant cloud, the first ID in the URL is typically the project ID of a privileged user (such as a cloud administrator) that can create, query or delete quotas of other projects in the cloud. If a server supports API version 2.60, URLs no longer need the privileged user’s project ID prior to the resource name.
user_id (Optional)	query	string	The ID of the user. If you specify this query parameter, you retrieve or update the quotas for this user in the project. If you omit this parameter, you query or update the quotas for the whole project. This parameter is mutually exclusive with the “share_type” parameter.
quota_set	body	object	The `quota_set` object.
force (Optional)	body	boolean	Indicates whether to permit or deny the force- update of a quota that is already used and the requested value exceeds the configured quota. Set to `True` to permit the force-update of the quota. Set to `False` to deny the force- update of the quota.
gigabytes (Optional)	body	integer	The number of gigabytes for the project.
snapshots (Optional)	body	integer	The number of snapshots for the project.
snapshot_gigabytes (Optional)	body	integer	The number of gigabytes for the snapshots for the project.
shares (Optional)	body	integer	The number of shares for the project.
share_networks (Optional)	body	integer	The number of share networks for the project.
share_groups (Optional)	body	integer	The number of share groups allowed for each project or user. New in version 2.40
share_group_snapshots (Optional)	body	integer	The number of share group snapshots allowed for each project or user. New in version 2.40
share_type (Optional)	path	string	The name or UUID of the share type. If you specify this parameter in the URI, you show, update, or delete quotas for this share type. This parameter is mutually exclusive with the “user_id” query parameter. New in version 2.39
share_replicas (Optional)	body	integer	The number of share replicas allowed for each project or user. New in version 2.53
replica_gigabytes (Optional)	body	integer	The number of gigabytes for share replicas for the project. New in version 2.53
per_share_gigabytes (Optional)	body	integer	The number of gigabytes per share allowed for each project. New in version 2.62
backups (Optional)	body	integer	The number of backups for the project. New in version 2.80
backup_gigabytes (Optional)	body	integer	The number of gigabytes for the backups for the project. New in version 2.80

Request example¶

{
    "quota_set": {
        "snapshot_gigabytes": 999,
        "snapshots": 49,
        "share_networks": 9,
        "share_replicas": 89,
        "per_share_gigabytes": 5
    }
}

Response parameters¶

Name	In	Type	Description
quota_set	body	object	The `quota_set` object.
id	body	string	The ID of the project the quota pertains to.
gigabytes	body	integer	The number of gigabytes allowed for each project.
snapshots	body	integer	The number of snapshots allowed for each project.
shares	body	integer	The number of shares allowed for each project.
snapshot_gigabytes	body	integer	The number of gigabytes for the snapshots allowed for each project.
share_networks (Optional)	body	integer	The number of share networks allowed for user and project, but not share type.
share_groups	body	integer	The number of share groups allowed for each project or user. New in version 2.40
share_group_snapshots	body	integer	The number of share group snapshots allowed for each project or user. New in version 2.40
share_replicas	body	integer	The number of share replicas allowed for each project. New in version 2.53
replica_gigabytes	body	integer	The number of gigabytes for the share replicas allowed for each project. New in version 2.53
per_share_gigabytes	body	integer	The number of gigabytes per share allowed for each project. New in version 2.62
backups	body	integer	The number of backups allowed for each project. New in version 2.80
backup_gigabytes	body	integer	The number of gigabytes for the backups allowed for each project. New in version 2.80

Response example¶

{
    "quota_set": {
        "gigabytes": 1000,
        "snapshot_gigabytes": 999,
        "shares": 50,
        "snapshots": 49,
        "share_networks": 9,
        "share_groups": 12,
        "share_group_snapshots": 12,
        "share_replicas": 89,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 40,
        "backup_gigabytes": 500
    }
}

DELETE

/v2/quota-sets/{project_id_quota_request_path}?user_id={user_id}

Delete quota set

Deletes quotas for a project. The quota reverts to the default quota.

If you specify the optional user_id query parameter, you delete the quotas for this user in the project. If you omit this parameter, you delete the quotas for the project.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
project_id_quota_request_path (Optional)	path	string	The ID of the project whose quotas must be acted upon by the API. This is optional, and if it is not specified, the project ID is derived from the caller’s API token. System/Domain scoped users interacting with this API must specify the project ID for the project whose quotas they need to query or manipulate. Note that this ID can be different from the project ID that precedes the resource name “quota-sets”. For example, in a multi-tenant cloud, the first ID in the URL is typically the project ID of a privileged user (such as a cloud administrator) that can create, query or delete quotas of other projects in the cloud. If a server supports API version 2.60, URLs no longer need the privileged user’s project ID prior to the resource name.
user_id (Optional)	query	string	The ID of the user. If you specify this query parameter, you retrieve or update the quotas for this user in the project. If you omit this parameter, you query or update the quotas for the whole project. This parameter is mutually exclusive with the “share_type” parameter.
share_type (Optional)	path	string	The name or UUID of the share type. If you specify this parameter in the URI, you show, update, or delete quotas for this share type. This parameter is mutually exclusive with the “user_id” query parameter. New in version 2.39

Quota class set¶

Quota classes can be shown and updated for a project.

Important

Share replicas and replica gigabytes were added to quota management APIs in API version 2.53. Per share gigabytes was added to quota management APIs in API version 2.62. Share backups and backup gigabytes were added to quota management APIs in API version 2.80.

GET

/v2/quota-class-sets/{quota_class_name}

Show quota classes for a project

Shows quota class set for a project. If no specific value for the quota class resource exists, then the default value will be reported.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
quota_class_name	path	string	The name of the quota class for which to set quotas.

Response Parameters¶

Name	In	Type	Description
quota_class_set	body	object	A `quota_class_set` object.
share_groups	body	integer	The maximum number of share groups. New in version 2.40
gigabytes	body	integer	The total maximum number of share gigabytes that are allowed in a project. You cannot request a share that exceeds the allowed gigabytes quota.
share_group_snapshots	body	integer	The maximum number of share group snapshots. New in version 2.40
snapshots	body	integer	The total maximum number of share snapshots that are allowed in a project.
snapshot_gigabytes	body	integer	The total maximum number of snapshot gigabytes that are allowed in a project.
shares	body	integer	The total maximum number of shares that are allowed in a project.
id	body	string	A `quota_class_set` id.
share_networks	body	integer	The total maximum number of share-networks that are allowed in a project.
share_replicas	body	integer	The maximum number of share replicas that is allowed. New in version 2.53
replica_gigabytes	body	integer	The maximum number of replica gigabytes that are allowed in a project. You cannot create a share, share replica, manage a share or extend a share if it is going to exceed the allowed replica gigabytes quota. New in version 2.53
per_share_gigabytes	body	integer	The number of gigabytes per share allowed in a project. New in version 2.62
backups	body	integer	The total maximum number of share backups that are allowed in a project. New in version 2.80
backup_gigabytes	body	integer	The total maximum number of backup gigabytes that are allowed in a project. New in version 2.80

Response Example¶

{
    "quota_class_set": {
        "share_groups": 50,
        "gigabytes": 1000,
        "share_group_snapshots": 50,
        "snapshots": 50,
        "snapshot_gigabytes": 1000,
        "shares": 50,
        "id": "default",
        "share_networks": 10,
        "share_replicas": 100,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 50,
        "backup_gigabytes": 1000
    }
}

PUT

/v2/quota-class-sets/{quota_class_name}

Update quota classes for a project

Updates quota class set for a project. If the quota_class_name key does not exist, then the API will create one.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
quota_class_name	path	string	The name of the quota class for which to set quotas.
shares (Optional)	body	integer	The total maximum number of shares that are allowed in a project.
snapshots (Optional)	body	integer	The total maximum number of share snapshots that are allowed in a project.
gigabytes (Optional)	body	integer	The total maximum number of share gigabytes that are allowed in a project. You cannot request a share that exceeds the allowed gigabytes quota.
snapshot-gigabytes (Optional)	body	integer	The total maximum number of snapshot gigabytes that are allowed in a project.
share-networks (Optional)	body	integer	The total maximum number of share-networks that are allowed in a project.
share-replicas (Optional)	body	integer	The maximum number of share replicas that is allowed. New in version 2.53
replica-gigabytes (Optional)	body	integer	The maximum number of replica gigabytes that are allowed in a project. You cannot create a share, share replica, manage a share or extend a share if it is going to exceed the allowed replica gigabytes quota. New in version 2.53
per-share-gigabytes (Optional)	body	integer	The number of gigabytes per share allowed in a project. New in version 2.62
backups (Optional)	body	integer	The total maximum number of share backups that are allowed in a project. New in version 2.80
backup-gigabytes (Optional)	body	integer	The total maximum number of backup gigabytes that are allowed in a project. New in version 2.80

Request Example¶

{
    "quota_class_set": {
        "class_name": "test-qupta-class-update",
        "gigabytes": 20
    }
}

Response Parameters¶

Name	In	Type	Description
quota_class_set	body	object	A `quota_class_set` object.
share_groups	body	integer	The maximum number of share groups. New in version 2.40
gigabytes	body	integer	The total maximum number of share gigabytes that are allowed in a project. You cannot request a share that exceeds the allowed gigabytes quota.
share_group_snapshots	body	integer	The maximum number of share group snapshots. New in version 2.40
snapshots	body	integer	The total maximum number of share snapshots that are allowed in a project.
snapshot_gigabytes	body	integer	The total maximum number of snapshot gigabytes that are allowed in a project.
shares	body	integer	The total maximum number of shares that are allowed in a project.
share_networks	body	integer	The total maximum number of share-networks that are allowed in a project.
share_replicas	body	integer	The maximum number of share replicas that is allowed. New in version 2.53
replica_gigabytes	body	integer	The maximum number of replica gigabytes that are allowed in a project. You cannot create a share, share replica, manage a share or extend a share if it is going to exceed the allowed replica gigabytes quota. New in version 2.53
per_share_gigabytes	body	integer	The number of gigabytes per share allowed in a project. New in version 2.62
backups	body	integer	The total maximum number of share backups that are allowed in a project. New in version 2.80
backup_gigabytes	body	integer	The total maximum number of backup gigabytes that are allowed in a project. New in version 2.80

Response Example¶

{
    "quota_class_set": {
        "share_groups": 50,
        "gigabytes": 20,
        "share_group_snapshots": 50,
        "snapshots": 50,
        "snapshot_gigabytes": 1000,
        "shares": 50,
        "share_networks": 10,
        "share_replicas": 100,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 50,
        "backup_gigabytes": 1000
    }
}

User messages (since API 2.37)¶

Lists, shows and deletes user messages.

User messages are automatically created when an asynchronous action fails on a resource. In such situations an error is logged in the appropriate log file but end users may not have access to the log files. User messages can be used by users to get error details for failed actions. This is handy for example when creating shares - if a share creation fails because a scheduling filter doesn’t find suitable back-end host for the share, this share will end up in error state, but from user messages API users can get details about the last executed filter which helps them identify the issue and perhaps re-attempt the creation request with different parameters.

GET

/v2/messages

List user messages

Added in version 2.37.

Lists all user messages.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
limit (Optional)	query	integer	The maximum number of resource records to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of messages. A valid value is `id`, `project_id`, `request_id`, `resource_type`, `action_id`, `detail_id`, `resource_id`, `message_level`, `expires_at`, `created_at`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.
action_id (Optional)	query	string	The ID of the action during which the message was created.
detail_id (Optional)	query	string	The ID of the message detail.
message_level (Optional)	query	string	The message level.
project_id (Optional)	query	string	The ID of the project for which the message was created.
request_id (Optional)	query	string	The ID of the request during which the message was created.
resource_id (Optional)	query	string	The UUID of the resource for which the message was created.
resource_type (Optional)	query	string	The type of the resource for which the message was created.
created_since (Optional)	query	string	The date and time stamp when the query operation, only return user messages since it. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2021-11-10T09:49:58+08:00`. New in version 2.52
created_before (Optional)	query	string	The date and time stamp when the query operation, only return user messages before it. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2021-11-10T09:49:58+08:00`. New in version 2.52

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the message.
action_id	body	string	The ID of the action during which the message was created.
detail_id	body	string	The ID of the message detail.
message_level	body	string	The message level.
project_id	body	string	The ID of the project for which the message was created.
request_id	body	string	The UUID of the request during which the message was created.
resource_id	body	string	The UUID of the resource for which the message was created.
resource_type	body	string	The type of the resource for which the message was created.
message_members_links	body	array	The message member links.
expires_at	body	string	The date and time stamp when the resource message will expire within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "messages": [
        {
            "links": [
                {
                    "href": "http://192.168.122.180:8786/v2/2e3de76b49b444fd9dc7ca9f7048ce6b/messages/4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.122.180:8786/2e3de76b49b444fd9dc7ca9f7048ce6b/messages/4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5",
                    "rel": "bookmark"
                }
            ],
            "id": "4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5",
            "resource_id": "351cc796-2d79-4a08-b878-a8ed933b6b68",
            "message_level": "ERROR",
            "user_message": "allocate host: No storage could be allocated for this share request. Trying again with a different size or share type may succeed.",
            "expires_at": "2017-07-10T10:27:43.000000",
            "created_at": "2017-07-10T10:26:43.000000",
            "detail_id": "002",
            "request_id": "req-24e7ccb6-a7d5-4ddd-a8e4-d8f72a4509c8",
            "project_id": "2e3de76b49b444fd9dc7ca9f7048ce6b",
            "resource_type": "SHARE",
            "action_id": "001"
        }
    ]
}

GET

/v2/messages/{message_id}

Show user message details

Added in version 2.37.

Shows details for a user message.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
message_id (Optional)	path	string	The UUID of the message.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the message.
action_id	body	string	The ID of the action during which the message was created.
detail_id	body	string	The ID of the message detail.
message_level	body	string	The message level.
project_id	body	string	The ID of the project for which the message was created.
request_id	body	string	The UUID of the request during which the message was created.
resource_id	body	string	The UUID of the resource for which the message was created.
resource_type	body	string	The type of the resource for which the message was created.
message_links	body	array	The message links.
expires_at	body	string	The date and time stamp when the resource message will expire within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.

Response example¶

{
    "message": {
        "links": [
            {
                "href": "http://192.168.122.180:8786/v2/2e3de76b49b444fd9dc7ca9f7048ce6b/messages/4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5",
                "rel": "self"
            },
            {
                "href": "http://192.168.122.180:8786/2e3de76b49b444fd9dc7ca9f7048ce6b/messages/4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5",
                "rel": "bookmark"
            }
        ],
        "resource_id": "351cc796-2d79-4a08-b878-a8ed933b6b68",
        "message_level": "ERROR",
        "user_message": "allocate host: No storage could be allocated for this share request. Trying again with a different size or share type may succeed.",
        "expires_at": "2017-07-10T10:27:43.000000",
        "id": "4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5",
        "created_at": "2017-07-10T10:26:43.000000",
        "detail_id": "002",
        "request_id": "req-24e7ccb6-a7d5-4ddd-a8e4-d8f72a4509c8",
        "project_id": "2e3de76b49b444fd9dc7ca9f7048ce6b",
        "resource_type": "SHARE",
        "action_id": "001"
    }
}

DELETE

/v2/messages/{message_id}

Delete message

Added in version 2.37.

Deletes a user message.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
message_id (Optional)	path	string	The UUID of the message.

Share access rules (since API v2.45)¶

Retrieve details about access rules

Note

Starting from API version 2.82, access rule visibility can be restricted by a project user, or any user with “service” or “admin” roles. When restricted, the access_to and access_key fields will be redacted to other users. This redaction applies irrespective of the API version.

Added in version 2.45.

Retrieve details about a specified access rule.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
access_id	path	string	The UUID of the access rule to which access is granted.

Response parameters¶

Name	In	Type	Description
share_id	body	string	The UUID of the share to which you are granted or denied access.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
access_type	body	string	The access rule type. A valid value for the share access rule type is one of the following values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_to	body	string	The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_key	body	string	The access credential of the entity granted share access.
state	body	string	Prior to versions 2.28, the state of all access rules of a given share is the same at all times. This could be `new`, `active` or `error`. Since 2.28, the state of each access rule of a share is independent of the others and can be `queued_to_apply`, `applying`, `active`, `error`, `queued_to_deny` or `denying`. A new rule starts out in `queued_to_apply` state and is successfully applied if it transitions to `active` state.
access_level	body	string	The access level to the share. To grant or deny access to a share, you specify one of the following share access levels: `rw`. Read and write (RW) access. `ro`. Read-only (RO) access.
id	body	string	The access rule ID.
metadata	body	object	One or more access rule metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "access": {
        "access_level": "rw",
        "state": "error",
        "id": "507bf114-36f2-4f56-8cf4-857985ca87c1",
        "share_id": "fb213952-2352-41b4-ad7b-2c4c69d13eef",
        "access_type": "cert",
        "access_to": "example.com",
        "access_key": null,
        "created_at": "2018-07-17T02:01:04.000000",
        "updated_at": "2018-07-17T02:01:04.000000",
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

Added in version 2.45.

Lists the share access rules on a share.

Note

This API replaces the older List share access rules API from version 2.45.

Note

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_id	query	string	The share ID to filter share access rules with.
metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more access rule metadata key and value pairs as a dictionary of strings.
access_type	body	string	The access rule type. A valid value for the share access rule type is one of the following values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_key	body	string	The access credential of the entity granted share access.
access_to	body	string	The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_level	body	string	The access level to the share. To grant or deny access to a share, you specify one of the following share access levels: `rw`. Read and write (RW) access. `ro`. Read-only (RO) access.
state	body	string	Prior to versions 2.28, the state of all access rules of a given share is the same at all times. This could be `new`, `active` or `error`. Since 2.28, the state of each access rule of a share is independent of the others and can be `queued_to_apply`, `applying`, `active`, `error`, `queued_to_deny` or `denying`. A new rule starts out in `queued_to_apply` state and is successfully applied if it transitions to `active` state.
access_list	body	string	The object of the access rule. To list access rules, set this value to `null`.
id	body	string	The access rule ID.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.

Response example¶

{
    "access_list": [
        {
            "access_level": "rw",
            "state": "error",
            "id": "507bf114-36f2-4f56-8cf4-857985ca87c1",
            "access_type": "cert",
            "access_to": "example.com",
            "access_key": null,
            "created_at": "2018-07-17T02:01:04.000000",
            "updated_at": "2018-07-17T02:01:04.000000",
            "metadata": {
                "key1": "value1",
                "key2": "value2"
            }
        },
        {
            "access_level": "rw",
            "state": "active",
            "id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452",
            "access_type": "ip",
            "access_to": "0.0.0.0/0",
            "access_key": null,
            "created_at": "2018-07-16T01:03:21.000000",
            "updated_at": "2018-07-16T01:03:21.000000",
            "metadata": {
                "key3": "value3",
                "key4": "value4"
            }
        }
    ]
}

Added in version 2.88.

Update access_level of a specified access rule.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name

Type

Description

project_id (Optional)

path

string

access_id

path

string

The UUID of the access rule to which access is granted.

access_level

body

string

The access level to the share. To grant or deny access to a share, you specify one of the following share access levels:

rw. Read and write (RW) access.
ro. Read-only (RO) access.

Request example¶

{
    "update_access": {
        "access_level": "ro"
    }
}

Response parameters¶

Name	In	Type	Description
share_id	body	string	The UUID of the share to which you are granted or denied access.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
access_type	body	string	The access rule type. A valid value for the share access rule type is one of the following values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_to	body	string	The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values: `ip`: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example `0.0.0.0/0` for IPv4 or `::/0` for IPv6. `cert`: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. `user`: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.
access_key	body	string	The access credential of the entity granted share access.
state	body	string	Prior to versions 2.28, the state of all access rules of a given share is the same at all times. This could be `new`, `active` or `error`. Since 2.28, the state of each access rule of a share is independent of the others and can be `queued_to_apply`, `applying`, `active`, `error`, `queued_to_deny` or `denying`. A new rule starts out in `queued_to_apply` state and is successfully applied if it transitions to `active` state.
access_level	body	string	The access level to the share. To grant or deny access to a share, you specify one of the following share access levels: `rw`. Read and write (RW) access. `ro`. Read-only (RO) access.
id	body	string	The access rule ID.
metadata	body	object	One or more access rule metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "access": {
        "access_level": "ro",
        "state": "error",
        "id": "507bf114-36f2-4f56-8cf4-857985ca87c1",
        "share_id": "fb213952-2352-41b4-ad7b-2c4c69d13eef",
        "access_type": "ip",
        "access_to": "0.0.0.0/0",
        "access_key": null,
        "created_at": "2024-12-17T02:01:04.000000",
        "updated_at": "2024-12-17T02:01:04.000000",
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

Share access rule metadata (since API v2.45)¶

Updates, and unsets share access rule metadata.

Added in version 2.45.

Updates the metadata for a share access rule.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
access_id	path	string	The UUID of the access rule to which access is granted.
metadata	body	object	One or more access rule metadata key and value pairs as a dictionary of strings.

Request example¶

{
    "metadata": {
        "aim": "changed_doc",
        "speed": "my_fast_access",
        "new_metadata_key": "new_information"
    }
}

Response parameters¶

Name	In	Type	Description
metadata	body	object	One or more access rule metadata key and value pairs as a dictionary of strings.

Response example¶

{
    "metadata": {
        "aim": "changed_doc",
        "speed": "my_fast_access",
        "new_metadata_key": "new_information"
    }
}

Added in version 2.45.

Un-sets the metadata on a share access rule.

To unset a metadata key value, specify only the key name in the URI.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
access_id	path	string	The UUID of the access rule to which access is granted.
key (Optional)	path	string	The key of a metadata item. For example, if the metadata on an existing share or access rule is as follows: `"project": "my_test", "aim": "testing"`, the keys are “project” and “aim”.

Share groups (since API v2.31)¶

The share groups enable you to create a group of volumes and manage them together. A project can put shares be used in the same application together in a share group, such as consistency group snapshot, clone, backup, migrate, replicate, retype, etc.

Shares should be able to become a part of a share group only on share creation step. If share was created without provided share_group_id then this share won’t be able to become a part of any share group.

You can create a share group and associate it with multiple shares, list share groups, and show information for delete a share group.

Note

Share Group APIs are no longer considered experimental since API version 2.55. The availability_zone_id and consistent_snapshot_support fields were added to share_group object since version 2.34.

Added in version 2.31.

Lists all share groups.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name (Optional)	query	string	The user defined name of the resource to filter resources by.
description (Optional)	query	string	The user defined description text that can be used to filter resources.
status (Optional)	query	string	Filters by a share group status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.
share_server_id (Optional)	query	string	The UUID of the share server.
snapshot_id (Optional)	query	string	The UUID of the share’s base snapshot to filter the request based on.
host (Optional)	query	string	The host name for the back end.
share_network_id (Optional)	query	string	The UUID of the share network to filter resources by.
share_group_type_id (Optional)	query	string	The share group type ID to filter share groups.
share_group_snapshot_id (Optional)	query	string	The source share group snapshot ID to list the share group. New in version 2.31
share_types (Optional)	query	array	A list of one or more share type IDs. Allows filtering share groups.
limit (Optional)	query	integer	The maximum number of share groups members to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of shares. A valid value is `id`, `status`, `size`, `host`, `share_proto`, `export_location`, `availability_zone`, `user_id`, `project_id`, `created_at`, `updated_at`, `display_name`, `name`, `share_type_id`, `share_type`, `share_network_id`, `share_network`, `snapshot_id`, or `snapshot`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
description~ (Optional)	query	string	The description pattern that can be used to filter shares, share snapshots, share networks or share groups. New in version 2.36

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share group. New in version 2.31
links	body	string	The share group links.
name	body	string	The user defined name of the resource.
status	body	string	The share group status, which is `available`, `error`, `creating`, or `deleting`.
description	body	string	The user defined description of the resource.

Response example¶

{
    "share_groups": [
        {
            "id": "b94a8548-2079-4be0-b21c-0a887acd31ca",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "bookmark"
                }
            ],
            "name": "My_share_group"
        },
        {
            "id": "306ea93c-32e9-4907-a117-148b3945749f",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
                    "rel": "bookmark"
                }
            ],
            "name": "Test_Share_group"
        }
    ]
}

Added in version 2.31.

Lists all share groups with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name (Optional)	query	string	The user defined name of the resource to filter resources by.
description (Optional)	query	string	The user defined description text that can be used to filter resources.
status (Optional)	query	string	Filters by a share group status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.
share_server_id (Optional)	query	string	The UUID of the share server.
snapshot_id (Optional)	query	string	The UUID of the share’s base snapshot to filter the request based on.
host (Optional)	query	string	The host name for the back end.
share_network_id (Optional)	query	string	The UUID of the share network to filter resources by.
share_group_type_id (Optional)	query	string	The share group type ID to filter share groups.
share_group_snapshot_id (Optional)	query	string	The source share group snapshot ID to list the share group. New in version 2.31
share_types (Optional)	query	array	A list of one or more share type IDs. Allows filtering share groups.
limit (Optional)	query	integer	The maximum number of share groups members to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of shares. A valid value is `id`, `status`, `size`, `host`, `share_proto`, `export_location`, `availability_zone`, `user_id`, `project_id`, `created_at`, `updated_at`, `display_name`, `name`, `share_type_id`, `share_type`, `share_network_id`, `share_network`, `snapshot_id`, or `snapshot`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
description~ (Optional)	query	string	The description pattern that can be used to filter shares, share snapshots, share networks or share groups. New in version 2.36

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share group. New in version 2.31
name	body	string	The user defined name of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share group status, which is `available`, `error`, `creating`, or `deleting`.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
host	body	string	The host name for the back end.
share_group_type_id	body	string	The share group type ID.
source_share_group_snapshot_id	body	string	The source share group snapshot ID to create the share group.
share_network_id	body	string	The share network ID where the resource is exported to.
share_types	body	array	A list of share type IDs.
links	body	string	The share group links.
availability_zone	body	string	The availability zone ID that the share group exists within. New in version 2.34
consistent_snapshot_support	body	string	The consistency snapshot support. New in version 2.34

Response example¶

{
    "share_groups": [
        {
            "id": "b94a8548-2079-4be0-b21c-0a887acd31ca",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "bookmark"
                }
            ],
            "name": "My_share_group",
            "availability_zone": "nova",
            "consistent_snapshot_support": true,
            "share_group_type_id": "313df749-aac0-1a54-af52-10f6c991e80c",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "share_types": ["25747776-08e5-494f-ab40-a64b9d20d8f7"],
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "status": "available",
            "description": "My share group",
            "host": "manila2@generic1#GENERIC1",
            "source_share_group_snapshot_id": null,
            "created_at": "2015-09-18T10:25:24.000000"
        },
        {
            "id": "306ea93c-32e9-4907-a117-148b3945749f",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
                    "rel": "bookmark"
                }
            ],
            "name": "Test_Share_group",
            "availability_zone": "nova",
            "consistent_snapshot_support": true,
            "share_group_type_id": "313df749-aac0-1a54-af52-10f6c991e80c",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "share_types": ["25747776-08e5-494f-ab40-a64b9d20d8f7"],
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "status": "available",
            "description": "Test share group",
            "host": "manila2@generic1#GENERIC1",
            "source_share_group_snapshot_id": null,
            "created_at": "2015-09-18T10:25:24.000000"
        }
    ]
}

Added in version 2.31.

Shows details for a share group.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_id	path	string	The UUID of the share group.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share group. New in version 2.31
name	body	string	The user defined name of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share group status, which is `available`, `error`, `creating`, or `deleting`.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
host	body	string	The host name for the back end.
share_group_type_id	body	string	The share group type ID.
source_share_group_snapshot_id	body	string	The source share group snapshot ID to create the share group.
share_network_id	body	string	The share network ID where the resource is exported to.
share_types	body	array	A list of share type IDs.
links	body	string	The share group links.
availability_zone	body	string	The availability zone ID that the share group exists within. New in version 2.34
consistent_snapshot_support	body	string	The consistency snapshot support. New in version 2.34

Response example¶

{
    "share_groups": {
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "consistent_snapshot_support": true,
        "share_group_type_id": "313df749-aac0-1a54-af52-10f6c991e80c",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "id": "011d21e2-fbc3-4e4a-9993-9ea223f73264",
        "share_types": ["25747776-08e5-494f-ab40-a64b9d20d8f7"],
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "status": "available",
        "description": "My custom share London",
        "host": "manila2@generic1#GENERIC1",
        "source_share_group_snapshot_id": null,
        "name": "share_London",
        "created_at": "2015-09-18T10:25:24.000000"
    }
}

Added in version 2.31.

Creates a share group.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
share_types (Optional)	body	array	A list of one or more share type IDs.
share_group_type (Optional)	body	string	The share group type ID to create a share group.
share_network (Optional)	body	string	The ID of a share network that the resource must be exported to. Note that when using a share type with the `driver_handles_share_servers` extra spec as `False`, you should not provide a `share_network_id`.
source_share_group_snapshot (Optional)	body	string	The source share group snapshot ID to create the share group.
availability_zone	body	string	The availability zone ID that the share group exists within. New in version 2.34

Request example¶

{
    "share_group": {
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
        "name": "my_group",
        "description": "for_test",
        "share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "availability_zone": "nova",
        "share_network_id": "82168c2a-10bf-4013-bcc4-3d984136aee3",
        "source_share_group_snapshot_id": "69861c2a-10bf-4013-bcc4-3d020466aee3"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share group. New in version 2.31
name	body	string	The user defined name of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share group status, which is `available`, `error`, `creating`, or `deleting`.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
host (Optional)	body	string	The share group host name.
share_group_type_id	body	string	The share group type ID.
source_share_group_snapshot_id	body	string	The source share group snapshot ID to create the share group.
share_network_id	body	string	The share network ID where the resource is exported to.
share_types	body	array	A list of share type IDs.
links	body	string	The share group links.
availability_zone	body	string	The availability zone ID that the share group exists within. New in version 2.34
consistent_snapshot_support	body	string	The consistency snapshot support. New in version 2.34

Response example¶

{
    "share_groups": {
        "status": "creating",
        "description": null,
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
                "rel": "bookmark"
            }
        ],
        "availability_zone": null,
        "source_share_group_snapshot_id": null,
        "share_network_id": null,
        "share_server_id": null,
        "host": null,
        "share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "consistent_snapshot_support": null,
        "id": "f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
        "name": null,
        "created_at": "2017-08-03T19:20:33.974421",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"]
    }
}

Added in version 2.31.

Administrator only. Explicitly updates the state of a share group.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_id	path	string	The UUID of the share group.
reset_status	body	object	The `reset_status` object.
status	body	string	The share group status, which is `available`, `error`, `creating`, or `deleting`.

Request example¶

{
    "reset_status": {
        "status": "error"
    }
}

Added in version 2.31.

Updates a share group.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_id	path	string	The UUID of the share group.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.

Request example¶

{
    "share_group": {
        "name": "new name",
        "description": "Changing the share group description."
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share group. New in version 2.31
name	body	string	The user defined name of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
status	body	string	The share group status, which is `available`, `error`, `creating`, or `deleting`.
description	body	string	The user defined description of the resource.
project_id	body	string	The ID of the project that owns the resource.
host (Optional)	body	string	The share group host name.
share_group_type_id	body	string	The share group type ID.
source_share_group_snapshot_id (Optional)	body	string	The source share group snapshot ID to create the share group.
share_network_id	body	string	The share network ID where the resource is exported to.
share_types	body	array	A list of share type IDs.
links	body	string	The share group links.
availability_zone	body	string	The availability zone ID that the share group exists within. New in version 2.34
consistent_snapshot_support	body	string	The consistency snapshot support. New in version 2.34

Response example¶

{
    "share_groups": {
        "status": "creating",
        "description": "Changing the share group description.",
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
                "rel": "bookmark"
            }
        ],
        "availability_zone": null,
        "source_share_group_snapshot_id": null,
        "share_network_id": null,
        "share_server_id": null,
        "host": null,
        "share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "consistent_snapshot_support": null,
        "id": "f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
        "name": "new name",
        "created_at": "2017-08-03T19:20:33.974421",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"]
    }
}

Added in version 2.31.

Deletes a share group.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_id	path	string	The UUID of the share group.
force	body	string	To force-delete a share or share group, set this value to `null`. The force-delete action, unlike the delete action, ignores the share or share group status.

Share group types (since API v2.31)¶

A share group type enables you to filter or choose back ends before you create a share group.

You can set share group types as either public or private. By default a share group type is created as publicly accessible. Set share_group_type_access:is_public to False to make a share group type private.

You can manage access to the private share group types for different projects. You can add access, remove access, and get information about access for a private share group type.

Administrators can specify which share type(s) a given group type may contain. If Administrators do not explicitly associate share types with a given share group type, the service will associate the share type configured as the default_share_type with the share group type. When creating a share group, the scheduler picks one of the back ends that match a combination of the extra specs in the specified share type(s) and share group type.

Administrators can also set additional group extra specifications for a share group type for the following purposes:

Filter back ends by group scheduler. Specify these group extras specifications in this format: group_specs=value. For example, consistent_snapshot_support=true.

Note

Share Group Type APIs are no longer considered experimental since API version 2.55.

Added in version 2.31.

Lists all share group types.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Request¶

Name

Type

Description

project_id (Optional)

path

string

is_public (Optional)

query

boolean

A boolean query parameter that, when set to true, allows retrieving public resources that belong to all projects.

group_specs (Optional)

query

string

The group specifications as a set of one or more key-value pairs. In each pair, the key is the name of the group specification and the value is the share group type that was used to filter search share group type list. The query must be a “percent-encoded” string, for example, the following query parameters: {‘group-specs’: {‘consistent_snapshot_support’: ‘true’}} is encoded as ‘group_specs=%7B%27consistent_snapshot_support%27%3A+%27True%27%7D’

New in version 2.66

Response parameters¶

Name	In	Type	Description
id	body	string	The share group type ID.
is_public	body	boolean	The level of visibility for the share group type. Set to `true` to make share group type public. Set to `false` to make it private. Default value is `true`.
share_types	body	array	A list of share type IDs.
name	body	string	The share group type name.
group_specs	body	object	The extra specifications for the share group type.
is_default	body	boolean	Defines the share group type created is default or not. If the returning value is true, then it is the default share group type, otherwise, it is not default. New in version 2.46

Response example¶

{
    "share_group_types": [
        {
            "is_public": true,
            "group_specs": {},
            "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
            "id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
            "name": "test_group_type",
            "is_default": false
        }
    ]
}

Added in version 2.31.

Lists default share group types.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).

Response parameters¶

Name	In	Type	Description
id	body	string	The share group type ID.
is_public	body	boolean	The level of visibility for the share group type. Set to `true` to make share group type public. Set to `false` to make it private. Default value is `true`.
share_types	body	array	A list of share type IDs.
name	body	string	The share group type name.
group_specs	body	object	The extra specifications for the share group type.
is_default	body	boolean	Defines the share group type created is default or not. If the returning value is true, then it is the default share group type, otherwise, it is not default. New in version 2.46

Response example¶

{
    "share_group_type": {
        "is_public": true,
        "group_specs": {},
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
        "id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "name": "test_group_type",
        "is_default": true
    }
}

Added in version 2.31.

Lists the extra specifications for a share group type.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_type_id	body	string	The share group type ID.

Response parameters¶

Name	In	Type	Description
group_specs	body	object	The extra specifications for the share group type.

Response example¶

{
    "group_specs": {
        "snapshot_support": "True"
    }
}

Added in version 2.31.

Creates a share group type.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_types	body	array	A list of share type IDs.
name (Optional)	body	string	The name of the share group type resource. The value of this field is limited to 255 characters.
group_specs (Optional)	body	object	The extra specifications for the share group type.
is_public (Optional)	body	boolean	The level of visibility for the share group type. Set to `true` to make share group type public. Set to `false` to make it private. Default value is `false`.

Request example¶

{
    "share_group_type": {
        "is_public": true,
        "group_specs": {
            "snapshot_support": true
        },
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
        "name": "my_new_group_type"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The share group type ID.
group_specs	body	object	The extra specifications for the share group type.
name	body	string	The share group type name.
share_types	body	array	A list of share type IDs.
is_public	body	boolean	The level of visibility for the share group type. Set to `true` to make share group type public. Set to `false` to make it private. Default value is `true`.
is_default	body	boolean	Defines the share group type created is default or not. If the returning value is true, then it is the default share group type, otherwise, it is not default. New in version 2.46

Response example¶

{
    "share_group_type": {
        "is_public": true,
        "group_specs": {},
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
        "id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "name": "test_group_type",
        "is_default": false
    }
}

Added in version 2.31.

Shows access details for a share group type.

You can view access details for private share group types only.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_type_id	body	string	The share group type ID.

Response parameters¶

Name	In	Type	Description
share_group_type_id	body	string	The share group type ID.
project_id	body	string	The ID of the project that has been granted access to the type resource.

Response example¶

{
    "share_group_type_access": [
        {
            "share_group_type_id": "1732f284-401d-41d9-a494-425451e8b4b8",
            "project_id": "818a3f48dcd644909b3fa2e45a399a27"
        },
        {
            "share_group_type_id": "1732f284-401d-41d9-a494-425451e8b4b8",
            "project_id": "e1284adea3ee4d2482af5ed214f3ad90"
        }
    ]
}

Added in version 2.31.

Sets an extra specification for the share group type.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_type_id	body	string	The share group type ID.
group_specs	body	object	The extra specifications for the share group type.

Request example¶

{
    "group_specs": {
        "my_group_key": "my_group_value"
    }
}

Response parameters¶

Name	In	Type	Description
group_specs	body	object	The extra specifications for the share group type.

Response example¶

{
    "group_specs": {
        "my_group_key": "my_group_value"
    }
}

DELETE

/v2/share-group-types/{share_group_type_id}/group-specs/{group_spec_key}

Unset an group spec

Added in version 2.31.

Unsets an extra specification for the share type.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_type_id	body	string	The share group type ID.
group_spec_key	body	string	The extra specification key for the share group type.

Added in version 2.31.

Adds share group type access for a project.

You can add access to private share group types only.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_type_id	path	string	The UUID of the share group type.
addProjectAccess	body	object	An object representing the project resource that access should be granted to.
project	body	string	The ID of the project that needs to have access to the type resource.

Request example¶

{
    "addProjectAccess": {
        "project": "e1284adea3ee4d2482af5ed214f3ad90"
    }
}

Added in version 2.31.

Removes share group type access from a project.

You can remove access from private share group types only.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_type_id	path	string	The UUID of the share group type.
removeProjectAccess	body	object	An object representing the project resource that access should be revoked from.
project	body	string	The ID of the project whose access to the type resource must be revoked.

Request example¶

{
    "removeProjectAccess": {
        "project": "818a3f48dcd644909b3fa2e45a399a27"
    }
}

Added in version 2.31.

Deletes a share group type.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
share_group_type_id	path	string	The UUID of the share group type.

Share group snapshots (since API v2.31)¶

Use the Shared File Systems Service to make snapshots of share groups. A share group snapshot is a point-in-time, read-only copy of the data that is contained in a share group. You can create, update, and delete share group snapshots. After you create a share group snapshot, you can create a share group from it.

You can update a share group snapshot to rename it, change its description, or update its state.

As administrator, you can also reset the state of a group snapshot. Use the policy.yaml file to grant permissions for these actions to other roles.

Note

Share Group Snapshot APIs are no longer considered experimental since API version 2.55.

Added in version 2.31.

Lists all share group snapshots.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name (Optional)	query	string	The user defined name of the resource to filter resources by.
description (Optional)	query	string	The user defined description text that can be used to filter resources.
status (Optional)	query	string	Filters by a share group snapshot status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.
share_group_id (Optional)	query	string	The UUID of a share group to filter resource. New in version 2.31
limit (Optional)	query	integer	The maximum number of share groups members to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of shares. A valid value is `id`, `status`, `size`, `host`, `share_proto`, `export_location`, `availability_zone`, `user_id`, `project_id`, `created_at`, `updated_at`, `display_name`, `name`, `share_type_id`, `share_type`, `share_network_id`, `share_network`, `snapshot_id`, or `snapshot`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.

Response parameters¶

Name	In	Type	Description
id	body	object	The share group snapshot ID.
name	body	string	The user defined name of the resource.
links	body	string	The share group snapshot links.

Response example¶

{
    "share_group_snapshot": [
        {
            "links": [
                {
                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                    "rel": "bookmark"
                }
            ],
            "name": null,
            "id": "46bf5875-58d6-4816-948f-8828423b0b9f"
        }
    ]
}

Added in version 2.31.

Lists all share group snapshots with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
name (Optional)	query	string	The user defined name of the resource to filter resources by.
description (Optional)	query	string	The user defined description text that can be used to filter resources.
status (Optional)	query	string	Filters by a share group snapshot status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.
share_group_id (Optional)	query	string	The UUID of a share group to filter resource. New in version 2.31
limit (Optional)	query	integer	The maximum number of share groups members to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of shares. A valid value is `id`, `status`, `size`, `host`, `share_proto`, `export_location`, `availability_zone`, `user_id`, `project_id`, `created_at`, `updated_at`, `display_name`, `name`, `share_type_id`, `share_type`, `share_network_id`, `share_network`, `snapshot_id`, or `snapshot`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.

Response parameters¶

Name	In	Type	Description
id	body	object	The share group snapshot ID.
project_id	body	string	The ID of the project that owns the resource.
status	body	string	Filters by a share group snapshot status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.
share_group_id	body	string	The UUID of the share group. New in version 2.31
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
members	body	string	The share group snapshot members.
links	body	string	The share group snapshot links.

Response example¶

{
    "share_group_snapshots": [
        {
            "status": "available",
            "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
            "links": [
                {
                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                    "rel": "bookmark"
                }
            ],
            "name": null,
            "members": [],
            "created_at": "2017-08-10T03:01:39.000000",
            "project_id": "e23850eeb91d4fa3866af634223e454c",
            "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
            "description": null
        },
        {
            "status": "available",
            "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
            "links": [
                {
                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
                    "rel": "bookmark"
                }
            ],
            "name": null,
            "members": [],
            "created_at": "2017-08-10T03:01:28.000000",
            "project_id": "e23850eeb91d4fa3866af634223e454c",
            "id": "9d8ed9be-4454-4df0-b0ae-8360b623d93d",
            "description": null
        }
    ]
}

Added in version 2.31.

Lists all share group snapshots members.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
group_snapshot_id	path	string	The group snapshot ID.

Response parameters¶

Name	In	Type	Description
id	body	object	The share group snapshot ID.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
project_id	body	string	The ID of the project that owns the resource.
size	body	integer	The snapshot size, in GiBs.
share_protocol	body	string	The file system protocol of a share snapshot. A valid value is `NFS`, `CIFS`, `GlusterFS`, `HDFS`, `CephFS` or `MAPRFS`. `CephFS` is supported starting with API v2.13.
name	body	string	The user defined name of the resource.
share_group_snapshot_id	body	object	The share group snapshot ID.
share_id	body	string	The UUID of the source share that was used to create the snapshot.

Response example¶

{
    "share_group_snapshot_members": [
        {
            "status": "available",
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "created_at": "2017-09-07T11:50:39.000000",
            "share_proto": "NFS",
            "share_size": 1,
            "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
            "size": 1
        },
        {
            "status": "available",
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "created_at": "2015-09-07T11:50:39.000000",
            "share_proto": "NFS",
            "share_size": 1,
            "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
            "size": 1
        }
    ]
}

Added in version 2.31.

Shows details for a share group snapshot.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
group_snapshot_id	path	string	The group snapshot ID.

Response parameters¶

Name	In	Type	Description
id	body	object	The share group snapshot ID.
project_id	body	string	The ID of the project that owns the resource.
status	body	string	Filters by a share group snapshot status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.
share_group_id	body	string	The UUID of the share group. New in version 2.31
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
members	body	string	The share group snapshot members.
links	body	string	The share group snapshot links.

Response example¶

{
    "share_group_snapshot": {
        "status": "creating",
        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "bookmark"
            }
        ],
        "name": null,
        "members": [],
        "created_at": "2017-08-10T03:01:39.442509",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
        "description": null
    }
}

Added in version 2.31.

Creates a snapshot from a share.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
share_group_id	body	string	The UUID of the share group. New in version 2.31

Request example¶

{
    "share_group_snapshot": {
        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
        "name": "test",
        "description": "test description"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	object	The share group snapshot ID.
project_id	body	string	The ID of the project that owns the resource.
status	body	string	Filters by a share group snapshot status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.
share_group_id	body	string	The UUID of the share group. New in version 2.31
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
members	body	string	The share group snapshot members.
links	body	string	The share group snapshot links.

Response example¶

{
    "share_group_snapshot": {
        "status": "creating",
        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "bookmark"
            }
        ],
        "name": null,
        "members": [],
        "created_at": "2017-08-10T03:01:39.442509",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
        "description": null
    }
}

Added in version 2.31.

Administrator only. Explicitly updates the state of a share group snapshot.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
group_snapshot_id	path	string	The group snapshot ID.
status	body	string	Filters by a share group snapshot status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.

Request example¶

{
    "reset_status": {
        "status": "error"
    }
}

Added in version 2.31.

Updates a share group snapshot.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
group_snapshot_id	path	string	The group snapshot ID.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.

Request example¶

{
    "snapshot": {
        "display_name": "snapshot_Share1",
        "display_description": "I am changing a description also. Here is a snapshot of share Share1"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	object	The share group snapshot ID.
project_id	body	string	The ID of the project that owns the resource.
status	body	string	Filters by a share group snapshot status. A valid value is `creating`, `error`, `available`, `deleting`, `error_deleting`.
share_group_id	body	string	The UUID of the share group. New in version 2.31
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
members	body	string	The share group snapshot members.
links	body	string	The share group snapshot links.

Response example¶

{
    "share_group_snapshot": {
        "status": "creating",
        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "bookmark"
            }
        ],
        "name": null,
        "members": [],
        "created_at": "2017-08-10T03:01:39.442509",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
        "description": null
    }
}

Added in version 2.31.

Deletes a share group snapshot.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
group_snapshot_id	path	string	The group snapshot ID.

Share transfer (since API v2.77)¶

Transfers a share across projects.

Initiates a share transfer from a source project namespace to a destination project namespace.

Preconditions

The share status must be available
If the share has snapshots, those snapshots must be available
The share can not belong to share group

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
transfer	body	object	The transfer object.
name (Optional)	body	string	The transfer display name.
share_id	body	string	The UUID of the share.

Request Example¶

{
    "transfer": {
        "share_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
        "name": "test_transfer"
    }
}

Response Parameters¶

Name	In	Type	Description
id	body	string	The transfer UUID.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
name (Optional)	body	string	The transfer display name.
resource_type	body	string	The type of the resource for the transfer.
resource_id	body	string	The UUID of the resource for the transfer.
auth_key	body	string	The authentication key for the transfer.
source_project_id	body	string	The ID of the project that owns the resource.
destination_project_id	body	string	UUID of the destination project to accept transfer resource.
accepted	body	boolean	Whether the transfer has been accepted.
expires_at	body	string	The date and time stamp when the resource transfer will expire. After transfer expired, will be automatically deleted. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
links	body	array	Pagination and bookmark links for the resource.

Response Example¶

{
    "transfer": {
        "id": "f21c72c4-2b77-445b-aa12-e8d1b44163a2",
        "created_at": "2022-09-06T08:17:43.629495",
        "name": "test_transfer",
        "resource_type": "share",
        "resource_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
        "auth_key": "406a2d67cdb09afe",
        "source_project_id": "714198c7ac5e45a4b785de732ea4695d",
        "destination_project_id": null,
        "accepted": false,
        "expires_at": "2022-09-06T08:22:43.629495",
        "links": [
            {
                "rel": "self",
                "href": "http://192.168.48.129/shar/v2/share-transfer/f21c72c4-2b77-445b-aa12-e8d1b44163a2"
            },
            {
                "rel": "bookmark",
                "href": "http://192.168.48.129/shar/share-transfer/f21c72c4-2b77-445b-aa12-e8d1b44163a2"
            }
        ]
    }
}

Accepts a share transfer.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`413 - Request Entity Too Large`	This operation cannot be completed.

Request¶

Name	In	Type	Description
transfer_id	path	string	The unique identifier for a transfer.
auth_key	body	string	The authentication key for the transfer.
clear_access_rules (Optional)	body	boolean	Whether clear all access rules when accept share.

Request Example¶

{
    "accept": {
        "auth_key": "d7ef426932068a33",
        "clear_access_rules": true
    }
}

Lists share transfers.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Request¶

Name	In	Type	Description
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
limit (Optional)	query	integer	The maximum number of share groups members to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of transfers. A valid value is `id`, `name`, `resource_type`, `resource_id`, `source_project_id`, `destination_project_id`, `created_at`, `expires_at`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.
name (Optional)	query	string	The user defined name of the resource to filter resources by.
name~ (Optional)	query	string	The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups. New in version 2.36
resource_type (Optional)	query	string	The type of the resource for which the transfer was created.

Response Parameters¶

Name	In	Type	Description
transfers	body	array	List of transfers.
id	body	string	The transfer UUID.
resource_type	body	string	The type of the resource for the transfer.
resource_id	body	string	The UUID of the resource for the transfer.
name (Optional)	body	string	The transfer display name.
links	body	array	Pagination and bookmark links for the resource.

Response Example¶

{
    "transfers": [
        {
            "id": "02a948b4-671b-4c62-b13a-18d613cb4576",
            "resource_type": "share",
            "resource_id": "0fe7cf64-b879-4902-9d86-f80aeff12b06",
            "name": "transfer2",
            "links": [
                {
                    "rel": "self",
                    "href": "http://192.168.48.129/shar/v2/share-transfer/02a948b4-671b-4c62-b13a-18d613cb4576"
                },
                {
                    "rel": "bookmark",
                    "href": "http://192.168.48.129/shar/share-transfer/02a948b4-671b-4c62-b13a-18d613cb4576"
                }
            ]
        },
        {
            "id": "a10209ff-b55d-4fed-9f63-abea53b6f107",
            "resource_type": "share",
            "resource_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
            "name": "transfer1",
            "links": [
                {
                    "rel": "self",
                    "href": "http://192.168.48.129/shar/v2/share-transfer/a10209ff-b55d-4fed-9f63-abea53b6f107"
                },
                {
                    "rel": "bookmark",
                    "href": "http://192.168.48.129/shar/share-transfer/a10209ff-b55d-4fed-9f63-abea53b6f107"
                }
            ]
        }
    ]
}

Lists share transfers, with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Request¶

Name	In	Type	Description
all_tenants (Optional)	query	boolean	(Admin only). Defines whether to list the requested resources for all projects. Set to `1` to list resources for all projects. Set to `0` to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.
limit (Optional)	query	integer	The maximum number of share groups members to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of transfers. A valid value is `id`, `name`, `resource_type`, `resource_id`, `source_project_id`, `destination_project_id`, `created_at`, `expires_at`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.

Response Parameters¶

Name	In	Type	Description
transfers	body	array	List of transfers.
id	body	string	The transfer UUID.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
name (Optional)	body	string	The transfer display name.
resource_type	body	string	The type of the resource for the transfer.
resource_id	body	string	The UUID of the resource for the transfer.
source_project_id	body	string	The ID of the project that owns the resource.
destination_project_id	body	string	UUID of the destination project to accept transfer resource.
accepted	body	boolean	Whether the transfer has been accepted.
expires_at	body	string	The date and time stamp when the resource transfer will expire. After transfer expired, will be automatically deleted. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
links	body	array	Pagination and bookmark links for the resource.

Response Example¶

{
    "transfers": [
        {
            "id": "42b0fab4-df77-4f25-a958-5370e1c95ed2",
            "created_at": "2022-09-07T01:52:39.000000",
            "name": "transfer2",
            "resource_type": "share",
            "resource_id": "0fe7cf64-b879-4902-9d86-f80aeff12b06",
            "source_project_id": "714198c7ac5e45a4b785de732ea4695d",
            "destination_project_id": null,
            "accepted": false,
            "expires_at": "2022-09-07T01:57:39.000000",
            "links": [
                {
                    "rel": "self",
                    "href": "http://192.168.48.129/shar/v2/share-transfer/42b0fab4-df77-4f25-a958-5370e1c95ed2"
                },
                {
                    "rel": "bookmark",
                    "href": "http://192.168.48.129/shar/share-transfer/42b0fab4-df77-4f25-a958-5370e1c95ed2"
                }
            ]
        },
        {
            "id": "506a7e77-42e7-4f33-ac36-1d1dd7f2b9af",
            "created_at": "2022-09-07T01:52:30.000000",
            "name": "transfer1",
            "resource_type": "share",
            "resource_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
            "source_project_id": "714198c7ac5e45a4b785de732ea4695d",
            "destination_project_id": null,
            "accepted": false,
            "expires_at": "2022-09-07T01:57:30.000000",
            "links": [
                {
                    "rel": "self",
                    "href": "http://192.168.48.129/shar/v2/share-transfer/506a7e77-42e7-4f33-ac36-1d1dd7f2b9af"
                },
                {
                    "rel": "bookmark",
                    "href": "http://192.168.48.129/shar/share-transfer/506a7e77-42e7-4f33-ac36-1d1dd7f2b9af"
                }
            ]
        }
    ]
}

Shows details for a share transfer.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
transfer_id	path	string	The unique identifier for a transfer.

Response Parameters¶

Name	In	Type	Description
id	body	string	The transfer UUID.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
name (Optional)	body	string	The transfer display name.
resource_type	body	string	The type of the resource for the transfer.
resource_id	body	string	The UUID of the resource for the transfer.
source_project_id	body	string	The ID of the project that owns the resource.
destination_project_id	body	string	UUID of the destination project to accept transfer resource.
accepted	body	boolean	Whether the transfer has been accepted.
expires_at	body	string	The date and time stamp when the resource transfer will expire. After transfer expired, will be automatically deleted. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
links	body	array	Pagination and bookmark links for the resource.

Response Example¶

{
    "transfer": {
        "id": "d2035732-d0c0-4380-a44c-f978a264ab1a",
        "created_at": "2022-09-07T01:12:29.000000",
        "name": "transfer1",
        "resource_type": "share",
        "resource_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
        "source_project_id": "714198c7ac5e45a4b785de732ea4695d",
        "destination_project_id": null,
        "accepted": false,
        "expires_at": "2022-09-07T01:17:29.000000",
        "links": [
            {
                "rel": "self",
                "href": "http://192.168.48.129/shar/v2/share-transfer/d2035732-d0c0-4380-a44c-f978a264ab1a"
            },
            {
                "rel": "bookmark",
                "href": "http://192.168.48.129/shar/share-transfer/d2035732-d0c0-4380-a44c-f978a264ab1a"
            }
        ]
    }
}

Deletes a share transfer.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Request¶

Name	In	Type	Description
transfer_id	path	string	The unique identifier for a transfer.

Resource Locks (since API v2.81)¶

Create, list, update and delete locks on user actions on resources.

POST

/v2/resource-locks

Create a resource lock

Added in version 2.81.

Lock a specific action on a given resource.

Not all resources are supported, and not actions on supported resources can be prevented with this mechanism. A lock can only be removed or manipulated by the user that created it, or by a more privileged user. The cloud administrator can use a policy.yaml file to tweak permissions on who can manipulate and delete locks created by other users.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
service_token (Optional)	header	string	An auth-token specified via the header `X-Service-Token`. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the `service` role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.
resource_lock	body	object	A resource lock object when making resource lock requests. All other parameters are included in this object.
resource_id	body	string	The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.
resource_type	body	string	The type of resource that the ID in `resource_id` denotes. For example, `share` is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for `share`.
resource_action (Optional)	body	string	The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of `resource_action` is `delete`. Resource locks are not supported for all API actions. Currently support only exists for `delete`, and for specific resources. If not provided, the value of this parameter defaults to `delete`.
lock_reason (Optional)	body	string	A blob of text representing the reason for the specific resource lock.

Request Example¶

{
    "resource_lock": {
        "resource_id": "5a313549-d346-44b6-9650-738ce08a9fee",
        "resource_type": "share",
        "resource_action": "delete",
        "lock_reason": "Locked for deletion until year end audit."
    }
}

Response Parameters¶

Name	In	Type	Description
resource_lock	body	object	A resource lock object when making resource lock requests. All other parameters are included in this object.
id	body	string	The UUID identifying the specific resource lock.
user_id	body	string	The ID of the user the resource lock was created for.
project_id	body	string	The ID of the project that the resource lock was created for.
lock_context	body	string	The lock creator’s context. Resource locks can be created by users with different roles. If a user with `admin` role creates the lock, the value of this field is `admin`. If a user with `service` role creates the lock, the value of this field is `service`. For all other contexts, the value of this field is `user`. This field also determines the user’s role that is required to unlock or manipulate a lock by virtue of the service’s default RBAC.
resource_type	body	string	The type of resource that the ID in `resource_id` denotes. For example, `share` is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for `share`.
resource_id	body	string	The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.
resource_action	body	string	The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of `resource_action` is `delete`. Resource locks are not supported for all API actions.
lock_reason	body	string	A blob of text representing the reason for the specific resource lock.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
links	body	array	Pagination and bookmark links for the resource.

Response Example¶

{
  "resource_lock": {
    "id": "713dc92d-bf5e-4b04-875b-2b2d284d8f94",
    "user_id": "89de351d3b5744b9853ec4829aa0e714",
    "project_id": "db2e72fef7864bbbbf210f22da7f1158",
    "lock_context": "user",
    "resource_type": "share",
    "resource_id": "5a313549-d346-44b6-9650-738ce08a9fee",
    "resource_action": "delete",
    "lock_reason": "Locked for deletion until year end audit.",
    "created_at": "2023-07-17T22:11:48.144302",
    "updated_at": null,
    "links": [
      {
        "rel": "self",
        "href": "http://203.0.113.30/share/v2/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
      },
      {
        "rel": "bookmark",
        "href": "http://203.0.113.30/share/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
      }
    ]
  }
}

GET

/v2/resource-locks

List resource locks

Added in version 2.81.

Retrieve resource locks with filters

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
service_token (Optional)	header	string	An auth-token specified via the header `X-Service-Token`. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the `service` role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.
id (Optional)	query	string	The ID of the resource lock to filter resource locks by.
resource_id (Optional)	query	string	The ID of the resource that the locks pertain to to filter resource locks by.
resource_action (Optional)	query	string	The `action` prevented by the filtered resource locks.
resource_type (Optional)	query	string	The type of the resource that the locks pertain to to filter resource locks by.
user_id (Optional)	query	string	The ID of a user to filter resource locks by.
project_id (Optional)	query	string	The ID of a project to filter resource locks by.
all_projects (Optional)	query	string	Set this parameter to True to get resource locks across all project namespaces.
lock_context (Optional)	query	string	The lock creator’s context to filter locks by.
created_since (Optional)	query	string	Search for the list of resources that were created after the specified date. The date is in ‘yyyy-mm-dd’ format.
created_before (Optional)	query	string	Search for the list of resources that were created prior to the specified date. The date is in ‘yyyy-mm-dd’ format.
lock_reason (Optional)	query	string	The lock reason that can be used to filter resource locks.
lock_reason~ (Optional)	query	string	The lock reason pattern that can be used to filter resource locks.
sort_key (Optional)	query	string	The key to sort a list of resource locks. A valid value is `id`, `resource_id`, `resource_type`, `resource_action`, `user_id`, `project_id`, `created_at`, `updated_act`, `lock_context`.
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.
offset (Optional)	query	integer	The offset to define start point of resource listing.
with_count (Optional)	query	boolean	Whether to show `count` in API response or not, default is `False`. This query parameter is useful with pagination.

Response Parameters¶

Name	In	Type	Description
resource_locks	body	object	A resource locks object containing a collection or list of resource locks.
id	body	string	The UUID identifying the specific resource lock.
user_id	body	string	The ID of the user the resource lock was created for.
project_id	body	string	The ID of the project that the resource lock was created for.
lock_context	body	string	The lock creator’s context. Resource locks can be created by users with different roles. If a user with `admin` role creates the lock, the value of this field is `admin`. If a user with `service` role creates the lock, the value of this field is `service`. For all other contexts, the value of this field is `user`. This field also determines the user’s role that is required to unlock or manipulate a lock by virtue of the service’s default RBAC.
resource_type	body	string	The type of resource that the ID in `resource_id` denotes. For example, `share` is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for `share`.
resource_id	body	string	The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.
resource_action	body	string	The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of `resource_action` is `delete`. Resource locks are not supported for all API actions.
lock_reason	body	string	A blob of text representing the reason for the specific resource lock.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
links	body	array	Pagination and bookmark links for the resource.
count (Optional)	body	integer	The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query.

Response Example¶

{
  "resource_locks": [
    {
      "id": "118750ee-b62b-4cae-9a94-7da29a4f831f",
      "user_id": "89de351d3b5744b9853ec4829aa0e714",
      "project_id": "db2e72fef7864bbbbf210f22da7f1158",
      "lock_context": "user",
      "resource_type": "share",
      "resource_id": "4c0b4d35-4ea8-4811-a1e2-a065c64225a8",
      "resource_action": "delete",
      "lock_reason": null,
      "created_at": "2023-07-17T22:53:18.894553",
      "updated_at": null,
      "links": [
        {
          "rel": "self",
          "href": "http://203.0.113.30/share/v2/resource_locks/118750ee-b62b-4cae-9a94-7da29a4f831f"
        },
        {
          "rel": "bookmark",
          "href": "http://203.0.113.30/share/resource_locks/118750ee-b62b-4cae-9a94-7da29a4f831f"
        }
      ]
    },
    {
      "id": "713dc92d-bf5e-4b04-875b-2b2d284d8f94",
      "user_id": "89de351d3b5744b9853ec4829aa0e714",
      "project_id": "db2e72fef7864bbbbf210f22da7f1158",
      "lock_context": "user",
      "resource_type": "share",
      "resource_id": "5a313549-d346-44b6-9650-738ce08a9fee",
      "resource_action": "delete",
      "lock_reason": "Locked for deletion until year end audit.",
      "created_at": "2023-07-17T22:11:48.144302",
      "updated_at": null,
      "links": [
        {
          "rel": "self",
          "href": "http://203.0.113.30/share/v2/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
        },
        {
          "rel": "bookmark",
          "href": "http://203.0.113.30/share/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
        }
      ]
    }
  ]
}

GET

/v2/resource-locks/{resource-lock-id}

Get a resource lock

Added in version 2.81.

Retrieve a specific resource lock

By default, resource locks can be viewed by all users within a project that owns the locks. The cloud administrator can use a policy.yaml file to tweak this behavior.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
service_token (Optional)	header	string	An auth-token specified via the header `X-Service-Token`. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the `service` role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.
resource_lock_id	path	string	The UUID of the resource lock.

Response Parameters¶

Name	In	Type	Description
resource_lock	body	object	A resource lock object when making resource lock requests. All other parameters are included in this object.
id	body	string	The UUID identifying the specific resource lock.
user_id	body	string	The ID of the user the resource lock was created for.
project_id	body	string	The ID of the project that the resource lock was created for.
lock_context	body	string	The lock creator’s context. Resource locks can be created by users with different roles. If a user with `admin` role creates the lock, the value of this field is `admin`. If a user with `service` role creates the lock, the value of this field is `service`. For all other contexts, the value of this field is `user`. This field also determines the user’s role that is required to unlock or manipulate a lock by virtue of the service’s default RBAC.
resource_type	body	string	The type of resource that the ID in `resource_id` denotes. For example, `share` is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for `share`.
resource_id	body	string	The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.
resource_action	body	string	The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of `resource_action` is `delete`. Resource locks are not supported for all API actions.
lock_reason	body	string	A blob of text representing the reason for the specific resource lock.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
links	body	array	Pagination and bookmark links for the resource.

Response Example¶

{
  "resource_lock": {
    "id": "713dc92d-bf5e-4b04-875b-2b2d284d8f94",
    "user_id": "89de351d3b5744b9853ec4829aa0e714",
    "project_id": "db2e72fef7864bbbbf210f22da7f1158",
    "lock_context": "user",
    "resource_type": "share",
    "resource_id": "5a313549-d346-44b6-9650-738ce08a9fee",
    "resource_action": "delete",
    "lock_reason": "Locked for deletion until year end audit.",
    "created_at": "2023-07-17T22:11:48.144302",
    "updated_at": null,
    "links": [
      {
        "rel": "self",
        "href": "http://203.0.113.30/share/v2/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
      },
      {
        "rel": "bookmark",
        "href": "http://203.0.113.30/share/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
      }
    ]
  }
}

PUT

/v2/resource-locks/{resource-lock-id}

Update a resource lock

Added in version 2.81.

Update a specific resource lock

By default, resource locks can be updated by the user that created the lock unless the lock_context is set to admin or service. A user with service role is required to manipulate locks that have a lock_context set to service. Users with admin role can manipulate all locks. Administrators can use policy.yaml to tweak this behavior.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
service_token (Optional)	header	string	An auth-token specified via the header `X-Service-Token`. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the `service` role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.
resource_lock_id	path	string	The UUID of the resource lock.
resource_lock	body	object	A resource lock object when making resource lock requests. All other parameters are included in this object.
resource_action (Optional)	body	string	The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of `resource_action` is `delete`. Resource locks are not supported for all API actions.
lock_reason (Optional)	body	string	A blob of text representing the reason for the specific resource lock.

Request Example¶

{
    "resource_lock": {
        "lock_reason": "This is a protected share"
    }
}

Response Parameters¶

Name	In	Type	Description
resource_lock	body	object	A resource lock object when making resource lock requests. All other parameters are included in this object.
id	body	string	The UUID identifying the specific resource lock.
user_id	body	string	The ID of the user the resource lock was created for.
project_id	body	string	The ID of the project that the resource lock was created for.
lock_context	body	string	The lock creator’s context. Resource locks can be created by users with different roles. If a user with `admin` role creates the lock, the value of this field is `admin`. If a user with `service` role creates the lock, the value of this field is `service`. For all other contexts, the value of this field is `user`. This field also determines the user’s role that is required to unlock or manipulate a lock by virtue of the service’s default RBAC.
resource_type	body	string	The type of resource that the ID in `resource_id` denotes. For example, `share` is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for `share`.
resource_id	body	string	The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.
resource_action	body	string	The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of `resource_action` is `delete`. Resource locks are not supported for all API actions.
lock_reason	body	string	A blob of text representing the reason for the specific resource lock.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
links	body	array	Pagination and bookmark links for the resource.

Response Example¶

{
  "resource_lock": {
    "id": "118750ee-b62b-4cae-9a94-7da29a4f831f",
    "user_id": "89de351d3b5744b9853ec4829aa0e714",
    "project_id": "db2e72fef7864bbbbf210f22da7f1158",
    "lock_context": "user",
    "resource_type": "share",
    "resource_id": "4c0b4d35-4ea8-4811-a1e2-a065c64225a8",
    "resource_action": "delete",
    "lock_reason": "This is a protected share",
    "created_at": "2023-07-17T22:53:18.894553",
    "updated_at": "2023-07-17T23:18:44.284565",
    "links": [
      {
        "rel": "self",
        "href": "http://203.0.113.30/share/v2/resource_locks/118750ee-b62b-4cae-9a94-7da29a4f831f"
      },
      {
        "rel": "bookmark",
        "href": "http://203.0.113.30/share/resource_locks/118750ee-b62b-4cae-9a94-7da29a4f831f"
      }
    ]
  }
}

DELETE

/v2/resource-locks/{resource-lock-id}

Delete a resource lock

Added in version 2.81.

Delete a specific resource lock

By default, resource locks can be deleted by the user that created the lock unless the lock_context is set to admin or service. A user with service role is required to delete locks that have a lock_context set to service. Users with admin role can delete any lock. Administrators can use policy.yaml to tweak this behavior.

This request provides no response body.

Response codes¶

Success¶

Code	Reason
`204 - No Content`	Request fulfilled but service does not return anything.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
service_token (Optional)	header	string	An auth-token specified via the header `X-Service-Token`. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the `service` role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.
resource_lock_id	path	string	The UUID of the resource lock.

Shared File Systems API (EXPERIMENTAL)¶

Experimental APIs¶

Important

The following APIs are part of the experimental feature introduced in version 2.4. The APIs may change or be removed in future versions of the Shared File Systems API. All experimental APIs require the X-OpenStack-Manila-API-Experimental: True header to be sent in the requests.

Share Migration (since API v2.22)¶

The Share Migration API is an administrator-only experimental API that allows the invoker to select a destination pool to migrate a share to, while still allowing clients to access the source “share instance” during migration.

Share migration is implemented in a 2-phase approach. The first phase of migration is when operations that take the longest are performed, such as data copying or replication. After first phase of data copying is complete, it is up to administrator to trigger the second phase, often referred to as switchover phase, which may perform operations such as final sync and deleting the source share instance.

During the data copy phase, user can remain connected to the source, and may have to reconnect after the switchover phase. In order to migrate a share, manila may employ one of two mechanisms which are driver-assisted migration and host-assisted migration.

Driver-assisted migration: This mechanism is intended to make use of driver
optimizations to migrate shares between pools of the same storage vendor. This mechanism allows migrating shares nondisruptively while the source remains writable, preserving all filesystem metadata and snapshots. The migration workload is performed in the storage back end.
Host-assisted migration: This mechanism is intended to migrate
shares in an agnostic manner between two different pools, regardless of storage vendor. The implementation for this mechanism does not offer the same properties found in driver-assisted migration. In host-assisted migration, the source remains readable, snapshots must be deleted prior to starting the migration, filesystem metadata may be lost, and the clients will get disconnected by the end of migration. The migration workload is performed by the Data Service, which is a dedicated manila service for intensive data operations.

These methods provide different capabilities and affect how efficiently the data copy and switchover are achieved. Generally speaking, driver-assisted migration is limited to homogenous storage backends and when available, is expected to be faster and more efficient than host-assisted migration. Driver-assisted migration occurs on the storage backend, while host-assisted migration occurs on the OpenStack nodes running the manila data service.

When starting a migration, driver-assisted migration is attempted first. If the shared file system service detects it is not possible to perform the driver-assisted migration, it proceeds to attempt host-assisted migration.

Possible use cases for data migration include:

Migrating shares along with snapshots.

Bring down a physical storage device for maintenance

Free up space in a thinly-provisioned back end.

Load balancing among share servers.

Retyping a share

Note

Share Migration APIs are experimental APIs .

POST

/v2/shares/{share_id}/action

Start Migration

Added in version 2.22.

Initiates share migration. This API will initiate the share data copy to the new host. The copy operation is non-disruptive.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id	body	string	The ID of the project that owns the resource.
share_id	path	string	The UUID of the share.
force_host_assisted_migration (Optional)	body	boolean	Forces the host-assisted mechanism to be used, thus using the Data Service to copy data across back ends. This parameter value defaults to `False`. When set to `True`, it skips the driver-assisted approach which would otherwise be attempted first. If this option is set to `True`, all driver-assisted options must be set to `False`.
preserve_snapshots	body	boolean	Specifies whether migration should enforce the preservation of all existing snapshots at the destination. When set to `True` and drivers are not capable of migrating the snapshots, migration will result in an error status. As of Ocata release, host-assisted migration cannot provide this capability.
preserve_metadata	body	boolean	Specifies whether migration should enforce the preservation of all file system metadata. When set to `True` and drivers are not capable of ensuring preservation of file system metadata, migration will result in an error status. As of Ocata release, host-assisted migration cannot provide any guarantees of preserving file system metadata.
nondisruptive	body	boolean	Specifies whether migration should only be performed without disrupting clients during migration. For such, it is also expected that the export location does not change. When set to `True` and drivers are not capable of allowing the share to remain accessible through the two phases of the migration, migration will result in an error status. As of Ocata release, host-assisted migration cannot provide this capability.
writable	body	boolean	Specifies whether migration should only be performed if the share can remain writable. When this behavior is set to `True` and drivers are not capable of allowing the share to remain writable, migration will result in an error status. If drivers are not capable of performing a nondisruptive migration, manila will ensure that the share will remain writable through the data copy phase of migration. However, during the switchover phase the share will be re-exported at the destination, causing the share to be rendered inaccessible for the duration of this phase. As of Ocata release, host-assisted migration cannot provide this capability.
new_share_type_id (Optional)	body	string	If willing to retype the share so it can be allocated in the desired destination pool, the invoker may supply a new share type to be used. This is often suited when the share is to be migrated to a pool which operates in the opposite driver mode.
new_share_network_id (Optional)	body	string	If willing to change the share’s share-network so it can be allocated in the desired destination pool, the invoker may supply a new share network to be used. This is often suited when the share is to be migrated to a pool which operates in a different availability zone or managed by a driver that handles share servers.
host	body	string	The target pool to which the share should be migrated to, in format `host@backend#pool`. E.g. `ubuntu@generic1#GENERIC1`.

Request example¶

{
    "migration_start":
        {
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "writable": true,
            "preserve_snapshots": true,
            "preserve_metadata": true,
            "nondisruptive": true,
            "host": "ubuntu@generic2#GENERIC2",
            "new_share_type_id": "foo_share_type_id",
            "new_share_network_id": "bar_share_network_id",
            "force_host_assisted_migration": false
        }
}

POST

/v2/shares/{share_id}/action

Complete Migration

Added in version 2.22.

Completes share migration. This API will initiate the switch-over from the source to destination share. This operation can be disruptive.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id	body	string	The ID of the project that owns the resource.
share_id	path	string	The UUID of the share.

Request example¶

{
    "migration_complete":
        {
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
        }
}

POST

/v2/shares/{share_id}/action

Migration Get Process

Added in version 2.22.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
share_id	path	string	The UUID of the share.
project_id	body	string	The ID of the project that owns the resource.

Response parameters¶

Name

Type

Description

details

body

object

Additional driver specific details of the migration progress.

New in version 2.59

total_progress

body

integer

Defines a total progress of share migration.

task_state

body

string

For the share migration, the migration task state. A valid value is null, migration_starting, migration_error, migration_success, migration_completing, or migrating. The task_state is null unless the share is migrated from one back-end to another.

New in version 2.5

Request example¶

{
    "migration_get_process":
        {
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
        }
}

Response_parameters¶

{
    "total_progress": 100,
    "task_state": "migration_driver_phase1_done"
}

POST

/v2/shares/{share_id}/action

Cancel Migration

Added in version 2.22.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
share_id	path	string	The UUID of the share.
project_id	body	string	The ID of the project that owns the resource.

Request example¶

{
    "migration_cancel":
        {
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
        }
}

Share Server Migration (since API v2.57)¶

The Share Server Migration API is an administrator-only experimental API that allows the invoker to select a destination backend to migrate a share server to.

Share server migration uses a 2-phased approach. In the first phase of the migration, the data copying or replication operations are performed, so it’s the longer phase. After the first phase is finished, the administrator can trigger the second phase, which consists in final syncs and making the new share server available to be used and the latter one inactive.

During the data copy phase, source shares will remain available and writable if it was required by the administrator and supported by the share driver. After the second phase, users may need to reconnect to the shares affected by the migration. All shares belonging to a share server are migrated and their access rules are preserved through the migration. The share snapshots are going to be copied if specified by the administrator and/or supported by the driver.

Important

In order to migrate a share server, the administrator must make sure that none of the shares on the server are replicated or in a share group.

Note

Share Server Migration APIs are experimental APIs .

Possible uses for share server migration include:

Migrating a share server and all its shares and snapshots at once.

Bring down a physical storage device for maintenance.

Free up space in a thinly-provisioned back end.

Load balancing among backends.

Added in version 2.57.

Checks if a share driver can handle a share server migration according to the specified destination host and new_share_network_id, as well as the writable, nondisruptive and preserve_snapshots flags.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id	body	string	The ID of the project that owns the resource.
share_server_id	body	string	The UUID of the share server.
preserve_snapshots	body	boolean	Specifies whether migration should enforce the preservation of all existing snapshots at the destination. When set to `True` and drivers are not capable of migrating the snapshots, migration will result in an error status.
nondisruptive	body	boolean	Specifies whether share server migration should only be performed without disrupting clients during migration. For such, it is also expected that the export location does not change. When set to `True` and drivers are not capable of allowing the share server to remain accessible through the two phases of the migration, migration will result in an error status.
writable	body	boolean	Specifies whether migration should only be performed if the shares can remain writable. When this behavior is set to `True` and drivers are not capable of allowing the shares to remain writable, migration will result in an error status. If drivers are not capable of performing a nondisruptive migration, manila will ensure that the shares will remain writable through the data copy phase of migration. However, during the switchover phase all shares will be re-exported at the destination, causing the shares to be rendered inaccessible for the duration of this phase.
new_share_network_id (Optional)	body	string	If willing to change the share server’s share-network so it can be allocated in the desired destination backend, the invoker may supply a new share network to be used.
host	body	string	The target backend to which the share server should be migrated to, in format `host@backend`. E.g. `ubuntu@generic1`.

Response parameters¶

Name	In	Type	Description
compatible	body	boolean	Whether the destination backend can or can’t handle the share server migration considering the received entries for `share_network_id`, `host`, `nondisruptive`, `writable` and `preserve_snapshots` matched with the driver supported capabilities.
requested_capabilities	body	object	The parameters that were sent to the server in order to check if the destination host can handle the share server migration. This object contains the following attributes: `writable`, `nondisruptive`, `preserve_snapshots`, `share_network_id` and `host`.
supported_capabilities	body	object	The driver’s supported attributes for a share server migration. It will contain the following items: `writable`, `nondisruptive`, `preserve_snapshots` and `share_network_id`. Drivers will also report if they can perform `migration_cancel` and `migration_get_progress` operations. All of the mentioned parameters will be present in this object. All parameters but the `share_network_id` are boolean values.

Request example¶

{
    "migration_check": {
        "host": "foohost2@backend2",
        "preserve_snapshots": "True",
        "writable": "True",
        "nondisruptive": "True",
        "new_share_network_id": null
    }
}

Response example¶

{
    "compatible": false,
    "requested_capabilities": {
        "writable": "True",
        "nondisruptive": "True",
        "preserve_snapshots": "True",
        "share_network_id": null,
        "host": "foohost2@backend2"
    },
    "supported_capabilities": {
        "writable": true,
        "nondisruptive": false,
        "preserve_snapshots": true,
        "share_network_id": "1d04b755-649f-46a4-964c-be9f0395af13",
        "migration_cancel": true,
        "migration_get_progress": true
    }
}

Added in version 2.57.

Triggers a share server migration. This API will initiate the first phase of the share server migration to a new host.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
project_id	body	string	The ID of the project that owns the resource.
share_server_id	body	string	The UUID of the share server.
preserve_snapshots	body	boolean	Specifies whether migration should enforce the preservation of all existing snapshots at the destination. When set to `True` and drivers are not capable of migrating the snapshots, migration will result in an error status.
nondisruptive	body	boolean	Specifies whether share server migration should only be performed without disrupting clients during migration. For such, it is also expected that the export location does not change. When set to `True` and drivers are not capable of allowing the share server to remain accessible through the two phases of the migration, migration will result in an error status.
writable	body	boolean	Specifies whether migration should only be performed if the shares can remain writable. When this behavior is set to `True` and drivers are not capable of allowing the shares to remain writable, migration will result in an error status. If drivers are not capable of performing a nondisruptive migration, manila will ensure that the shares will remain writable through the data copy phase of migration. However, during the switchover phase all shares will be re-exported at the destination, causing the shares to be rendered inaccessible for the duration of this phase.
new_share_network_id (Optional)	body	string	If willing to change the share server’s share-network so it can be allocated in the desired destination backend, the invoker may supply a new share network to be used.
host	body	string	The target backend to which the share server should be migrated to, in format `host@backend`. E.g. `ubuntu@generic1`.

Request example¶

{
    "migration_start": {
        "host": "foohost2@backend2",
        "preserve_snapshots": "True",
        "writable": "True",
        "nondisruptive": "False",
        "new_share_network_id": null
    }
}

Added in version 2.57.

Completes share server migration. This API will initiate the switch-over from the source to destination share server. This operation can be disruptive.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id	body	string	The ID of the project that owns the resource.
share_server_id	body	string	The UUID of the share server.

Response parameters¶

Name	In	Type	Description
total_progress	body	integer	Defines a total progress of share server migration.
task_state	body	string	For the share server migration, the migration task state. A valid value is `null`, `migration_in_progress`, `migration_cancel_in_progress`, `migration_cancelled`, `migration_driver_starting`, `migration_driver_in_progress`, or `migration_phase_1_done`.
destination_share_server_id	body	string	UUID of the share server that was created in the destination backend during a share server migration operation.

Request example¶

{
    "migration_complete": null
}

Response example¶

{
    "destination_share_server_id": "c2f71561-85e2-4ccb-a91a-e44f9ff6f7ef"
}

Added in version 2.57.

Returns the completed percentage and the destination share server id of an ongoing share server migration.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.

Request¶

Name	In	Type	Description
share_server_id	body	string	The UUID of the share server.
project_id	body	string	The ID of the project that owns the resource.

Response parameters¶

Name	In	Type	Description
total_progress	body	integer	Defines a total progress of share server migration.
task_state	body	string	For the share server migration, the migration task state. A valid value is `null`, `migration_in_progress`, `migration_cancel_in_progress`, `migration_cancelled`, `migration_driver_starting`, `migration_driver_in_progress`, or `migration_phase_1_done`.
destination_share_server_id	body	string	UUID of the share server that was created in the destination backend during a share server migration operation.

Request example¶

{
    "migration_get_progress": null
}

Response example¶

{
    "total_progress": 50,
    "task_state": "migration_driver_in_progress",
    "destination_share_server_id": "c2f71561-85e2-4ccb-a91a-e44f9ff6f7ef"
}

Added in version 2.57.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
share_server_id	body	string	The UUID of the share server.
project_id	body	string	The ID of the project that owns the resource.

Request example¶

{
    "migration_cancel":null
}

Share backups (since API v2.80)¶

Use the Shared File Systems service to make backups of shares. A share backup is a point-in-time, read-only copy of the data that is contained in a share. The APIs below allow controlling share backups. They are represented by a “backup” resource in the Shared File Systems service, and they can have user-defined metadata such as a name and description.

You can create, restore, update, list and delete share backups. After you create a share backup, you can access backup and use it. You can also restore a backup into a share as long as certain criteria are met e.g. size.

You can update a share backup to change its name or description. As administrator, you can also reset the state of a backup. Backup can be in one of the following states:

available
error
creating
deleting
restoring

During a backup or restore operation, share can be in one of the following states:

available
backup_creating
backup_restoring
backup_restoring_error

Added in version 2.80.

Lists all share backups.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.

Request¶

Name	In	Type	Description
share_id (Optional)	query	string	The UUID of the share that the backup pertains to.
name~ (Optional)	query	string	The name pattern that can be used to filter share backups.
description~ (Optional)	query	string	The description pattern that can be used to filter share backups.
limit (Optional)	query	integer	The maximum number of resource records to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of share backups. A valid value is `id`, `status`, `size`, `host`, `share_id` `availability_zone`, `created_at`, `updated_at`, `display_name`, `topic`, `progress` and `restore_progress`
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.
status (Optional)	query	string	Filters by a backup status. A valid filter value can be one of ‘creating’, ‘error’, ‘available’, ‘restoring’.
host (Optional)	query	string	The host name of the backup to query with. Querying by hostname is a privileged operation. If restricted by API policy, this query parameter may be silently ignored by the server.
topic (Optional)	query	string	Filters by a backup topic. A valid filter value can be one of ‘manila-data’, ‘manila-share’.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share backup.
share_id	body	string	The UUID of the share that the backup pertains to.
status	body	string	The status of backup which can be one of `creating`, `error`, `available`, `restoring`.

Response example¶

{
    "share_backups": [
        {
            "id": "1125c47a-0216-4ee0-a517-0460d63301a6",
            "name": "backup3",
            "share_id": "112dffd-f033-4248-a315-319ca2bd70c8",
            "status": "available"
        },
        {
            "id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
            "name": "backup1",
            "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
            "status": "creating"
        }
    ]
}

Added in version 2.80.

Lists all share backups with details.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.

Request¶

Name	In	Type	Description
share_id (Optional)	query	string	The UUID of the share that the backup pertains to.
name~ (Optional)	query	string	The name pattern that can be used to filter share backups.
description~ (Optional)	query	string	The description pattern that can be used to filter share backups.
limit (Optional)	query	integer	The maximum number of resource records to return.
offset (Optional)	query	integer	The offset to define start point of resource listing.
sort_key (Optional)	query	string	The key to sort a list of share backups. A valid value is `id`, `status`, `size`, `host`, `share_id` `availability_zone`, `created_at`, `updated_at`, `display_name`, `topic`, `progress` and `restore_progress`
sort_dir (Optional)	query	string	The direction to sort a list of resources. A valid value is `asc`, or `desc`.
status (Optional)	query	string	Filters by a backup status. A valid filter value can be one of ‘creating’, ‘error’, ‘available’, ‘restoring’.
host (Optional)	query	string	The host name of the backup to query with. Querying by hostname is a privileged operation. If restricted by API policy, this query parameter may be silently ignored by the server.
topic (Optional)	query	string	Filters by a backup topic. A valid filter value can be one of ‘manila-data’, ‘manila-share’.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share backup.
share_id	body	string	The UUID of the share that the backup pertains to.
status	body	string	The status of backup which can be one of `creating`, `error`, `available`, `restoring`.
size	body	integer	The share backup size, in GiBs.
availability_zone	body	string	The availability zone.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
progress	body	string	The progress of the backup creation in percentange.
restore_progress	body	string	The progress of the backup restoration in percentage.

Response example¶

{
    "share_backups": [
        {
            "id": "1125c47a-0216-4ee0-a517-0460d63301a6",
            "share_id": "112dffd-f033-4248-a315-319ca2bd70c8",
            "status": "available",
            "name": "backup3",
            "description": null,
            "size": 1,
            "created_at": "2023-08-16T12:34:57.000000",
            "updated_at": "2023-08-17T12:14:15.000000",
            "availability_zone": null,
            "progress": "100",
            "restore_progress": "0"
        },
        {
            "id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
            "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
            "status": "creating",
            "name": "backup1",
            "description": null,
            "size": 1,
            "created_at": "2023-08-16T13:03:59.020692",
            "updated_at": "2023-08-16T13:13:15.000002",
            "availability_zone": null,
            "progress": "0",
            "restore_progress": "0"
        }
    ]
}

Added in version 2.80.

Shows details for a share backup.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
backup_id	path	string	The UUID of the share backup.

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share backup.
share_id	body	string	The UUID of the share that the backup pertains to.
status	body	string	The status of backup which can be one of `creating`, `error`, `available`, `restoring`.
size	body	integer	The share backup size, in GiBs.
availability_zone	body	string	The availability zone.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
progress	body	string	The progress of the backup creation in percentange.
restore_progress	body	string	The progress of the backup restoration in percentage.

Response example¶

{
    "share_backup": {
        "id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
        "status": "available",
        "name": "backup1",
        "description": null,
        "size": 1,
        "created_at": "2023-08-16T13:03:59.000000",
        "updated_at": "2023-08-16T13:04:15.000000",
        "availability_zone": null,
        "progress": "100",
        "restore_progress": "0"
    }
}

Added in version 2.80.

Creates a backup from a share.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This resource has an action in progress that would conflict with this request.
`422 - Unprocessable Entity`	The entity of the request is in a format not processable by the requested resource for the method.

Request¶

Name	In	Type	Description
share_id	body	string	The UUID of the share that the backup pertains to.
name (Optional)	body	string	The user defined name of the resource. The value of this field is limited to 255 characters.
description (Optional)	body	string	The user defined description of the resource. The value of this field is limited to 255 characters.
backup_options (Optional)	body	object	One or more backup options key and value pairs as a url encoded dictionary of strings.

Request example¶

{
    "share_backup": {
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
        "backup_options": {},
        "description": null,
        "name": "backup1"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share backup.
share_id	body	string	The UUID of the share that the backup pertains to.
status	body	string	The status of backup which can be one of `creating`, `error`, `available`, `restoring`.
size	body	integer	The share backup size, in GiBs.
availability_zone	body	string	The availability zone.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
progress	body	string	The progress of the backup creation in percentange.
restore_progress	body	string	The progress of the backup restoration in percentage.

Response example¶

{
    "share_backup": {
        "id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
        "status": "creating",
        "name": "backup1",
        "description": null,
        "size": 1,
        "created_at": "2023-08-16T13:03:59.020692",
        "updated_at": "2023-08-16T13:03:59.020692",
        "availability_zone": null,
        "progress": "0",
        "restore_progress": "0"
    }
}

Added in version 2.80.

Updates a share backup.

You can update these attributes:

display_name, which changes the name of the share backup.
display_description, which changes the description of the share backup.

If you try to update other attributes, they retain their previous values.

Response codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
backup_id	path	string	The UUID of the share backup.
display_name (Optional)	body	string	The user defined name of the resource. This field sets the `name` parameter.
display_description (Optional)	body	string	The user defined description of the resource. This field sets the `description` parameter.

Request example¶

{
    "share_backup": {
        "display_name": "backup2",
        "display_description": "I am changing a description also. Here is a backup"
    }
}

Response parameters¶

Name	In	Type	Description
id	body	string	The UUID of the share backup.
share_id	body	string	The UUID of the share that the backup pertains to.
status	body	string	The status of backup which can be one of `creating`, `error`, `available`, `restoring`.
size	body	integer	The share backup size, in GiBs.
availability_zone	body	string	The availability zone.
name	body	string	The user defined name of the resource.
description	body	string	The user defined description of the resource.
created_at	body	string	The date and time stamp when the resource was created within the service’s database. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2019-03-27T09:49:58-05:00`.
updated_at	body	string	The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The `±hh:mm` value, if included, returns the time zone as an offset from UTC. For example, `2016-12-31T13:14:15-05:00`.
progress	body	string	The progress of the backup creation in percentange.
restore_progress	body	string	The progress of the backup restoration in percentage.

Response example¶

{
    "share_backup": {
        "id": "fa32a89f-ed0f-4906-b1d7-92eedf98fbb5",
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
        "status": "available",
        "name": "backup2",
        "description": "I am changing a description also. Here is a backup",
        "size": 1,
        "created_at": "2023-08-16T13:18:55.000000",
        "updated_at": "2023-08-16T13:33:15.000000",
        "availability_zone": null,
        "progress": "100",
        "restore_progress": "0"
    }
}

Added in version 2.80.

Deletes a share backup.

Preconditions

Share backup status must be available or error.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
backup_id	path	string	The UUID of the share backup.

Added in version 2.80.

Restores a share backup into original share.

Preconditions

Share backup status must be available.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
backup_id	path	string	The UUID of the share backup.

Request example¶

{
    "restore": null
}

Response parameters¶

Name	In	Type	Description
backup_id	body	string	The UUID of the share backup.
share_id	body	string	The UUID of the share that the backup pertains to.

Response example¶

{
    "restore": {
        "backup_id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30"
    }
}

Added in version 2.80.

Administrator only. Explicitly updates the state of a share backup.

Use the policy.yaml file to grant permissions for this action to other roles.

Response codes¶

Success¶

Code	Reason
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request¶

Name	In	Type	Description
project_id (Optional)	path	string	The project ID of the user or service making the API request. This parameter is optional if the service supports API version 2.60. If the service doesn’t yet support API version 2.60, ensure that the service catalog endpoint obtained for the service has the user’s project_id after the “/v2/” component, for example, the API to retrieve shares is GET /v2/{project_id}/shares. If the service doesn’t yet support API version 2.60, and the project_id is ommitted from the API URL, a Malformed Request error is returned (HTTP 400).
backup_id	path	string	The UUID of the share backup.
status (Optional)	body	string	The backup status, which can be `available`, `error`, `creating`, `deleting`, `restoring`.

Request example¶

{
    "reset_status": {
        "status": "error"
    }
}