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

Show All

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

detail

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

detail

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

detail

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.

GET

/v2/limits

List share limits

detail

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

detail

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

detail

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
}

GET

/v2/shares/{share_id}

Show share details

detail

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

GET

/v2/shares/{share_id}/instances

List share instances

detail

New in version 2.3.

Lists instances of a share.

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

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Response parameters

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

Response example

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

POST

/v2/shares

Create share

detail

Creates a share.

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Request example

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

Response parameters

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

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

POST

/v2/shares/manage

Manage share (since API v2.7)

detail

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

PUT

/v2/shares/{share_id}

Update share

detail

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

DELETE

/v2/shares/{share_id}

Delete share

detail

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

detail

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

detail

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.

GET

/v2/shares/{share_id}/metadata

Show all share metadata

detail

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

GET

/v2/shares/{share_id}/metadata/{key}

Show share metadata item

detail

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

POST

/v2/shares/{share_id}/metadata

Set share metadata

detail

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

PUT

/v2/shares/{share_id}/metadata

Update share metadata

detail

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
}

DELETE

/v2/shares/{share_id}/metadata/{key}

Delete share metadata item

detail

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

detail

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.
metadata	body	object	One or more access rule metadata key and value pairs as a dictionary of strings. New in version 2.45

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

detail

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)

detail

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

POST

/v2/shares/{share_id}/action

Reset share state

detail

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

POST

/v2/shares/{share_id}/action

Force-delete share

detail

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
}

POST

/v2/shares/{share_id}/action

Extend share

detail

Increases the size of a share.

Response codes

Success

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

Error

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

Request

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

Request example

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

POST

/v2/shares/{share_id}/action

Shrink share

detail

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

POST

/v2/shares/{share_id}/action

Unmanage share (since API v2.7)

detail

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.

POST

/v2/shares/{share_id}/action

Revert share to snapshot (since API v2.27)

detail

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.

GET

/v2/snapshots

List share snapshots

detail

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

GET

/v2/snapshots/detail

List share snapshots with details

detail

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

GET

/v2/snapshots/{snapshot_id}

Show share snapshot details

detail

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

POST

/v2/snapshots

Create share snapshot

detail

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

POST

/v2/snapshots/manage

Manage share snapshot (since API v2.12)

detail

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

POST

/v2/snapshots/{snapshot_id}/action

Unmanage share snapshot (since API v2.12)

detail

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.

POST

/v2/snapshots/{snapshot_id}/action

Reset share snapshot state

detail

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

POST

/v2/snapshots/{snapshot_id}/action

Force-delete share snapshot

detail

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
}

PUT

/v2/snapshots/{snapshot_id}

Update share snapshot

detail

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

DELETE

/v2/snapshots/{snapshot_id}

Delete share snapshot

detail

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.

GET

/v2/snapshot-instances

List share snapshot instances

detail

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

GET

/v2/snapshot-instances/detail

List share snapshot instances with details

detail

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

GET

/v2/snapshot-instances/{snapshot_instance_id}

Show share snapshot instance details

detail

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

POST

/v2/snapshot-instances/{snapshot_instance_id}/action

Reset share snapshot instance state

detail

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.

POST

/v2/share-replicas

Create share replica

detail

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

Response example

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

POST

/v2/share-replicas/{share_replica_id}/action

Promote share replica

detail

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.

POST

/v2/share-replicas/{share_replica_id}/action

Resync share replica

detail

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.

GET

/v2/share-replicas?share_id={share_id}

List share replicas

detail

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

GET

/v2/share-replicas/detail?share_id={share_id}

List share replicas with details

detail

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

Response example

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

GET

/v2/share-replicas/{share_replica_id}

Show share replica

detail

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

Response example

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

POST

/v2/share-replicas/{share_replica_id}/action

Reset status of the share replica

detail

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

POST

/v2/share-replicas/{share_replica_id}/action

Reset replica_state of the share replica

detail

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

DELETE

/v2/share-replicas/{share_replica_id}

Delete share replica

detail

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.

POST

/v2/share-replicas/{share_replica_id}/action

Force-delete share replica

detail

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

detail

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

detail

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.

GET

/v2/share-networks

List share networks

detail

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

GET

/v2/share-networks/detail

List share networks with details

detail

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
security_service_update_support	body	boolean	Whether the share network supports its security services being updated when it is already being used. New in version 2.63
status	body	string	The status of a share network. Possible values are: active, error or network_change. New in version 2.63

Response example

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

Note

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 response will look like the below example.

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

GET

/v2/share-networks/{share_network_id}

Show share network details

detail

Shows details for a share network.

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Response parameters

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

Response example

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

Note

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 response will look like the below example.

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

POST

/v2/share-networks

Create share network

detail

Creates a share network.

Response codes

Success

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

Error

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

Request

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

Request example

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

Note

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

Response parameters

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

Response example

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

Note

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

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

POST

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

Add security service to share network

detail

Adds a security service to a share network.

Note

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

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Request example

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

Response parameters

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

Response example

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

Note

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 response will look like the below example.

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

POST

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

Remove security service from share network

detail

