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
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.
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
        }
    }
}

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
`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.

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.
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 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 API response or not, default is `False`. New in version 2.42
limit (Optional)	query	integer	The maximum number of shares to return.
offset (Optional)	query	integer	The offset to define start point of share or share group 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 shares. 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.
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 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 API response or not, default is `False`. New in version 2.42
limit (Optional)	query	integer	The maximum number of shares to return.
offset (Optional)	query	integer	The offset to define start point of share or share group 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 shares. 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.
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

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,
            "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,
            "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

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"
    }
}

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.

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"
        }
    }
}

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

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"
    }
}

New 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.json 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

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

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

New 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.json.
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

New 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.json.
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 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"
    }
}

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 share or access rule 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.json 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.

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
`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.
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.
access_metadata	body	object	One or more metadata key and value pairs as a dictionary of strings.

Request example¶

{
    "allow_access": {
        "access_level": "rw",
        "access_type": "ip",
        "access_to": "0.0.0.0/0",
        "metadata":{
            "key1": "value1",
            "key2": "value2"
        }
    }
}

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.
access_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.

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.

Request example¶

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

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.json 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.json 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.

Request example¶

{
    "extend": {
        "new_size": 2
    }
}

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
    }
}

New 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.json 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.

New 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"
    }
}

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.json 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 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 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 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 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¶

{
    "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

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	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": {
        "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
    }
}

New 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"
    }
}

New 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.json 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.json 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.

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.json file to grant permissions for these actions to other roles.

New 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"
        }
    ]
}

New 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"
        }
    ]
}

New 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"
    }
}

New in version 2.19.

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

Use the policy.json 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.

New 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.

Request example¶

{
    "share_replica": {
        "share_id": "50a6a566-6bac-475c-ad69-5035c86696c0",
        "availability_zone": "nova"
    }
}

Note

Since API version 2.51, the parameter share_network_id is deprecated. 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	string	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"
    }
}

New 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	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.

New 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.

New 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"
        }
    ]
}

New 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	string	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"
        }
    ]
}

New 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	string	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"
    }
}

New in version 2.11.

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

Use the policy.json 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"
    }
}

New in version 2.11.

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

Use the policy.json 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"
    }
}

New 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.

New in version 2.11.

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

Use the policy.json 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

New 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.json.
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

New 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.json.
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 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 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 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 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

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

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
    }
}

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,
        "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

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
    }
}

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",
        "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.

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

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
    }
}

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

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
    }
}

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,
        "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

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
    }
}

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",
        "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.

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.

New 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"
    }
    ]
}

New 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"
    }
}

New in version 2.51.

Creates a share network subnet in the given 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.
`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
    }
}

New 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.

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 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.
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,
            "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,
            "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.
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,
        "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.

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.
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,
        "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.

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.
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.json 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

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"
        }
    ]
}

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

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"
    }
}

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.

New 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

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"
    }
}

New 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)

New in version 2.49.

Resets a share server status

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

Use the policy.json 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)¶

Administrators can list, show information for, explicitly set the state of, and force-delete share instances. Use the policy.json file to grant permissions for these actions to other roles.

New 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

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).

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`.
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	string	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_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",
            "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",
            "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",
            "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",
            "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",
            "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",
            "id": "48155648-2fd3-480d-b02b-44b995c24bab"
        }
    ]
}

New 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`.
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	string	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",
        "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"
    }
}

New in version 2.3.

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

Use the policy.json 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"
    }
}

New in version 2.3.

Administrator only. Force-deletes a share instance.

Use the policy.json 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.json 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

New 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.json.
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

New 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.json.
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.json 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.
extra_specs	body	object	The extra specifications for the share type.
driver_handles_share_servers	body	boolean	An extra specification that 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. This value is `true` when the share driver manages, or handles, the share server life cycle. This value is `false` when an administrator rather than a share driver manages the storage life cycle.
replication_type (Optional)	body	string	Type of replication supported for shares of this type. Valid values are: `null`: replication is not supported `readable`: users can create replicas of the share that are read-only until they are promoted, `writable`: users can create read/write replicas `dr`: users can create replicas that are not exported until they are promoted.
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
mount_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to mount share snapshots. New in version 2.32
revert_to_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots. New in version 2.27
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
create_share_from_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots. New in version 2.24
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.
extra_specs	body	object	The extra specifications for the share type.
driver_handles_share_servers	body	boolean	An extra specification that 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. This value is `true` when the share driver manages, or handles, the share server life cycle. This value is `false` when an administrator rather than a share driver manages the storage life cycle.
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
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": {
            "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.
extra_specs	body	object	The extra specifications for the share type.
driver_handles_share_servers	body	boolean	An extra specification that 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. This value is `true` when the share driver manages, or handles, the share server life cycle. This value is `false` when an administrator rather than a share driver manages the storage life cycle.
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
replication_type (Optional)	body	string	Type of replication supported for shares of this type. Valid values are: `null`: replication is not supported `readable`: users can create replicas of the share that are read-only until they are promoted, `writable`: users can create read/write replicas `dr`: users can create replicas that are not exported until they are promoted.
mount_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to mount share snapshots. New in version 2.32
revert_to_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots. New in version 2.27
create_share_from_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots. New in version 2.24
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": {
            "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	The extra specifications for the share type.
driver_handles_share_servers	body	boolean	An extra specification that 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. This value is `true` when the share driver manages, or handles, the share server life cycle. This value is `false` when an administrator rather than a share driver manages the storage life cycle.
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
replication_type (Optional)	body	string	Type of replication supported for shares of this type. Valid values are: `null`: replication is not supported `readable`: users can create replicas of the share that are read-only until they are promoted, `writable`: users can create read/write replicas `dr`: users can create replicas that are not exported until they are promoted.
mount_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to mount share snapshots. New in version 2.32
revert_to_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots. New in version 2.27
create_share_from_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots. New in version 2.24

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	The extra specifications for the share type.
driver_handles_share_servers	body	boolean	An extra specification that 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. This value is `true` when the share driver manages, or handles, the share server life cycle. This value is `false` when an administrator rather than a share driver manages the storage life cycle.
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
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 (Optional)	body	string	Name of the share type. The value of this field is limited to 255 characters.
replication_type (Optional)	body	string	Type of replication supported for shares of this type. Valid values are: `null`: replication is not supported `readable`: users can create replicas of the share that are read-only until they are promoted, `writable`: users can create read/write replicas `dr`: users can create replicas that are not exported until they are promoted.
mount_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to mount share snapshots. New in version 2.32
revert_to_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots. New in version 2.27
create_share_from_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots. New in version 2.24
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.
extra_specs	body	object	The extra specifications for the share type.
driver_handles_share_servers	body	boolean	An extra specification that 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. This value is `true` when the share driver manages, or handles, the share server life cycle. This value is `false` when an administrator rather than a share driver manages the storage life cycle.
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
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.
replication_type (Optional)	body	string	Type of replication supported for shares of this type. Valid values are: `null`: replication is not supported `readable`: users can create replicas of the share that are read-only until they are promoted, `writable`: users can create read/write replicas `dr`: users can create replicas that are not exported until they are promoted.
mount_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to mount share snapshots. New in version 2.32
revert_to_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots. New in version 2.27
create_share_from_snapshot_support (Optional)	body	boolean	Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots. New in version 2.24
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	The extra specifications for the share type.

Request example¶

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

Response parameters¶

Name	In	Type	Description
extra_specs	body	object	The extra specifications for the share type.

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