Removes a security service from a share network.

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Request example

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

Response parameters

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

Response example

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

Note

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 response will look like the below example.

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

PUT

/v2/share-networks/{share_network_id}

Update share network

detail

Updates a share network.

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

Note

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

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Request example

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

Response parameters

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

Response example

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

Note

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 response will look like the below example.

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

DELETE

/v2/share-networks/{share_network_id}

Delete share network

detail

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.

POST

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

Update share network security service (since API v2.63)

detail

New in version 2.63.

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

Important

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

Response codes

Success

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

Error

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

Request

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

Request example

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

Response parameters

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

Response example

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

POST

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

Check share network security service update (since API v2.63)

detail

New in version 2.63.

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

Response codes

Success

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

Error

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

Request

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

Request example

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

Response parameters

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

Response example

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

POST

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

Check share network security service add (since API v2.63)

detail

New in version 2.63.

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

Response codes

Success

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

Error

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

Request

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

Request example

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

Response parameters

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

Response example

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

POST

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

Reset status (since API v2.63)

detail

New in version 2.63.

Resets a share network status.

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

Response codes

Success

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

Error

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

Request parameters

Name	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.
status	body	string	The status of a share network. Possible values are: active, error or network_change. New in version 2.63

Request example

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

Response parameters

There is no body content for the response.

Share network subnets (since API v2.51)

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

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

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

Note

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

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

A share network subnet resource has these attributes:

• The IP block in Classless Inter-Domain Routing (CIDR) notation from which to allocate the network.

• The IP version of the network.

• The network type, which is vlan, vxlan, gre, or flat.

• If the network uses segmentation, a segmentation identifier. For example, VLAN, VXLAN, and GRE networks use segmentation.

• The availability zone, when null signifies that the share network subnet is available across all storage availability zones known to the Shared File Systems Service.

GET

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

List share network subnets

detail

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

GET

/v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}

Show share network subnet details

detail

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

POST

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

Create share network subnet

detail

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

DELETE

/v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}

Delete share network subnet

detail

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

detail

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

detail

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

detail

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

detail

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

detail

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

detail

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.

GET

/v2/share-servers

List share servers

detail

Lists all share servers.

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Response parameters

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

Response example

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

GET

/v2/share-servers/{share_server_id}

Show share server

detail

Show a share server’s details.

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Response parameters

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

Response example

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

GET

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

Show share server back end details

detail

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

DELETE

/v2/share-servers/{share_server_id}

Delete share server

detail

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.

POST

/v2/share-servers/manage

Manage share server (since API v2.49)

detail

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
security_service_update_support	body	boolean	Whether a share network or server supports security service updates or not. New in version 2.63

Response examples

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

POST

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

Unmanage share server (since API v2.49)

detail

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)

detail

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)

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

GET

/v2/share_instances

List share instances

detail

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	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).
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	boolean	If the share instance has its cast_rules_to_readonly attribute set to True, all existing access rules will be cast to read/only. New in version 2.30
share_network_id	body	string	The share network ID where the resource is exported to.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
access_rules_status	body	string	The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync. New in version 2.10
share_type_id	path	string	The UUID of the share type.
id	body	string	The share instance ID.

Response example

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

GET

/v2/share_instances/{share_instance_id}

Show share instance details

detail

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	boolean	If the share instance has its cast_rules_to_readonly attribute set to True, all existing access rules will be cast to read/only. New in version 2.30
share_network_id	body	string	The share network ID where the resource is exported to.
share_server_id	body	string	The UUID of the share server.
host	body	string	The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.
id	body	string	The share instance ID.

Response example

{
    "share_instance": {
        "status": "available",
        "progress": "100%",
        "share_id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
        "availability_zone": "nova",
        "replica_state": null,
        "created_at": "2015-09-07T08:51:34.000000",
        "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"
    }
}

POST

/v2/share_instances/{share_instance_id}/action

Reset share instance state

detail

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

POST

/v2/share_instances/{share_instance_id}/action

Force-delete share instance

detail

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

detail

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

detail

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.

GET

/v2/types?is_public={is_public}&extra-specs={extra-specs-as-dict}

List share types

detail

Lists all share types.

Response codes

Success

Code	Reason
200 - OK	Request was successful.

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).
is_public (Optional)	query	boolean	A boolean query parameter that, when set to true, allows retrieving public resources that belong to all projects.
extra_specs (Optional)	query	string	The extra specifications as a set of one or more key-value pairs. In each pair, the key is the name of the extra specification and the value is the share type that was used to filter search share type list. The query must be a “percent-encoded” string, for example, the following query parameters: {‘extra-specs’: {‘snapshot_support’: ‘true’, ‘availability_zones’: ‘az1’}} is encoded as ‘extra_specs=%7B%27snapshot_support%27%3A+%27true%27%2C+%27availability_zones%27%3A+%27az1%27%7D’ New in version 2.43

Response parameters

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

Response example

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

GET

/v2/types/default

List default share types

detail

Lists default share types.

Response codes

Success

Code	Reason
200 - OK	Request was successful.

Error

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

Request

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

Response parameters

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

Response example

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