Shared File Systems API

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

Important

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

GET /v2/{project_id}/shares

API versions

Lists information for all Shared File Systems API versions.

Concepts

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

  • ‘’major versions’’, which have dedicated URLs

  • ‘’microversions’’, which can be requested through the use of the X-OpenStack-Manila-API-Version header

Read more about microversion guidelines that the service adheres to here

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

GET
/

List All Major Versions

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

Response codes

Success

Code

Reason

300 - Multiple Choices

The resource corresponds to more than one representation.

Response

Name

In

Type

Description

versions

body

array

A list of version objects that describe the API versions available.

id

body

string

A common name for the version in question. Informative only, it has no real semantic meaning.

updated

body

string

A date and time stamp for API versions. This field presents no meaningful information.

status

body

string

The status of this API version. This can be one of:

  • CURRENT: this is the preferred version of the API to use

  • SUPPORTED: this is an older, but still supported version of the API

  • DEPRECATED: a deprecated version of the API that is slated for removal

links

body

array

Pagination and bookmark links for the resource.

media-types

body

object

Media types supported by the API.

version

body

string

If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.

min_version

body

string

If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.

Note

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

Response Example

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

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

Show Details of Specific API Version

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

api_version

path

string

The API version as returned in the links from the GET / call.

Response

Name

In

Type

Description

version

body

string

The version.

id

body

string

A common name for the version in question. Informative only, it has no real semantic meaning.

status

body

string

The status of this API version. This can be one of:

  • CURRENT: this is the preferred version of the API to use

  • SUPPORTED: this is an older, but still supported version of the API

  • DEPRECATED: a deprecated version of the API that is slated for removal

links

body

array

Pagination and bookmark links for the resource.

version

body

string

If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.

updated

body

string

A date and time stamp for API versions. This field presents no meaningful information.

min_version

body

string

If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.

media-types

body

object

Media types supported by the API.

Note

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

Response Example

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

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

API extensions

Lists available Shared File Systems API extensions.

GET
/v2/extensions

List extensions

Lists all extensions.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

Response parameters

Name

In

Type

Description

name

body

string

The name of the extension. For example, “Fox In Socks.”

links

body

array

The extension links.

description

body

string

The description of the extension API.

alias

body

string

The alias for the extension. For example, “FOXNSOX”, “os-availability-zone”, “os-extended-quotas”, “os- share-unmanage”, or “os-used-limits”.

updated

body

string

The date and time stamp when the extension API was last updated.

The date and time stamp format is ISO 8601:

::

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

Response example

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

Limits

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

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

  • Total maximum share memory, in GiBs.

  • Number of share-networks.

  • Number of share-snapshots.

  • Number of shares.

  • Shares and total used memory, in GiBs.

  • Snapshots and total used memory, in GiBs.

  • Number of share replicas (since API version 2.53).

  • Share replicas and total used memory, in GiBs (since API version 2.53).

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

GET
/v2/limits

List share limits

Lists share limits.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

Response parameters

Name

In

Type

Description

maxTotalShareGigabytes

body

integer

The total maximum number of share gigabytes that are allowed in a project. You cannot request a share that exceeds the allowed gigabytes quota.

maxTotalSnapshotGigabytes

body

integer

The total maximum number of snapshot gigabytes that are allowed in a project.

maxTotalShares

body

integer

The total maximum number of shares that are allowed in a project.

maxTotalShareSnapshots

body

integer

The total maximum number of share snapshots that are allowed in a project.

maxTotalShareNetworks

body

integer

The total maximum number of share-networks that are allowed in a project.

maxTotalShareReplicas

body

integer

The maximum number of share replicas that is allowed.

New in version 2.53

maxTotalReplicaGigabytes

body

integer

The maximum number of replica gigabytes that are allowed in a project. You cannot create a share, share replica, manage a share or extend a share if it is going to exceed the allowed replica gigabytes quota.

New in version 2.53

maxTotalShareBackups

body

integer

The total maximum number of share backups that are allowed in a project.

New in version 2.80

maxTotalBackupGigabytes

body

integer

The total maximum number of backup gigabytes that are allowed in a project.

New in version 2.80

totalSharesUsed

body

integer

The total number of created shares in a project.

totalShareSnapshotsUsed

body

integer

The total number of created share snapshots in a project.

totalShareNetworksUsed

body

integer

The total number of created share-networks in a project.

totalShareGigabytesUsed

body

integer

The total number of gigabytes used in a project by shares.

totalSnapshotGigabytesUsed

body

integer

The total number of gigabytes used in a project by snapshots.

totalShareReplicasUsed

body

integer

The total number of created share replicas in a project.

totalReplicaGigabytesUsed

body

integer

The total number of replica gigabytes used in a project by share replicas.

totalShareBackupsUsed

body

integer

The total number of created share backups in a project.

totalBackupGigabytesUsed

body

integer

The total number of gigabytes used in a project by backups.

uri (Optional)

body

string

A human-readable URI of a rate limit.

regex (Optional)

body

string

An API regular expression. For example, ^/shares for the /shares API URI or .* for any URI.

value (Optional)

body

integer

The number of API requests that are allowed during a time interval. Used in conjunction with the unit parameter, expressed as value per unit. For example, 120 requests are allowed per minute.

verb (Optional)

body

string

The HTTP method for the API request. For example, GET, POST, DELETE, and so on.

remaining (Optional)

body

integer

The remaining number of allowed requests.

unit (Optional)

body

string

The time interval during which a number of API requests are allowed. A valid value is SECOND, MINUTE, HOUR, or DAY. Used in conjunction with the value parameter, expressed as value per unit. For example, 120 requests are allowed per minute.

next-available (Optional)

body

string

The date and time stamp when next issues are available.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

Response example

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

Shares

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

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

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

  • NFS. Network File System (NFS).

  • CIFS. Common Internet File System (CIFS).

  • GLUSTERFS. Gluster file system (GlusterFS).

  • HDFS. Hadoop Distributed File System (HDFS).

  • CEPHFS. Ceph File System (CephFS).

  • MAPRFS. MapR File System (MAPRFS).

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

A share has one of these status values:

Share statuses

Status

Description

backup_creating

The share is being backed up.

backup_restoring

The share is being restored from backup.

backup_restoring_error

An error occurred during share backup restore.

creating

The share is being created.

creating_from_snapshot

The share is being created from a parent snapshot.

deleting

The share is being deleted.

deleted

The share was deleted.

error

An error occurred during share creation.

error_deleting

An error occurred during share deletion.

available

The share is ready to use.

inactive

The share is inactive.

manage_starting

Share manage started.

manage_error

Share manage failed.

unmanage_starting

Share unmanage started.

unmanage_error

Share cannot be unmanaged.

unmanaged

Share was unmanaged.

extending

The extend, or increase, share size request was issued successfully.

extending_error

Extend share failed.

shrinking

Share is being shrunk.

shrinking_error

Failed to update quota on share shrinking.

shrinking_possible_data_loss_error

Shrink share failed due to possible data loss.

migrating

Share is currently migrating.

migrating_to

Share is a migration destination.

replication_change

The share is undergoing a replication change.

reverting

Share is being reverted to a snapshot.

reverting_error

Share revert to snapshot failed.

awaiting_transfer

Share is being transferred to a different project’s namespace.

GET
/v2/shares

List shares

Lists all shares.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name (Optional)

query

string

The user defined name of the resource to filter resources by.

status (Optional)

query

string

Filters by a share status. For valid statuses, see the section above.

share_server_id (Optional)

query

string

The UUID of the share server.

metadata (Optional)

query

object

One or more metadata key and value pairs as a url encoded dictionary of strings.

extra_specs (Optional)

query

string

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

New in version 2.43

share_type_id (Optional)

query

string

The UUID of a share type to query resources by.

snapshot_id (Optional)

query

string

The UUID of the share’s base snapshot to filter the request based on.

source_backup_id (Optional)

query

string

The UUID of the share’s backup to filter the request based on.

host (Optional)

query

string

The host name of the resource to query with. Querying by hostname is a privileged operation. If restricted by API policy, this query parameter may be silently ignored by the server.

share_network_id (Optional)

query

string

The UUID of the share network to filter resources by.

project_id (Optional)

query

string

The ID of the project that owns the resource. This query parameter is useful in conjunction with the all_tenants parameter.

is_public (Optional)

query

boolean

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

share_group_id (Optional)

query

string

The UUID of a share group to filter resource.

New in version 2.31

export_location_id (Optional)

query

string

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

New in version 2.35

export_location_path (Optional)

query

string

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

New in version 2.35

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

description~ (Optional)

query

string

The description pattern that can be used to filter shares, share snapshots, share networks or share groups.

New in version 2.36

with_count (Optional)

query

boolean

Whether to show count in share list API response or not, default is False. This query parameter is useful with pagination.

New in version 2.42

is_soft_deleted (Optional)

query

boolean

A boolean query parameter that, when set to True, will return all shares in recycle bin. Default is False, will return all shares not in recycle bin.

New in version 2.69

limit (Optional)

query

integer

The maximum number of resource records to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of shares. A valid value is id, status, size, host, share_proto, export_location, availability_zone, user_id, project_id, created_at, updated_at, display_name, name, share_type_id, share_type, share_network_id, share_network, snapshot_id, or snapshot.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share.

links

body

array

Pagination and bookmark links for the resource.

name

body

string

The user defined name of the resource.

count (Optional)

body

integer

The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query.

New in version 2.42

Response example

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

List shares with details

Lists all shares, with details.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

status (Optional)

query

string

Filters by a share status. For valid statuses, see the section above.

share_server_id (Optional)

query

string

The UUID of the share server.

metadata (Optional)

query

object

One or more metadata key and value pairs as a url encoded dictionary of strings.

extra_specs (Optional)

query

string

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

New in version 2.43

share_type_id (Optional)

query

string

The UUID of a share type to query resources by.

name (Optional)

query

string

The user defined name of the resource to filter resources by.

snapshot_id (Optional)

query

string

The UUID of the share’s base snapshot to filter the request based on.

source_backup_id (Optional)

query

string

The UUID of the share’s backup to filter the request based on.

host (Optional)

query

string

The host name of the resource to query with. Querying by hostname is a privileged operation. If restricted by API policy, this query parameter may be silently ignored by the server.

share_network_id (Optional)

query

string

The UUID of the share network to filter resources by.

project_id (Optional)

query

string

The ID of the project that owns the resource. This query parameter is useful in conjunction with the all_tenants parameter.

is_public (Optional)

query

boolean

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

share_group_id (Optional)

query

string

The UUID of a share group to filter resource.

New in version 2.31

export_location_id (Optional)

query

string

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

New in version 2.35

export_location_path (Optional)

query

string

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

New in version 2.35

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

description~ (Optional)

query

string

The description pattern that can be used to filter shares, share snapshots, share networks or share groups.

New in version 2.36

with_count (Optional)

query

boolean

Whether to show count in share list API response or not, default is False. This query parameter is useful with pagination.

New in version 2.42

is_soft_deleted (Optional)

query

boolean

A boolean query parameter that, when set to True, will return all shares in recycle bin. Default is False, will return all shares not in recycle bin.

New in version 2.69

limit (Optional)

query

integer

The maximum number of resource records to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of shares. A valid value is id, status, size, host, share_proto, export_location, availability_zone, user_id, project_id, created_at, updated_at, display_name, name, share_type_id, share_type, share_network_id, share_network, snapshot_id, or snapshot.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share.

size

body

integer

The share size, in GiBs.

availability_zone

body

string

The name of the availability zone the share exists within.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share or share instance status. Possible values are listed in the section above.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

snapshot_id

body

string

The UUID of the snapshot that was used to create the share.

source_backup_id

body

string

The UUID of the backup that was restored in the share.

New in version 2.80

share_network_id

body

string

The share network ID where the resource is exported to.

share_proto

body

string

The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS, MAPRFS, CephFS supported is starting with API v2.13.

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

share_type

body

string

The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.

links

body

array

Pagination and bookmark links for the resource.

is_public

body

boolean

Whether the share is visible publicly (by all projects in the cloud) or not.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

snapshot_support

body

boolean

Whether or not this share supports snapshots. Snapshots are point in time backups of the share.

New in version 2.2

task_state

body

string

For the share migration, the migration task state. A valid value is null, migration_starting, migration_error, migration_success, migration_completing, or migrating. The task_state is null unless the share is migrated from one back-end to another.

New in version 2.5

share_type_name

body

string

Name of the share type.

access_rules_status

body

string

The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync.

New in version 2.10

replication_type

body

string

The share replication type. The value can be:

  • null, if the share cannot be replicated.

  • readable, if one or more read-only replicas of the share can be created

  • writable, if one or more active replicas of the share can be created

  • dr, if one or more replicas of the share can be created that will remain inaccessible until they are promoted.

New in version 2.11

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

user_id

body

string

ID of the user that the share was created by.

New in version 2.16

create_share_from_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”)

New in version 2.24

revert_to_snapshot_support

body

boolean

Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.27

share_group_id

body

string

The UUID of the share group.

New in version 2.31

source_share_group_snapshot_member_id

body

string

ID of the group snapshot instance that was the source of this share.

New in version 2.31

mount_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.32

progress

body

string

The progress of the share creation.

New in version 2.54

count (Optional)

body

integer

The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query.

New in version 2.42

volume_type

body

string

The share type ID. This is a legacy parameter that contains the same value as the share_type parameter. Do not rely on this parameter as it may be removed in a future API revision.

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

is_soft_deleted (Optional)

body

boolean

Whether the share has been soft deleted to recycle bin or not.

New in version 2.69

scheduled_to_be_deleted_at (Optional)

body

string

Estimated time at which the share in the recycle bin will be deleted automatically.

New in version 2.69

Response example

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

Show share details

Shows details for a share.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share.

size

body

integer

The share size, in GiBs.

availability_zone

body

string

The name of the availability zone the share exists within.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share or share instance status. Possible values are listed in the section above.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

snapshot_id

body

string

The UUID of the snapshot that was used to create the share.

share_network_id

body

string

The share network ID where the resource is exported to.

share_proto

body

string

The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS, MAPRFS, CephFS supported is starting with API v2.13.

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

share_type

body

string

The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.

links

body

array

Pagination and bookmark links for the resource.

is_public

body

boolean

Whether the share is visible publicly (by all projects in the cloud) or not.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

snapshot_support

body

boolean

Whether or not this share supports snapshots. Snapshots are point in time backups of the share.

New in version 2.2

task_state

body

string

For the share migration, the migration task state. A valid value is null, migration_starting, migration_error, migration_success, migration_completing, or migrating. The task_state is null unless the share is migrated from one back-end to another.

New in version 2.5

share_type_name

body

string

Name of the share type.

access_rules_status

body

string

The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync.

New in version 2.10

replication_type

body

string

The share replication type. The value can be:

  • null, if the share cannot be replicated.

  • readable, if one or more read-only replicas of the share can be created

  • writable, if one or more active replicas of the share can be created

  • dr, if one or more replicas of the share can be created that will remain inaccessible until they are promoted.

New in version 2.11

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

user_id

body

string

ID of the user that the share was created by.

New in version 2.16

create_share_from_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”)

New in version 2.24

revert_to_snapshot_support

body

boolean

Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.27

share_group_id

body

string

The UUID of the share group.

New in version 2.31

source_share_group_snapshot_member_id

body

string

ID of the group snapshot instance that was the source of this share.

New in version 2.31

mount_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.32

progress

body

string

The progress of the share creation.

New in version 2.54

count (Optional)

body

integer

The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query.

New in version 2.42

volume_type

body

string

The share type ID. This is a legacy parameter that contains the same value as the share_type parameter. Do not rely on this parameter as it may be removed in a future API revision.

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

is_soft_deleted (Optional)

body

boolean

Whether the share has been soft deleted to recycle bin or not.

New in version 2.69

scheduled_to_be_deleted_at (Optional)

body

string

Estimated time at which the share in the recycle bin will be deleted automatically.

New in version 2.69

Response example

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

List share instances

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.yaml file to grant permissions for this action to other roles.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

Response parameters

Name

In

Type

Description

status

body

string

The share or share instance status. Possible values are listed in the section above.

access_rules_status

body

string

The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync.

New in version 2.10

share_id

body

string

The UUID of the share to which the share instance belongs to.

progress

body

string

The progress of the share creation.

New in version 2.54

availability_zone

body

string

The name of the availability zone the share exists within.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

replica_state

body

string

The share replica state. Has set value only when replication is used. List of possible values: active, in_sync, out_of_sync, and error.

New in version 2.11

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

cast_rules_to_readonly

body

boolean

If the share instance has its cast_rules_to_readonly attribute set to True, all existing access rules will be cast to read/only.

New in version 2.30

share_network_id

body

string

The share network ID where the resource is exported to.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

access_rules_status

body

string

The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync.

New in version 2.10

share_type_id

path

string

The UUID of the share type.

id

body

string

The share instance ID.

Response example

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

Create share

Creates a share.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_proto

body

string

The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS, MAPRFS, CephFS supported is starting with API v2.13.

size

body

integer

The share size, in GiBs. The requested share size cannot be greater than the allowed GiB quota. To view the allowed quota, issue a get limits request.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

display_name (Optional)

body

string

The user defined name of the resource. This field sets the name parameter.

display_description (Optional)

body

string

The user defined description of the resource. This field sets the description parameter.

share_type (Optional)

body

string

The name or ID of the share type to be used to create the resource. If you omit this parameter, the default share type is used. To view the default share type set by the administrator, issue a list default share types request.

snapshot_id (Optional)

body

string

The UUID of the share’s base snapshot.

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share visible to all projects in the cloud. Set to false to make it private to your project. Default value is false.

share_group_id (Optional)

body

string

The UUID of the share group.

New in version 2.31

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

share_network_id (Optional)

body

string

The ID of a share network that the resource must be exported to. Note that when using a share type with the driver_handles_share_servers extra spec as False, you should not provide a share_network_id.

availability_zone (Optional)

body

string

The UUID or name of an availability zone for resource to be created within.

scheduler_hints (Optional)

body

object

One or more scheduler_hints key and value pairs as a dictionary of strings. Accepted hints are: - same_host or different_host: values must be a comma separated list of Share IDs - only_host: value must be a manage-share service host in host@backend#POOL format (admin only). Only available in and beyond API version 2.67

New in version 2.65

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share.

size

body

integer

The share size, in GiBs.

availability_zone

body

string

The name of the availability zone the share exists within.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share or share instance status. Possible values are listed in the section above.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

snapshot_id

body

string

The UUID of the snapshot that was used to create the share.

share_network_id

body

string

The share network ID where the resource is exported to.

share_proto

body

string

The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS, MAPRFS, CephFS supported is starting with API v2.13.

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

share_type

body

string

The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.

links

body

array

Pagination and bookmark links for the resource.

is_public

body

boolean

Whether the share is visible publicly (by all projects in the cloud) or not.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

snapshot_support

body

boolean

Whether or not this share supports snapshots. Snapshots are point in time backups of the share.

New in version 2.2

task_state

body

string

For the share migration, the migration task state. A valid value is null, migration_starting, migration_error, migration_success, migration_completing, or migrating. The task_state is null unless the share is migrated from one back-end to another.

New in version 2.5

share_type_name

body

string

Name of the share type.

access_rules_status

body

string

The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync.

New in version 2.10

replication_type

body

string

The share replication type. The value can be:

  • null, if the share cannot be replicated.

  • readable, if one or more read-only replicas of the share can be created

  • writable, if one or more active replicas of the share can be created

  • dr, if one or more replicas of the share can be created that will remain inaccessible until they are promoted.

New in version 2.11

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

user_id

body

string

ID of the user that the share was created by.

New in version 2.16

create_share_from_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”)

New in version 2.24

revert_to_snapshot_support

body

boolean

Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.27

share_group_id

body

string

The UUID of the share group.

New in version 2.31

source_share_group_snapshot_member_id

body

string

ID of the group snapshot instance that was the source of this share.

New in version 2.31

mount_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.32

progress

body

string

The progress of the share creation.

New in version 2.54

count (Optional)

body

integer

The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query.

New in version 2.42

volume_type

body

string

The share type ID. This is a legacy parameter that contains the same value as the share_type parameter. Do not rely on this parameter as it may be removed in a future API revision.

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

is_soft_deleted (Optional)

body

boolean

Whether the share has been soft deleted to recycle bin or not.

New in version 2.69

scheduled_to_be_deleted_at (Optional)

body

string

Estimated time at which the share in the recycle bin will be deleted automatically.

New in version 2.69

Response example

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

Manage share (since API v2.7)

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.yaml file to grant permissions for this action to other roles.

Note

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share

body

object

A share object.

protocol

body

string

The Shared File Systems protocol of the share to manage. A valid value is NFS, CIFS, GlusterFS, CEPHFS, HDFS or MAPRFS.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

share_type (Optional)

body

string

The name or ID of the share type to be used to create the resource. If you omit this parameter, the default share type is used. To view the default share type set by the administrator, issue a list default share types request.

driver_options (Optional)

body

object

A set of one or more key and value pairs, as a dictionary of strings, that describe driver options. Details for driver options should be taken from appropriate share driver documentation.

export_path

body

string

The share export path in the format appropriate for the protocol:

  • NFS protocol. 10.0.0.1:/foo_path. For example, 10.254.0 .5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5.

  • CIFS protocol. For example, \\10.0.0.1\foo_name_of_cifs_share.

service_host

body

string

The manage-share service host in this format: host@backend#POOL:

  • host. The host name for the back end.

  • backend. The name of the back end.

  • POOL. The pool name for the back end.

share_server_id

body

string

The UUID of the share server.

New in version 2.49

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share visible to all projects in the cloud. Set to false to make it private to your project. Default value is false.

New in version 2.8

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share.

size

body

integer

The share size, in GiBs.

availability_zone

body

string

The name of the availability zone the share exists within.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share or share instance status. Possible values are listed in the section above.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

snapshot_id

body

string

The UUID of the snapshot that was used to create the share.

share_network_id

body

string

The share network ID where the resource is exported to.

share_proto

body

string

The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS, MAPRFS, CephFS supported is starting with API v2.13.

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

share_type

body

string

The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.

links

body

array

Pagination and bookmark links for the resource.

is_public

body

boolean

Whether the share is visible publicly (by all projects in the cloud) or not.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

snapshot_support

body

boolean

Whether or not this share supports snapshots. Snapshots are point in time backups of the share.

New in version 2.2

task_state

body

string

For the share migration, the migration task state. A valid value is null, migration_starting, migration_error, migration_success, migration_completing, or migrating. The task_state is null unless the share is migrated from one back-end to another.

New in version 2.5

share_type_name

body

string

Name of the share type.

access_rules_status

body

string

The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync.

New in version 2.10

replication_type

body

string

The share replication type. The value can be:

  • null, if the share cannot be replicated.

  • readable, if one or more read-only replicas of the share can be created

  • writable, if one or more active replicas of the share can be created

  • dr, if one or more replicas of the share can be created that will remain inaccessible until they are promoted.

New in version 2.11

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

user_id

body

string

ID of the user who brought the share under manila management.

New in version 2.16

create_share_from_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”)

New in version 2.24

revert_to_snapshot_support

body

boolean

Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.27

share_group_id

body

string

The UUID of the share group.

New in version 2.31

source_share_group_snapshot_member_id

body

string

ID of the group snapshot instance that was the source of this share.

New in version 2.31

mount_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.32

progress

body

string

The progress of the share creation.

New in version 2.54

count (Optional)

body

integer

The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query.

New in version 2.42

volume_type

body

string

The share type ID. This is a legacy parameter that contains the same value as the share_type parameter. Do not rely on this parameter as it may be removed in a future API revision.

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

is_soft_deleted (Optional)

body

boolean

Whether the share has been soft deleted to recycle bin or not.

New in version 2.69

scheduled_to_be_deleted_at (Optional)

body

string

Estimated time at which the share in the recycle bin will be deleted automatically.

New in version 2.69

Response example

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

Update share

Updates a share.

You can update these attributes:

  • display_name, which also changes the name of the share.

  • display_description, which also changes the description of the share.

  • is_public. Changes the level of visibility.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share visible to all projects in the cloud. Set to false to make it private to your project. Default value is false.

display_name (Optional)

body

string

The user defined name of the resource. This field sets the name parameter.

display_description (Optional)

body

string

The user defined description of the resource. This field sets the description parameter.

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share.

size

body

integer

The share size, in GiBs.

availability_zone

body

string

The name of the availability zone the share exists within.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share or share instance status. Possible values are listed in the section above.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

snapshot_id

body

string

The UUID of the snapshot that was used to create the share.

share_network_id

body

string

The share network ID where the resource is exported to.

share_proto

body

string

The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS, MAPRFS, CephFS supported is starting with API v2.13.

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

share_type

body

string

The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.

links

body

array

Pagination and bookmark links for the resource.

is_public

body

boolean

Whether the share is visible publicly (by all projects in the cloud) or not.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

snapshot_support

body

boolean

Whether or not this share supports snapshots. Snapshots are point in time backups of the share.

New in version 2.2

task_state

body

string

For the share migration, the migration task state. A valid value is null, migration_starting, migration_error, migration_success, migration_completing, or migrating. The task_state is null unless the share is migrated from one back-end to another.

New in version 2.5

share_type_name

body

string

Name of the share type.

access_rules_status

body

string

The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync.

New in version 2.10

replication_type

body

string

The share replication type. The value can be:

  • null, if the share cannot be replicated.

  • readable, if one or more read-only replicas of the share can be created

  • writable, if one or more active replicas of the share can be created

  • dr, if one or more replicas of the share can be created that will remain inaccessible until they are promoted.

New in version 2.11

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

user_id

body

string

ID of the user that the share was created by.

New in version 2.16

create_share_from_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be cloned into new shares. Inconsequential if the share doesn’t support snapshots. (see capability “snapshot_support”)

New in version 2.24

revert_to_snapshot_support

body

boolean

Whether or not this share supports being reverted to its latest snapshot. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.27

share_group_id

body

string

The UUID of the share group.

New in version 2.31

source_share_group_snapshot_member_id

body

string

ID of the group snapshot instance that was the source of this share.

New in version 2.31

mount_snapshot_support

body

boolean

Whether or not this share supports snapshots that can be mounted and access controlled independently of the share. Inconsequential if the share doesn’t support snapshots (see capability “snapshot_support”).

New in version 2.32

progress

body

string

The progress of the share creation.

New in version 2.54

count (Optional)

body

integer

The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query.

New in version 2.42

volume_type

body

string

The share type ID. This is a legacy parameter that contains the same value as the share_type parameter. Do not rely on this parameter as it may be removed in a future API revision.

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

is_soft_deleted (Optional)

body

boolean

Whether the share has been soft deleted to recycle bin or not.

New in version 2.69

scheduled_to_be_deleted_at (Optional)

body

string

Estimated time at which the share in the recycle bin will be deleted automatically.

New in version 2.69

Response example

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

Delete share

Deletes a share.

Preconditions

  • Share status must be available, error or inactive

  • You cannot already have a snapshot of the share.

  • You cannot already have a group snapshot of the share.

  • You cannot already have a replica of the share.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

Share export locations (since API v2.9)

Set of APIs used for viewing export locations of shares.

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

GET
/v2/shares/{share_id}/export_locations

List export locations

New in version 2.9.

Lists all export locations for a share.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

Response parameters

Name

In

Type

Description

id

body

string

The share export location UUID.

share_instance_id

body

string

The UUID of the share instance that this export location belongs to. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy.yaml.

path

body

string

The export location path that should be used for mount operation.

is_admin_only

body

boolean

Defines purpose of an export location. If set to true, then it is expected to be used for service needs and by administrators only. If it is set to false, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.

preferred

body

boolean

Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to false value.

New in version 2.14

Response example

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

Show single export location

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

path

body

string

The export location path that should be used for mount operation.

is_admin_only

body

boolean

Defines purpose of an export location. If set to true, then it is expected to be used for service needs and by administrators only. If it is set to false, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.

preferred

body

boolean

Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to false value.

New in version 2.14

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

Response example

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

Share metadata

Shows, sets, updates, and unsets share metadata.

GET
/v2/shares/{share_id}/metadata

Show all share metadata

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

Response parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

Response example

{
    "metadata": {
        "project": "my_app",
        "aim": "doc"
    }
}
GET
/v2/shares/{share_id}/metadata/{key}

Show share metadata item

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

key

body

object

The key of a metadata item. For example, if the metadata on an existing resource is as follows: "project": "my_test", "aim": "testing", the keys are “project” and “aim”.

Response parameters

Name

In

Type

Description

metadata

body

object

A single metadata key and value pair.

Response example

{
    "meta": {
        "project": "my_app"
    }
}
POST
/v2/shares/{share_id}/metadata

Set share metadata

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

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

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

key

body

object

The key of a metadata item. For example, if the metadata on an existing resource is as follows: "project": "my_test", "aim": "testing", the keys are “project” and “aim”.

Share actions

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

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

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

  • available

  • error

  • creating

  • deleting

  • error_deleting

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

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

POST
/v2/shares/{share_id}/action

Grant access

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

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

  • rw. Read and write (RW) access.

  • ro. Read-only (RO) access.

You must also specify one of these supported authentication methods:

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

Important

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

Note

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

  • cert. Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user. Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 255 characters long.

Grants access to a share.

Response codes

Success

Code

Reason

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

lock_visibility (Optional)

body

string

Whether the resource should have its sensitive fields restricted or not. When enabled, other users will see the “access_to” and “access_secret” fields set to **

New in version 2.82

lock_deletion (Optional)

body

string

Whether the resource should have its deletion locked or not.

New in version 2.82

lock_reason

body

string

A blob of text representing the reason for the specific resource lock.

Request example

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

Response parameters

Name

In

Type

Description

share_id

body

string

The UUID of the share to which you are granted or denied access.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

access_type

body

string

The access rule type. A valid value for the share access rule type is one of the following values:

  • ip: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example 0.0.0.0/0 for IPv4 or ::/0 for IPv6.

  • cert: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_to

body

string

The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values:

  • ip: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example 0.0.0.0/0 for IPv4 or ::/0 for IPv6.

  • cert: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_key

body

string

The access credential of the entity granted share access.

New in version 2.21

access

body

object

The access object.

access_level

body

string

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

  • rw. Read and write (RW) access.

  • ro. Read-only (RO) access.

id

body

string

The access rule ID.

metadata

body

object

One or more access rule metadata key and value pairs as a dictionary of strings.

Response example

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

Revoke access

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

Note

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

deny_access

body

object

The deny_access object.

access_id

body

string

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

unrestrict (Optional)

body

string

Whether the service should attempt to remove deletion restrictions during the access rule deletion or not.

New in version 2.82

Request example

{
    "deny_access": {
        "access_id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452",
        "unrestrict": true
    }
}
POST
/v2/shares/{share_id}/action

List access rules (DEPRECATED)

Warning

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

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

access_list

body

string

The object of the access rule. To list access rules, set this value to null.

Request example

{
    "access_list": null
}

Response parameters

Name

In

Type

Description

access_type

body

string

The access rule type. A valid value for the share access rule type is one of the following values:

  • ip: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example 0.0.0.0/0 for IPv4 or ::/0 for IPv6.

  • cert: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_key

body

string

The access credential of the entity granted share access.

New in version 2.21

access_to

body

string

The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values:

  • ip: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example 0.0.0.0/0 for IPv4 or ::/0 for IPv6.

  • cert: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_level

body

string

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

  • rw. Read and write (RW) access.

  • ro. Read-only (RO) access.

state

body

string

Prior to versions 2.28, the state of all access rules of a given share is the same at all times. This could be new, active or error. Since 2.28, the state of each access rule of a share is independent of the others and can be queued_to_apply, applying, active, error, queued_to_deny or denying. A new rule starts out in queued_to_apply state and is successfully applied if it transitions to active state.

access_list

body

string

The object of the access rule. To list access rules, set this value to null.

id

body

string

The access rule ID.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

Response example

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

Reset share state

Administrator only. Explicitly updates the state of a share.

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

reset_status

body

object

The reset_status object.

status

body

string

The share or share instance status to be set. Possible values are listed in the section above.

Request example

{
    "reset_status": {
        "status": "error"
    }
}
POST
/v2/shares/{share_id}/action

Force-delete share

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

force_delete

body

string

To force-delete a share or share group, set this value to null. The force-delete action, unlike the delete action, ignores the share or share group status.

Request example

{
    "force_delete": null
}
POST
/v2/shares/{share_id}/action

Extend share

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

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)

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.yaml file to grant permissions for this action to other roles.

Preconditions:

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

Note

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

unmanage

body

string

To unmanage a share, set this value to null.

Request example

{
    "unmanage": null
}

Response parameters

There is no body content for the response.

POST
/v2/shares/{share_id}/action

Revert share to snapshot (since API v2.27)

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"
    }
}
POST
/v2/shares/{share_id}/action

Soft delete share (since API v2.69)

New in version 2.69.

Soft delete a share to recycle bin.

Preconditions

  • Share status must be available, error or inactive

  • Share can’t have any snapshot.

  • Share can’t have a share group snapshot.

  • Share can’t have dependent replicas.

  • You cannot soft delete share that already is in the Recycle Bin..

  • You cannot soft delete a share that doesn’t belong to your project.

  • You cannot soft delete a share is busy with an active task.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

Request example

{
    "soft_delete": null
}
POST
/v2/shares/{share_id}/action

Restore share (since API v2.69)

New in version 2.69.

Restore a share from recycle bin.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

Request example

{
    "restore": null
}

Share snapshots

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

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

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

  • available

  • error

  • creating

  • deleting

  • error_deleting

  • manage_starting

  • manage_error

  • unmanage_starting

  • unmanage_error

  • restoring

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

GET
/v2/snapshots

List share snapshots

Lists all share snapshots.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

description~ (Optional)

query

string

The description pattern that can be used to filter shares, share snapshots, share networks or share groups.

New in version 2.36

with_count (Optional)

query

boolean

Whether to show count in share snapshot list API response or not, default is False. This query parameter is useful with pagination.

New in version 2.79

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the snapshot.

name

body

string

The user defined name of the resource.

Response example

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

List share snapshots with details

Lists all share snapshots with details.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

description~ (Optional)

query

string

The description pattern that can be used to filter shares, share snapshots, share networks or share groups.

New in version 2.36

with_count (Optional)

query

boolean

Whether to show count in share snapshot list API response or not, default is False. This query parameter is useful with pagination.

New in version 2.79

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the snapshot.

status

body

string

The snapshot status, which can be available, error, creating, deleting, manage_starting, manage_error, unmanage_starting, unmanage_error or error_deleting.

share_id

body

string

The UUID of the source share that was used to create the snapshot.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

share_proto

body

string

The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS or MAPRFS. CephFS is supported starting with API v2.13.

share_size

body

integer

The share snapshot size, in GiBs.

size

body

integer

The snapshot size, in GiBs.

project_id

body

string

ID of the project that the snapshot belongs to.

New in version 2.17

user_id

body

string

ID of the user that the snapshot was created by.

New in version 2.17

provider_location (Optional)

body

string

Provider location of the snapshot on the backend. This parameter is only available to users with an “administrator” role by virtue of default RBAC. This behavior can be modified by overriding the context_is_admin policy via a custom policy.yaml.

New in version 2.12

Response example

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

Show share snapshot details

Shows details for a share snapshot.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_id

path

string

The UUID of the snapshot.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the snapshot.

status

body

string

The snapshot status, which can be available, error, creating, deleting, manage_starting, manage_error, unmanage_starting, unmanage_error or error_deleting.

share_id

body

string

The UUID of the source share that was used to create the snapshot.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

share_proto

body

string

The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS or MAPRFS. CephFS is supported starting with API v2.13.

share_size

body

integer

The share snapshot size, in GiBs.

size

body

integer

The snapshot size, in GiBs.

project_id

body

string

ID of the project that the snapshot belongs to.

New in version 2.17

user_id

body

string

ID of the user that the snapshot was created by.

New in version 2.17

provider_location (Optional)

body

string

Provider location of the snapshot on the backend. This parameter is only available to users with an “administrator” role by virtue of default RBAC. This behavior can be modified by overriding the context_is_admin policy via a custom policy.yaml.

New in version 2.12

Response example

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

Create share snapshot

Creates a snapshot from a share.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

body

string

The UUID of the share from which to create a snapshot.

force (Optional)

body

boolean

Indicates whether snapshot creation must be attempted when a share’s status is not available. Set to true to force snapshot creation when the share is busy performing other operations. Default is false.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

display_name (Optional)

body

string

The user defined name of the resource. This field sets the name parameter.

display_description (Optional)

body

string

The user defined description of the resource. This field sets the description parameter.

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the snapshot.

share_id

body

string

The UUID of the source share that was used to create the snapshot.

status

body

string

The snapshot status, which can be available, error, creating, deleting, manage_starting, manage_error, unmanage_starting, unmanage_error or error_deleting.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

share_proto

body

string

The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS or MAPRFS. CephFS is supported starting with API v2.13.

share_size

body

integer

The share snapshot size, in GiBs.

provider_location (Optional)

body

string

Provider location of the snapshot on the backend. This parameter is only available to users with an “administrator” role by virtue of default RBAC. This behavior can be modified by overriding the context_is_admin policy via a custom policy.yaml.

New in version 2.12

size

body

integer

The snapshot size, in GiBs.

project_id

body

string

ID of the project that the snapshot belongs to.

New in version 2.17

user_id

body

string

ID of the user that the snapshot was created by.

New in version 2.17

Response example

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

Manage share snapshot (since API v2.12)

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)

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

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_id

path

string

The UUID of the snapshot.

status (Optional)

body

string

The snapshot status, which can be available, error, creating, deleting, manage_starting, manage_error, unmanage_starting, unmanage_error or error_deleting.

Request example

{
    "reset_status": {
        "status": "error"
    }
}
POST
/v2/snapshots/{snapshot_id}/action

Force-delete share snapshot

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_id

path

string

The UUID of the snapshot.

force_delete

body

string

To force-delete a snapshot, include this param and set its value to null. The force-delete action, unlike the delete action, ignores the snapshot status.

Request example

{
    "force_delete": null
}
PUT
/v2/snapshots/{snapshot_id}

Update share snapshot

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

Deletes a share snapshot.

Preconditions

  • Share snapshot status must be available or error.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_id

path

string

The UUID of the snapshot.

Snapshot metadata (Since API v2.73)

Shows, sets, updates, and unsets snapshot metadata.

GET
/v2/snapshots/{snapshot_id}/metadata

Show all snapshot metadata

New in version 2.73.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_id

path

string

The UUID of the snapshot.

Response parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

Response example

{
    "metadata": {
        "project": "my_app",
        "aim": "doc"
    }
}
GET
/v2/snapshots/{snapshot_id}/metadata/{key}

Show snapshot metadata item

New in version 2.73.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_id

path

string

The UUID of the snapshot.

key (Optional)

path

string

The key of a metadata item. For example, if the metadata on an existing share or access rule is as follows: "project": "my_test", "aim": "testing", the keys are “project” and “aim”.

Response parameters

Name

In

Type

Description

metadata

body

object

A single metadata key and value pair.

Response example

{
    "meta": {
        "project": "my_app"
    }
}
POST
/v2/snapshots/{snapshot_id}/metadata

Set snapshot metadata

New in version 2.73.

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

snapshot_id

path

string

The UUID of the snapshot.

metadata

body

object

One or more metadata key-value pairs, as a dictionary of strings. For example, "project": "my_test", "aim": "testing". The share server does not respect case-sensitive key names. For example, "key": "v1" and "KEY": "V1" are equivalent. If you specify both key-value pairs, the server sets and returns only the "KEY": "V1" key-value pair.

Request example

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

Response parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

Response example

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "key1": "value1",
        "new_metadata_key": "new_information",
        "key": "value"
    }
}
PUT
/v2/snapshots/{snapshot_id}/metadata

Update snapshot metadata

New in version 2.73.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_id

path

string

The UUID of the snapshot.

metadata

body

object

One or more metadata key-value pairs, as a dictionary of strings. For example, "project": "my_test", "aim": "testing". The share server does not respect case-sensitive key names. For example, "key": "v1" and "KEY": "V1" are equivalent. If you specify both key-value pairs, the server sets and returns only the "KEY": "V1" key-value pair.

Request example

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

Response parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

Response example

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

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

Request example

{
    "metadata": null
}

Response example

{
    "metadata": null
}
DELETE
/v2/snapshots/{snapshot_id}/metadata/{key}

Delete snapshot metadata item

New in version 2.73.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_id

path

string

The UUID of the snapshot.

key (Optional)

path

string

The key of a metadata item. For example, if the metadata on an existing share or access rule is as follows: "project": "my_test", "aim": "testing", the keys are “project” and “aim”.

Share snapshot instances (since API v2.19)

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

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

GET
/v2/snapshot-instances

List share snapshot instances

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

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

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

New in version 2.19.

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

snapshot_instance_id

path

string

The UUID of the share snapshot instance.

status

body

string

The snapshot instance status. A valid value is available, error, creating, deleting, and error_deleting, restoring, unmanage_starting, unmanage_error, manage_starting, manage_error.

Request example

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

Share replicas (since API v2.11)

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

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

Note

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

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

  • writable

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

  • readable

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

  • dr (for Disaster Recovery)

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

Important

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

POST
/v2/share-replicas

Create share replica

New in version 2.11.

Create a share replica for the share.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

body

string

The UUID of the share from which to create a share replica.

availability_zone (Optional)

body

string

The availability zone.

share_network_id (Optional)

body

string

The UUID of the share network.

scheduler_hints (Optional)

body

object

One or more scheduler_hints key and value pairs as a dictionary of strings. Accepted hints are: - only_host: value must be a share manager service host in host@backend#POOL format (admin only)

New in version 2.67

Request example

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

Note

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

Response parameters

Name

In

Type

Description

share_id

body

string

The UUID of the share from which to create a share replica.

status

body

string

The status of a share replica. List of possible values: available, error, creating, deleting, or error_deleting.

cast_rules_to_readonly

body

boolean

If the share replica has its cast_rules_to_readonly attribute set to True, all existing access rules will be cast to read/only.

New in version 2.30

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

share_network_id

body

string

The share network ID where the resource is exported to.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the share replica.

id

body

string

The UUID of the share replica.

replica_state

body

string

The replica state of a share replica. List of possible values: active, in_sync, out_of_sync, and error.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

Response example

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

Promote share replica

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.

quiesce_wait_time (Optional)

body

integer

The quiesce wait time in seconds used during replica promote.

New in version 2.75

Request example

{
    "promote": {
        "quiesce_wait_time": 30
    }
}
POST
/v2/share-replicas/{share_replica_id}/action

Resync share replica

New in version 2.11.

Resync a replica with its active mirror.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_replica_id

path

string

The UUID of the share replica.

Request example

{
    "resync": null
}
GET
/v2/share-replicas?share_id={share_id}

List share replicas

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

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

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

New in version 2.11.

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_replica_id

path

string

The UUID of the share replica.

reset_status

body

object

The reset_status object.

status

body

string

The status of a share replica. List of possible values: available, error, creating, deleting, or error_deleting.

Request example

{
    "reset_status": {
        "status": "available"
    }
}
POST
/v2/share-replicas/{share_replica_id}/action

Reset replica_state of the share replica

New in version 2.11.

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_replica_id

path

string

The UUID of the share replica.

reset_replica_state

body

object

The reset_replica_state object.

replica_state

body

string

The replica state of a share replica. List of possible values: active, in_sync, out_of_sync, and error.

Request example

{
    "reset_replica_state": {
        "replica_state": "out_of_sync"
    }
}
DELETE
/v2/share-replicas/{share_replica_id}

Delete share replica

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

New in version 2.11.

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Note

The active replica cannot be deleted with this API.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_replica_id

path

string

The UUID of the share replica.

force_delete

body

string

To force-delete a share replica, set this value to null. The force-delete action, unlike the delete action, ignores the share replica status.

Request example

{
    "force_delete": null
}

Share replica export locations (since API v2.47)

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

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

List export locations

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

path

body

string

The export location path that should be used for mount operation.

is_admin_only

body

boolean

Defines purpose of an export location. If set to true, then it is expected to be used for service needs and by administrators only. If it is set to false, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.

preferred

body

boolean

Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to false value.

availability_zone

body

string

The name of the availability zone that the export location belongs to.

replica_state

body

string

The replica state of a share replica. List of possible values: active, in_sync, out_of_sync, and error.

Response example

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

Show single export location

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

path

body

string

The export location path that should be used for mount operation.

is_admin_only

body

boolean

Defines purpose of an export location. If set to true, then it is expected to be used for service needs and by administrators only. If it is set to false, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.

preferred

body

boolean

Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to false value.

availability_zone

body

string

The name of the availability zone that the export location belongs to.

replica_state

body

string

The replica state of a share replica. List of possible values: active, in_sync, out_of_sync, and error.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

Response example

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

Share networks

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

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

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

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

A share network resource has these attributes:

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

  • The IP version of the network.

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

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

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

Note

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

GET
/v2/share-networks

List share networks

Lists all share networks.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

description~ (Optional)

query

string

The description pattern that can be used to filter shares, share snapshots, share networks or share groups.

New in version 2.36

name (Optional)

query

string

The user defined name of the resource to filter resources by.

description (Optional)

query

string

The user defined description text that can be used to filter resources.

created_since (Optional)

query

string

Search for the list of resources that were created after the specified date. The date is in ‘yyyy-mm-dd’ format.

created_before (Optional)

query

string

Search for the list of resources that were created prior to the specified date. The date is in ‘yyyy-mm-dd’ format.

security_service_id (Optional)

query

string

The security service ID to filter out share networks.

nova_net_id (Optional)

query

string

The ID of a Nova network to filter out share networks.

Available until version 2.26

neutron_net_id (Optional)

query

string

The neutron network id to filter out share networks.

neutron_subnet_id (Optional)

query

string

The neutron network subnet id to filter out share networks.

network_type (Optional)

query

string

The network type to filter out share networks.

segmentation_id (Optional)

query

string

The segmentation id to filter out share networks.

cidr (Optional)

query

string

The CIDR to filter share networks.

ip_version (Optional)

query

string

The IP version to filter share networks.

offset (Optional)

query

integer

The offset to define start point of resource listing.

limit (Optional)

query

integer

The maximum number of resource records to return.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of a share network resource.

name

body

string

The user defined name of the resource.

Response example

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

List share networks with details

Lists all share networks with details.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

description~ (Optional)

query

string

The description pattern that can be used to filter shares, share snapshots, share networks or share groups.

New in version 2.36

created_since (Optional)

query

string

Search for the list of resources that were created after the specified date. The date is in ‘yyyy-mm-dd’ format.

created_before (Optional)

query

string

Search for the list of resources that were created prior to the specified date. The date is in ‘yyyy-mm-dd’ format.

nova_net_id (Optional)

query

string

The ID of a Nova network to filter out share networks.

Available until version 2.26

neutron_net_id (Optional)

query

string

The neutron network id to filter out share networks.

neutron_subnet_id (Optional)

query

string

The neutron network subnet id to filter out share networks.

network_type (Optional)

query

string

The network type to filter out share networks.

segmentation_id (Optional)

query

string

The segmentation id to filter out share networks.

cidr (Optional)

query

string

The CIDR to filter share networks.

ip_version (Optional)

query

string

The IP version to filter share networks.

offset (Optional)

query

integer

The offset to define start point of resource listing.

limit (Optional)

query

integer

The maximum number of resource records to return.

security_service_id (Optional)

query

string

The security service ID to filter out share networks.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of a share network resource.

project_id

body

string

The ID of the project that owns the resource.

neutron_net_id

body

string

The neutron network ID.

Available until version 2.50

neutron_subnet_id

body

string

The neutron subnet ID.

Available until version 2.50

network_type

body

string

The network type. A valid value is VLAN, VXLAN, GRE, or flat. This parameter is automatically set to a value determined by the network provider.

Available until version 2.50

segmentation_id

body

integer

The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295.

Available until version 2.50

cidr

body

string

The IP block from which to allocate the network, in CIDR notation. For example, 172.16.0.0/24 or 2001:DB8::/64. This parameter is automatically set to a value determined by the network provider.

Available until version 2.50

ip_version

body

integer

The IP version of the network. A valid value is 4 or 6. This parameter is automatically set to a value determined by the network provider.

Available until version 2.50

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

gateway

body

string

The gateway of a share network.

New in version 2.18

Available until version 2.50

mtu

body

integer

The MTU value of a share network.

New in version 2.20

Available until version 2.50

share_network_subnets

body

array

A list of share network subnets that pertain to the related share network.

New in version 2.51

security_service_update_support

body

boolean

Whether the share network supports its security services being updated when it is already being used.

New in version 2.63

status

body

string

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

New in version 2.63

Response example

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

Note

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

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

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

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

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

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

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)

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)

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)

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)

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

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

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

New in version 2.51.

Creates a share network subnet in the given share network.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_network_id

path

string

The UUID of the share network.

neutron_net_id (Optional)

body

string

The UUID of a neutron network when setting up or updating a share network subnet with neutron. Specify both a neutron network and a neutron subnet that belongs to that neutron network.

neutron_subnet_id (Optional)

body

string

The UUID of the neutron subnet when setting up or updating a share network subnet with neutron. Specify both a neutron network and a neutron subnet that belongs to that neutron network.

availability_zone (Optional)

body

string

The UUID or name of an availability zone for resource to be created within.

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share network subnet.

neutron_net_id

body

string

The neutron network ID.

neutron_subnet_id

body

string

The neutron subnet ID.

network_type

body

string

The network type. A valid value is VLAN, VXLAN, GRE, or flat. This parameter is automatically set to a value determined by the network provider.

segmentation_id

body

integer

The segmentation ID. This parameter is automatically set to a value determined by the network provider. For VLAN, this value is an integer from 1 to 4094. For VXLAN, this value is an integer from 1 to 16777215. For GRE, this value is an integer from 1 to 4294967295.

cidr

body

string

The IP block from which to allocate the network, in CIDR notation. For example, 172.16.0.0/24 or 2001:DB8::/64. This parameter is automatically set to a value determined by the network provider.

ip_version

body

integer

The IP version of the network. A valid value is 4 or 6. This parameter is automatically set to a value determined by the network provider.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

gateway

body

string

The gateway of a share network subnet.

mtu

body

string

The MTU of a share network subnet.

availability_zone

body

string

The name of the availability zone that the share network subnet belongs to.

share_network_id

body

string

The UUID of the share network that the share network subnet belongs to.

share_network_name

body

string

The name of the share network that the share network subnet belongs to.

Response example

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

Delete share network subnet

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.

Share network subnets metadata (since API v2.78)

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

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

Show all share network subnets metadata

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_network_id

path

string

The UUID of the share network.

share_network_subnet_id

path

string

The UUID of the share network subnet.

Response parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

Response example

{
    "metadata": {
        "project": "my_app",
        "key": "value"
    }
}
GET
/v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata/{key}

Show share network subnet metadata item

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_network_id

path

string

The UUID of the share network.

share_network_subnet_id

path

string

The UUID of the share network subnet.

key

body

object

The key of a metadata item. For example, if the metadata on an existing resource is as follows: "project": "my_test", "aim": "testing", the keys are “project” and “aim”.

Response parameters

Name

In

Type

Description

meta

body

object

A single metadata key and value pair.

Response example

{
    "meta": {
        "project": "my_app"
    }
}
POST
/v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata

Set share network subnet metadata

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.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_network_id

path

string

The UUID of the share network.

share_network_subnet_id

path

string

The UUID of the share network subnet.

metadata

body

object

One or more metadata key-value pairs, as a dictionary of strings. For example, "project": "my_test", "aim": "testing". The share server does not respect case-sensitive key names. For example, "key": "v1" and "KEY": "V1" are equivalent. If you specify both key-value pairs, the server sets and returns only the "KEY": "V1" key-value pair.

Request example

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

Response parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

Response example

{
    "metadata": {
        "aim": "changed_doc",
        "project": "my_app",
        "key1": "value1",
        "new_metadata_key": "new_information",
        "key": "value"
    }
}
PUT
/v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata

Update share network subnet metadata

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_network_id

path

string

The UUID of the share network.

share_network_subnet_id

path

string

The UUID of the share network subnet.

metadata

body

object

One or more metadata key-value pairs, as a dictionary of strings. For example, "project": "my_test", "aim": "testing". The share server does not respect case-sensitive key names. For example, "key": "v1" and "KEY": "V1" are equivalent. If you specify both key-value pairs, the server sets and returns only the "KEY": "V1" key-value pair.

Request example

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

Response parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

Response example

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

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

Request example

{
    "metadata": null
}

Response example

{
    "metadata": null
}
DELETE
/v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata/{key}

Delete share network subnet metadata item

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_network_id

path

string

The UUID of the share network.

share_network_subnet_id

path

string

The UUID of the share network subnet.

key

body

object

The key of a metadata item. For example, if the metadata on an existing resource is as follows: "project": "my_test", "aim": "testing", the keys are “project” and “aim”.

Security services

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

The Shared File Systems service supports three security service types:

  • ldap. LDAP.

  • kerberos. Kerberos.

  • active_directory. Microsoft Active Directory.

You can configure a security service with these options:

  • A DNS IP address. Some drivers may allow a comma separated list of multiple addresses, e.g. NetApp ONTAP.

  • An IP address or host name.

  • A domain.

  • An ou, the organizational unit. (available starting with API version 2.44)

  • A user or group name.

  • The password for the user, if you specify a user name.

  • A default AD site, optional (available starting with API version 2.76)

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

GET
/v2/security-services

List security services

Lists all security services.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

type

body

string

The security service type. A valid value is ldap, kerberos, or active_directory.

id

body

string

The security service ID.

name

body

string

The user defined name of the resource.

Response example

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

List security services with details

Lists all security services with details.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

id

body

string

The security service ID.

project_id

body

string

The ID of the project that owns the resource.

type

body

string

The security service type. A valid value is ldap, kerberos, or active_directory.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

dns_ip

body

string

The DNS IP address that is used inside the project network.

user

body

string

The security service user or group name that is used by the project.

password

body

string

The user password, if you specify a user.

domain

body

string

The security service domain.

ou

body

string

The security service ou.

New in version 2.44

server

body

string

The security service host name or IP address.

default_ad_site

body

string

The security service default AD site.

New in version 2.76

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

Response example

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

Show security service details

Shows details for a security service.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

security_service_id

path

string

The UUID of the security service.

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

id

body

string

The security service ID.

project_id

body

string

The ID of the project that owns the resource.

type

body

string

The security service type. A valid value is ldap, kerberos, or active_directory.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

dns_ip

body

string

The DNS IP address that is used inside the project network.

user

body

string

The security service user or group name that is used by the project.

password

body

string

The user password, if you specify a user.

domain

body

string

The security service domain.

ou

body

string

The security service ou.

New in version 2.44

server

body

string

The security service host name or IP address.

default_ad_site

body

string

The security service default AD site.

New in version 2.76

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

Response example

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

Create security service

Creates a security service.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

type

body

string

The security service type. A valid value is ldap, kerberos, or active_directory.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

dns_ip (Optional)

body

string

The DNS IP address that is used inside the project network.

user (Optional)

body

string

The security service user or group name that is used by the project.

password (Optional)

body

string

The user password, if you specify a user.

domain (Optional)

body

string

The security service domain.

ou (Optional)

body

string

The security service ou. An organizational unit can be added to specify where the share ends up.

New in version 2.44

server (Optional)

body

string

The security service host name or IP address.

default_ad_site (Optional)

body

string

The security service default AD site.

New in version 2.76

Request example

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

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

id

body

string

The security service ID.

project_id

body

string

The ID of the project that owns the resource.

type

body

string

The security service type. A valid value is ldap, kerberos, or active_directory.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

dns_ip

body

string

The DNS IP address that is used inside the project network.

user

body

string

The security service user or group name that is used by the project.

password

body

string

The user password, if you specify a user.

domain

body

string

The security service domain.

ou

body

string

The security service ou.

New in version 2.44

server

body

string

The security service host name or IP address.

default_ad_site

body

string

The security service default AD site.

New in version 2.76

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

Response example

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

Update security service

Updates a security service.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

security_service_id

path

string

The UUID of the security service.

type

body

string

The security service type. A valid value is ldap, kerberos, or active_directory.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

dns_ip (Optional)

body

string

The DNS IP address that is used inside the project network.

user (Optional)

body

string

The security service user or group name that is used by the project.

password (Optional)

body

string

The user password, if you specify a user.

domain (Optional)

body

string

The security service domain.

ou (Optional)

body

string

The security service ou. An organizational unit can be added to specify where the share ends up.

New in version 2.44

server (Optional)

body

string

The security service host name or IP address.

default_ad_site (Optional)

body

string

The security service default AD site.

New in version 2.76

Request example

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

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

id

body

string

The security service ID.

project_id

body

string

The ID of the project that owns the resource.

type

body

string

The security service type. A valid value is ldap, kerberos, or active_directory.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

dns_ip

body

string

The DNS IP address that is used inside the project network.

user

body

string

The security service user or group name that is used by the project.

password

body

string

The user password, if you specify a user.

domain

body

string

The security service domain.

ou

body

string

The security service ou.

New in version 2.44

server

body

string

The security service host name or IP address.

default_ad_site

body

string

The security service default AD site.

New in version 2.76

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

Response example

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

Delete security service

Deletes a security service.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

security_service_id

path

string

The UUID of the security service.

Share servers

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

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

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

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

The possible share servers statuses are:

Share server statuses

Status

Description

active

Share server was successfully set up.

error

The set up or deletion of the share server failed.

deleting

The share server has no dependent shares and is being deleted.

creating

The share server is being created on the back end with data from the database.

GET
/v2/share-servers

List share servers

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

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

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

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)

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)

New in version 2.49.

Unmanages a share server

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

Preconditions

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

404 - Not Found

The requested resource could not be found.

Request parameters

Name

In

Type

Description

project_id (Optional)

path

string

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

share_server_id

body

string

The UUID of the share server.

force (Optional)

body

boolean

Indicates whether to permit or deny the force- update of a quota that is already used and the requested value exceeds the configured quota. Set to True to permit the force-update of the quota. Set to False to deny the force- update of the quota.

unmanage

body

object

To unmanage a share server, either set this value to null or {}. Optionally, the force attribute can be included in this object.

Request example

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

Response parameters

There is no body content for the response.

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

Reset status (since API v2.49)

New in version 2.49.

Resets a share server status

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

404 - Not Found

The requested resource could not be found.

Request parameters

Name

In

Type

Description

project_id (Optional)

path

string

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

share_server_id

body

string

The UUID of the share server.

status

body

string

The share server status, which can be active, error, creating, deleting, manage_starting, manage_error, unmanage_starting, unmanage_error or error_deleting.

Request example

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

Response parameters

There is no body content for the response.

Share instances (since API v2.3)

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

GET
/v2/share_instances

List share instances

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.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

replica_state

body

string

The share replica state. Has set value only when replication is used. List of possible values: active, in_sync, out_of_sync, and error.

New in version 2.11

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

cast_rules_to_readonly

body

boolean

If the share instance has its cast_rules_to_readonly attribute set to True, all existing access rules will be cast to read/only.

New in version 2.30

share_network_id

body

string

The share network ID where the resource is exported to.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

access_rules_status

body

string

The share instance access rules status. A valid value is active, error, or syncing. In versions prior to 2.28, syncing was represented with status out_of_sync.

New in version 2.10

share_type_id

path

string

The UUID of the share type.

id

body

string

The share instance ID.

Response example

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

Show share instance details

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.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

replica_state

body

string

The share replica state. Has set value only when replication is used. List of possible values: active, in_sync, out_of_sync, and error.

New in version 2.11

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

cast_rules_to_readonly

body

boolean

If the share instance has its cast_rules_to_readonly attribute set to True, all existing access rules will be cast to read/only.

New in version 2.30

share_network_id

body

string

The share network ID where the resource is exported to.

share_server_id

body

string

The UUID of the share server.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

id

body

string

The share instance ID.

Response example

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

Reset share instance state

New in version 2.3.

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_instance_id

path

string

The UUID of the share instance.

status

body

string

The share or share instance status to be set. Possible values are listed in the section above.

Request example

{
    "reset_status": {
        "status": "available"
    }
}
POST
/v2/share_instances/{share_instance_id}/action

Force-delete share instance

New in version 2.3.

Administrator only. Force-deletes a share instance.

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_instance_id

path

string

The UUID of the share instance.

force_delete

body

string

To force-delete a share instance, set this value to null. The force-delete action, unlike the delete action, ignores the share instance status.

Request example

{
    "force_delete": null
}

Share instance export locations (since API v2.9)

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

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

Lists all export locations for a share instance.

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

GET
/v2/share_instances/{share_instance_id}/export_locations

List export locations

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

path

body

string

The export location path that should be used for mount operation.

is_admin_only

body

boolean

Defines purpose of an export location. If set to true, then it is expected to be used for service needs and by administrators only. If it is set to false, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.

preferred

body

boolean

Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to false value.

New in version 2.14

Response example

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

Show single export location

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

path

body

string

The export location path that should be used for mount operation.

is_admin_only

body

boolean

Defines purpose of an export location. If set to true, then it is expected to be used for service needs and by administrators only. If it is set to false, then this export location can be used by end users. This parameter is only available to users with an “administrator” role, and cannot be controlled via policy .json.

preferred

body

boolean

Drivers may use this field to identify which export locations are most efficient and should be used preferentially by clients. By default it is set to false value.

New in version 2.14

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

Response example

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

Share types

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

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

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

Important

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

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

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

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

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

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

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

    Set to False when an administrator rather than a share driver manages the share server life cycle.

  • snapshot_support. Filters back ends by whether they do or do not support share snapshots.

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

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

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

  • Filter back ends. Specify these unqualified extra specifications in this format: extra_spec=value. For example, netapp_raid_type=raid4.

  • Set data for the driver. Except for the special capabilities prefix, you specify these qualified extra specifications with its prefix followed by a colon: vendor:extra_spec=value. For example, netapp:thin_provisioned=true.

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

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

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

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

List share types

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

Lists default share types.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share type.

required_extra_specs

body

object

The required extra specifications for the share type: driver_handles_share_servers. snapshot_support was treated as a required extra-specification until api version 2.24.

extra_specs

body

object

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

share_type_access:is_public

body

boolean

Indicates whether a share type is accessible by all projects (tenants) in the cloud.

name

body

string

Name of the share type.

description

body

string

The description of the share type.

New in version 2.41

is_default

body

boolean

Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

New in version 2.46

Response example

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

Show share type detail

Shows details for a specified share type.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the share type.

required_extra_specs

body

object

The required extra specifications for the share type: driver_handles_share_servers. snapshot_support was treated as a required extra-specification until api version 2.24.

extra_specs

body

object

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

share_type_access:is_public

body

boolean

Indicates whether a share type is accessible by all projects (tenants) in the cloud.

name

body

string

Name of the share type.

description

body

string

The description of the share type.

New in version 2.41

is_default

body

boolean

Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

New in version 2.46

Response Example

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

List extra specs

Lists the extra specifications for a share type.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

Response parameters

Name

In

Type

Description

extra_specs

body

object

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

Response example

{
    "extra_specs": {
        "replication_type": "readable",
        "driver_handles_share_servers": "True",
        "create_share_from_snapshot_support": "True",
        "revert_to_snapshot_support": "False",
        "mount_snapshot_support": "False",
        "snapshot_support": "True"
    }
}
POST
/v2/types

Create share type

Creates a share type.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

extra_specs

body

object

Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. When creating a new share type, required extra-specifications must be provided. driver_handles_share_servers is a required extra-specification, and snapshot_support was considered a required extra-specification until API version 2.24. When updating extra-specs of a share type, there’s no need to provide required extra specifications unless they need to be updated. Some examples of extra-specifications include: replication_type, snapshot_support, mount_snapshot_support, revert_to_snapshot_support, create_share_from_snapshot_support

os-share-type-access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

Available until version 2.6

name

body

string

Name of the share type.

description (Optional)

body

string

The description of the share type. The value of this field is limited to 255 characters.

New in version 2.41

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share type.

required_extra_specs

body

object

The required extra specifications for the share type: driver_handles_share_servers. snapshot_support was treated as a required extra-specification until api version 2.24.

extra_specs

body

object

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

os-share-type-access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

Available until version 2.6

share_type_access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

New in version 2.7

name

body

string

Name of the share type.

description

body

string

The description of the share type.

New in version 2.41

is_default

body

boolean

Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

New in version 2.46

Response example

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

Show share type access details

Shows access details for a share type.

You can view access details for private share types only.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

Response parameters

Name

In

Type

Description

project_id

body

string

The ID of the project that has been granted access to the type resource.

share_type_id

body

string

The UUID of the share type.

Response example

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

Set extra spec for share type

Sets an extra specification for the share type.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

extra_specs

body

object

Extra specifications of the share type. These are key=value pairs of capabilities that the shares of this type are expected to possess. For more information, see Share Types. When creating a new share type, required extra-specifications must be provided. driver_handles_share_servers is a required extra-specification, and snapshot_support was considered a required extra-specification until API version 2.24. When updating extra-specs of a share type, there’s no need to provide required extra specifications unless they need to be updated. Some examples of extra-specifications include: replication_type, snapshot_support, mount_snapshot_support, revert_to_snapshot_support, create_share_from_snapshot_support

Request example

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

Response parameters

Name

In

Type

Description

extra_specs

body

object

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

Response example

{
    "extra_specs": {
        "my_key": "my_value"
    }
}
DELETE
/v2/types/{share_type_id}/extra_specs/{extra-spec-key}

Unset an extra spec

Unsets an extra specification for the share type.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

extra-spec-key

path

string

The extra specification key

POST
/v2/types/{share_type_id}/action

Add share type access

Adds share type access for a project.

You can add access to private share types only.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

addProjectAccess

body

object

An object representing the project resource that access should be granted to.

project

body

string

The ID of the project that needs to have access to the type resource.

Request example

{
    "addProjectAccess": {
        "project": "e1284adea3ee4d2482af5ed214f3ad90"
    }
}
POST
/v2/types/{share_type_id}/action

Remove share type access

Removes share type access from a project.

You can remove access from private share types only.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

removeProjectAccess

body

object

An object representing the project resource that access should be revoked from.

project

body

string

The ID of the project whose access to the type resource must be revoked.

Request example

{
    "removeProjectAccess": {
        "project": "818a3f48dcd644909b3fa2e45a399a27"
    }
}
DELETE
/v2/types/{share_type_id}

Delete share type

Deletes a share type.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

PUT
/v2/types/{share_type_id}

Update share type (since API v2.50)

New in version 2.50.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_type_id

path

string

The UUID of the share type.

name (Optional)

body

string

Name of the share type. The value of this field is limited to 255 characters.

share_type_access:is_public (Optional)

body

boolean

Indicates whether the share type should be accessible by all projects (tenants) in the cloud. If not specified, the visibility of the share type is not altered.

description (Optional)

body

string

New description for the share type.

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share type.

required_extra_specs

body

object

The required extra specifications for the share type: driver_handles_share_servers. snapshot_support was treated as a required extra-specification until api version 2.24.

extra_specs

body

object

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

share_type_access:is_public

body

boolean

Indicates whether a share type is accessible by all projects (tenants) in the cloud.

name

body

string

Name of the share type.

description

body

string

The description of the share type.

is_default

body

boolean

Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

Response example

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

Scheduler Stats - Storage Pools

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

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

List back-end storage pools

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

pool_name (Optional)

query

string

The pool name for the back end.

host_name (Optional)

query

string

The host name for the back end.

backend_name (Optional)

query

string

The name of the back end.

capabilities (Optional)

query

string

The capabilities for the storage back end.

share_type (Optional)

query

string

The share type name or UUID. Allows filtering back end pools based on the extra-specs in the share type.

New in version 2.23

Response parameters

Name

In

Type

Description

backend

body

string

The name of the back end.

host

body

string

The host name for the back end.

pool

body

string

The pool name for the back end.

name

body

string

The name of the back end in this format: host@backend#POOL:

  • host. The host name for the back end.

  • backend. The name of the back end.

  • POOL. The pool name for the back end.

Response example

{
  "pools": [
    {
      "name": "opencloud@alpha#ALPHA_pool",
      "host": "opencloud",
      "backend": "alpha",
      "pool": "ALPHA_pool"
    },
    {
      "name": "opencloud@beta#BETA_pool",
      "host": "opencloud",
      "backend": "beta",
      "pool": "BETA_pool"
    },
    {
      "name": "opencloud@gamma#GAMMA_pool",
      "host": "opencloud",
      "backend": "gamma",
      "pool": "GAMMA_pool"
    },
    {
      "name": "opencloud@delta#DELTA_pool",
      "host": "opencloud",
      "backend": "delta",
      "pool": "DELTA_pool"
    }
  ]
}
GET
/v2/scheduler-stats/pools/detail?pool={pool_name}&host={host_name}&backend={backend_name}&capabilities={capabilities}&share_type={share_type}

List back-end storage pools with details

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

pool_name (Optional)

query

string

The pool name for the back end.

host_name (Optional)

query

string

The host name for the back end.

backend_name (Optional)

query

string

The name of the back end.

capabilities (Optional)

query

string

The capabilities for the storage back end.

share_type (Optional)

query

string

The share type name or UUID. Allows filtering back end pools based on the extra-specs in the share type.

New in version 2.23

Response parameters

Name

In

Type

Description

pools

body

string

The pools for the back end. This value is either null or a string value that indicates the capabilities for each pool. For example, pool_name, total_capacity_gb, qos, and so on.

name

body

string

The name of the back end in this format: host@backend#POOL:

  • host. The host name for the back end.

  • backend. The name of the back end.

  • POOL. The pool name for the back end.

backend

body

string

The name of the back end.

pool

body

string

The pool name for the back end.

host

body

string

The host name for the back end.

capabilities

body

object

The back end capabilities which include qos, total_capacity_gb, etc.

qos

body

boolean

The quality of service (QoS) support.

timestamp

body

string

The date and time stamp when the API request was issued.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

share_backend_name

body

string

The name of the share back end.

server_pools_mapping

body

object

The mapping between servers and pools.

driver_handles_share_servers

body

boolean

Share server is usually a storage virtual machine or a lightweight container that is used to export shared file systems. Storage backends may be able to work with configured share servers or allow the share driver to create and manage the lifecycle of share servers. This capability specifies whether the pool’s associated share driver is responsible to create and manage the lifecycle of share servers. If false, the administrator of the shared file systems service has configured the share server as necessary for the given back end.

driver_version

body

string

The driver version of the back end.

total_capacity_gb

body

string

The total capacity for the back end, in GiBs. A valid value is a string, such as unknown, or an integer.

free_capacity_gb

body

string

The amount of free capacity for the back end, in GiBs. A valid value is a string, such as unknown, or an integer.

reserved_percentage

body

integer

The percentage of the total capacity that is reserved for the internal use by the back end.

vendor_name

body

string

The name of the vendor for the back end.

snapshot_support

body

boolean

The specification that filters back ends by whether they do or do not support share snapshots.

replication_domain

body

string

The back end replication domain.

storage_protocol

body

string

The storage protocol for the back end. For example, NFS_CIFS, glusterfs, HDFS, etc.

Response example

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

Services

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

Important

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

Note

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

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

List services

Lists all services optionally filtered with the specified search options.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

host (Optional)

query

string

The service host name.

binary (Optional)

query

string

The service binary name. Default is the base name of the executable.

zone (Optional)

query

string

The availability zone.

state (Optional)

query

string

The current state of the service. A valid value is up or down.

status (Optional)

query

string

The service status, which is enabled or disabled.

Response parameters

Name

In

Type

Description

services

body

string

Top element in the response body.

id

body

integer

The service ID.

status

body

string

The service status, which is enabled or disabled.

binary

body

string

The service binary name. Default is the base name of the executable.

zone

body

string

The service availability zone.

host

body

string

The service host name.

state

body

string

The current state of the service. A valid value is up or down.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

disabled_reason

body

string

A reason for the service being disabled.

New in version 2.83

Response example

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

Enable service

Enables a service.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

binary

body

string

The name of the service binary that you want to enable. Typically, this name is the base name of the executable.

host

body

string

The host name of the service that you want to enable.

Request example

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

Response parameters

Name

In

Type

Description

host

body

string

The host name of the enabled service.

binary

body

string

The service binary name. Default is the base name of the executable.

disabled

body

boolean

Indicates whether the service is disabled.

Available until version 2.82

status

body

string

The service status, which is enabled or disabled.

New in version 2.83

disabled_reason

body

string

A reason for the service being disabled.

New in version 2.83

Response example

{
    "binary": "manila-share",
    "host": "openstackhost@generic#pool_0",
    "status": "enabled",
    "disabled_reason": ""
}
PUT
/v2/services/disable

Disable service

Disables a service.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

binary

body

string

The name of the service binary that you want to disable. Typically, this name is the base name of the executable.

host

body

string

The host name of the service that you want to disable.

disabled_reason (Optional)

body

string

A reason for the service being disabled.

New in version 2.83

Request example

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

Response parameters

Name

In

Type

Description

host

body

string

The host name of the disabled service.

binary

body

string

The name of the disabled service binary. Typically, this name is the base name of the executable.

disabled

body

boolean

Indicates whether the service is disabled.

Available until version 2.82

status

body

string

The service status, which is enabled or disabled.

New in version 2.83

disabled_reason

body

string

A reason for the service being disabled.

New in version 2.83

Response example

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

Availability zones

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

Important

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

GET
/v2/availability-zones

List availability zones

Lists all availability zones.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

Response parameters

Name

In

Type

Description

availability_zones

body

string

Top level response body element.

id

body

string

The availability zone ID the resource exists within.

name

body

string

The name of the availability zone.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

Response example

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

Manage and unmanage shares (DEPRECATED)

Allows bringing shared file systems under service management.

POST
/v2/os-share-manage

Manage share (DEPRECATED)

Warning

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

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

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share

body

object

A share object.

protocol

body

string

The Shared File Systems protocol of the share to manage. A valid value is NFS, CIFS, GlusterFS, CEPHFS, HDFS or MAPRFS.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

display_name (Optional)

body

string

The user defined name of the resource. This field sets the name parameter.

share_type (Optional)

body

string

The name or ID of the share type to be used to create the resource. If you omit this parameter, the default share type is used. To view the default share type set by the administrator, issue a list default share types request.

driver_options (Optional)

body

object

A set of one or more key and value pairs, as a dictionary of strings, that describe driver options. Details for driver options should be taken from appropriate share driver documentation.

export_path

body

string

The share export path in the format appropriate for the protocol:

  • NFS protocol. 10.0.0.1:/foo_path. For example, 10.254.0 .5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5.

  • CIFS protocol. For example, \\10.0.0.1\foo_name_of_cifs_share.

service_host

body

string

The manage-share service host in this format: host@backend#POOL:

  • host. The host name for the back end.

  • backend. The name of the back end.

  • POOL. The pool name for the back end.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

display_description (Optional)

body

string

The user defined description of the resource. This field sets the description parameter.

Request example

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

Response parameters

Name

In

Type

Description

share

body

object

A share object.

links

body

array

Pagination and bookmark links for the resource.

availability_zone

body

string

The name of the availability zone the share exists within.

share_network_id

body

string

The share network ID where the resource is exported to.

export_locations

body

array

A list of export locations. For example, when a share server has more than one network interface, it can have multiple export locations. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

share_server_id

body

string

The UUID of the share server.

snapshot_id

body

string

The UUID of the snapshot that was used to create the share.

id

body

string

The UUID of the share.

size

body

integer

The share size, in GiBs.

share_type

body

string

The UUID of the share type that the share belongs to. Prior to API version 2.6, this parameter resolved to the name of the share type. In API version 2.6 and beyond, this parameter holds the share type ID instead of the name.

share_type_name

body

string

Name of the share type.

export_location

body

string

The export location. For newer API versions it is available in separate APIs. See sections Share export locations and Share instance export locations.

Available until version 2.8

project_id

body

string

The ID of the project that owns the resource.

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

status

body

string

The share or share instance status. Possible values are listed in the section above.

description

body

string

The user defined description of the resource.

host

body

string

The host name of the service back end that the resource is contained within. This parameter is always present in the response schema, but the value may be represented as “null” to non-admin users.

is_public

body

boolean

Whether the share is visible publicly (by all projects in the cloud) or not.

snapshot_support

body

boolean

An extra specification that filters back ends by whether they do or do not support share snapshots.

New in version 2.2

name

body

string

The user defined name of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

share_proto

body

string

The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS, MAPRFS, CephFS supported is starting with API v2.13.

Response example

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

Unmanage share (DEPRECATED)

Warning

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

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

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

Preconditions:

  • This API does not support unmanaging shares that are created on top of share servers (i.e. created with share networks).

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

path

string

The UUID of the share.

Response parameters

There is no body content for the response.

Quota sets

Provides quotas management support.

Important

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

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

  • gigabytes

  • snapshots

  • shares

  • snapshot_gigabytes

  • share_groups (since API version 2.40)

  • share_group_snapshots (since API version 2.40)

  • share_replicas (since API version 2.53)

  • replica_gigabytes (since API version 2.53)

  • per_share_gigabytes (since API version 2.62)

  • backups (since API version 2.80)

  • backup_gigabytes (since API version 2.80)

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

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

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

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

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

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

Show default quota set

Shows default quotas for a given project.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

project_id_quota_request_path (Optional)

path

string

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

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

Response parameters

Name

In

Type

Description

quota_set

body

object

The quota_set object.

id

body

string

The ID of the project the quota pertains to.

gigabytes

body

integer

The number of gigabytes allowed for each project.

snapshots

body

integer

The number of snapshots allowed for each project.

shares

body

integer

The number of shares allowed for each project.

snapshot_gigabytes

body

integer

The number of gigabytes for the snapshots allowed for each project.

share_networks (Optional)

body

integer

The number of share networks allowed for user and project, but not share type.

share_groups

body

integer

The number of share groups allowed for each project or user.

New in version 2.40

share_group_snapshots

body

integer

The number of share group snapshots allowed for each project or user.

New in version 2.40

share_networks

body

integer

The number of share networks allowed for each project.

share_replicas

body

integer

The number of share replicas allowed for each project.

New in version 2.53

replica_gigabytes

body

integer

The number of gigabytes for the share replicas allowed for each project.

New in version 2.53

per_share_gigabytes

body

integer

The number of gigabytes per share allowed for each project.

New in version 2.62

backups

body

integer

The number of backups allowed for each project.

New in version 2.80

backup_gigabytes

body

integer

The number of gigabytes for the backups allowed for each project.

New in version 2.80

Response example

{
    "quota_set": {
        "gigabytes": 1000,
        "shares": 50,
        "snapshot_gigabytes": 1000,
        "snapshots": 50,
        "id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_networks": 10,
        "share_groups": 10,
        "share_group_snapshots": 10,
        "share_replicas": 100,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 50,
        "backup_gigabytes": 1000
    }
}
GET
/v2/quota-sets/{project_id_quota_request_path}?user_id={user_id}

Show quota set

Shows quotas for a given project..

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

project_id_quota_request_path (Optional)

path

string

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

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

user_id (Optional)

query

string

The ID of the user. If you specify this query parameter, you retrieve or update the quotas for this user in the project. If you omit this parameter, you query or update the quotas for the whole project. This parameter is mutually exclusive with the “share_type” parameter.

share_type (Optional)

path

string

The name or UUID of the share type. If you specify this parameter in the URI, you show, update, or delete quotas for this share type. This parameter is mutually exclusive with the “user_id” query parameter.

New in version 2.39

Response parameters

Name

In

Type

Description

quota_set

body

object

The quota_set object.

id

body

string

The ID of the project the quota pertains to.

gigabytes

body

integer

The number of gigabytes allowed for each project.

snapshots

body

integer

The number of snapshots allowed for each project.

shares

body

integer

The number of shares allowed for each project.

snapshot_gigabytes

body

integer

The number of gigabytes for the snapshots allowed for each project.

share_networks (Optional)

body

integer

The number of share networks allowed for user and project, but not share type.

share_groups

body

integer

The number of share groups allowed for each project or user.

New in version 2.40

share_group_snapshots

body

integer

The number of share group snapshots allowed for each project or user.

New in version 2.40

share_replicas

body

integer

The number of share replicas allowed for each project.

New in version 2.53

replica_gigabytes

body

integer

The number of gigabytes for the share replicas allowed for each project.

New in version 2.53

per_share_gigabytes

body

integer

The number of gigabytes per share allowed for each project.

New in version 2.62

backups

body

integer

The number of backups allowed for each project.

New in version 2.80

backup_gigabytes

body

integer

The number of gigabytes for the backups allowed for each project.

New in version 2.80

Response example

{
    "quota_set": {
        "gigabytes": 1000,
        "shares": 50,
        "snapshot_gigabytes": 1000,
        "snapshots": 50,
        "id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_networks": 10,
        "share_groups": 10,
        "share_group_snapshots": 10,
        "share_replicas": 100,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 50,
        "backup_gigabytes": 1000
    }
}
GET
/v2/quota-sets/{project_id_quota_request_path}/detail?user_id={user_id}

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

New in version 2.25.

Shows quotas for a project in detail.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

project_id_quota_request_path (Optional)

path

string

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

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

user_id (Optional)

query

string

The ID of the user. If you specify this query parameter, you retrieve or update the quotas for this user in the project. If you omit this parameter, you query or update the quotas for the whole project. This parameter is mutually exclusive with the “share_type” parameter.

share_type (Optional)

path

string

The name or UUID of the share type. If you specify this parameter in the URI, you show, update, or delete quotas for this share type. This parameter is mutually exclusive with the “user_id” query parameter.

New in version 2.39

Response parameters

Name

In

Type

Description

quota_set

body

object

The quota_set object.

id

body

string

The ID of the project the quota pertains to.

gigabytes

body

object

The limit, in_use, reserved number of gigabytes allowed for each project.

New in version 2.25

snapshots

body

object

The limit, in_use, reserved number of snapshots allowed for each project.

New in version 2.25

shares

body

object

The limit, in_use, reserved number of shares allowed for each project.

New in version 2.25

snapshot_gigabytes

body

object

The limit, in_use, reserved number of gigabytes for the snapshots allowed for each project.

New in version 2.25

share_networks (Optional)

body

object

The limit, in_use, reserved number of share networks allowed for user and project, but not share type.

New in version 2.25

share_groups

body

object

The limit, in_use, reserved number of share groups for each project or user.

New in version 2.40

share_group_snapshots

body

object

The limit, in_use, reserved number of share group snapshots for each project or user.

New in version 2.40

share_replicas

body

object

The limit, in_use, reserved number of share replicas for each project.

New in version 2.53

replica_gigabytes

body

object

The limit, in_use, reserved number of replica gigabytes for each project.

New in version 2.53

per_share_gigabytes

body

object

The limit, in_use, reserved number of per share gigabytes for each project.

New in version 2.62

backups

body

object

The limit, in_use, reserved number of backups allowed for each project.

New in version 2.80

backup_gigabytes

body

object

The limit, in_use, reserved number of gigabytes for the backups allowed for each project.

New in version 2.80

Response example

{
    "quota_set": {
        "id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "gigabytes": {"in_use": 0,
                      "limit": 1000,
                      "reserved": 0},
        "shares": {"in_use": 0,
                   "limit": 50,
                   "reserved": 0},
        "snapshot_gigabytes": {"in_use": 0,
                               "limit": 1000,
                               "reserved": 0},
        "snapshots": {"in_use": 0,
                      "limit": 50,
                      "reserved": 0},
        "share_networks": {"in_use": 0,
                           "limit": 10,
                           "reserved": 0},
        "share_groups": {"in_use": 0,
                         "limit": 10,
                         "reserved": 0},
        "share_group_snapshots": {"in_use": 0,
                                  "limit": 10,
                                  "reserved": 0},
        "share_replicas": {"in_use": 0,
                           "limit": 100,
                           "reserved": 0},
        "replica_gigabytes": {"in_use": 0,
                              "limit": 1000,
                              "reserved": 0},
        "per_share_gigabytes": {"in_use": 0,
                                "limit": -1,
                                "reserved": 0},
        "backup_gigabytes": {"in_use": 0,
                             "limit": 1000,
                             "reserved": 0},
        "backups": {"in_use": 0,
                    "limit": 50,
                    "reserved": 0}
    }
}
PUT
/v2/quota-sets/{project_id_quota_request_path}?user_id={user_id}

Update quota set

Updates quotas for a project.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

project_id_quota_request_path (Optional)

path

string

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

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

user_id (Optional)

query

string

The ID of the user. If you specify this query parameter, you retrieve or update the quotas for this user in the project. If you omit this parameter, you query or update the quotas for the whole project. This parameter is mutually exclusive with the “share_type” parameter.

quota_set

body

object

The quota_set object.

force (Optional)

body

boolean

Indicates whether to permit or deny the force- update of a quota that is already used and the requested value exceeds the configured quota. Set to True to permit the force-update of the quota. Set to False to deny the force- update of the quota.

gigabytes (Optional)

body

integer

The number of gigabytes for the project.

snapshots (Optional)

body

integer

The number of snapshots for the project.

snapshot_gigabytes (Optional)

body

integer

The number of gigabytes for the snapshots for the project.

shares (Optional)

body

integer

The number of shares for the project.

share_networks (Optional)

body

integer

The number of share networks for the project.

share_groups (Optional)

body

integer

The number of share groups allowed for each project or user.

New in version 2.40

share_group_snapshots (Optional)

body

integer

The number of share group snapshots allowed for each project or user.

New in version 2.40

share_type (Optional)

path

string

The name or UUID of the share type. If you specify this parameter in the URI, you show, update, or delete quotas for this share type. This parameter is mutually exclusive with the “user_id” query parameter.

New in version 2.39

share_replicas (Optional)

body

integer

The number of share replicas allowed for each project or user.

New in version 2.53

replica_gigabytes (Optional)

body

integer

The number of gigabytes for share replicas for the project.

New in version 2.53

per_share_gigabytes (Optional)

body

integer

The number of gigabytes per share allowed for each project.

New in version 2.62

backups (Optional)

body

integer

The number of backups for the project.

New in version 2.80

backup_gigabytes (Optional)

body

integer

The number of gigabytes for the backups for the project.

New in version 2.80

Request example

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

Response parameters

Name

In

Type

Description

quota_set

body

object

The quota_set object.

id

body

string

The ID of the project the quota pertains to.

gigabytes

body

integer

The number of gigabytes allowed for each project.

snapshots

body

integer

The number of snapshots allowed for each project.

shares

body

integer

The number of shares allowed for each project.

snapshot_gigabytes

body

integer

The number of gigabytes for the snapshots allowed for each project.

share_networks (Optional)

body

integer

The number of share networks allowed for user and project, but not share type.

share_groups

body

integer

The number of share groups allowed for each project or user.

New in version 2.40

share_group_snapshots

body

integer

The number of share group snapshots allowed for each project or user.

New in version 2.40

share_replicas

body

integer

The number of share replicas allowed for each project.

New in version 2.53

replica_gigabytes

body

integer

The number of gigabytes for the share replicas allowed for each project.

New in version 2.53

per_share_gigabytes

body

integer

The number of gigabytes per share allowed for each project.

New in version 2.62

backups

body

integer

The number of backups allowed for each project.

New in version 2.80

backup_gigabytes

body

integer

The number of gigabytes for the backups allowed for each project.

New in version 2.80

Response example

{
    "quota_set": {
        "gigabytes": 1000,
        "snapshot_gigabytes": 999,
        "shares": 50,
        "snapshots": 49,
        "share_networks": 9,
        "share_groups": 12,
        "share_group_snapshots": 12,
        "share_replicas": 89,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 40,
        "backup_gigabytes": 500
    }
}
DELETE
/v2/quota-sets/{project_id_quota_request_path}?user_id={user_id}

Delete quota set

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

project_id_quota_request_path (Optional)

path

string

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

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

user_id (Optional)

query

string

The ID of the user. If you specify this query parameter, you retrieve or update the quotas for this user in the project. If you omit this parameter, you query or update the quotas for the whole project. This parameter is mutually exclusive with the “share_type” parameter.

share_type (Optional)

path

string

The name or UUID of the share type. If you specify this parameter in the URI, you show, update, or delete quotas for this share type. This parameter is mutually exclusive with the “user_id” query parameter.

New in version 2.39

Quota class set

Quota classes can be shown and updated for a project.

Important

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

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

Show quota classes for a project

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

quota_class_name

path

string

The name of the quota class for which to set quotas.

Response Parameters

Name

In

Type

Description

quota_class_set

body

object

A quota_class_set object.

share_groups

body

integer

The maximum number of share groups.

New in version 2.40

gigabytes

body

integer

The total maximum number of share gigabytes that are allowed in a project. You cannot request a share that exceeds the allowed gigabytes quota.

share_group_snapshots

body

integer

The maximum number of share group snapshots.

New in version 2.40

snapshots

body

integer

The total maximum number of share snapshots that are allowed in a project.

snapshot_gigabytes

body

integer

The total maximum number of snapshot gigabytes that are allowed in a project.

shares

body

integer

The total maximum number of shares that are allowed in a project.

id

body

string

A quota_class_set id.

share_networks

body

integer

The total maximum number of share-networks that are allowed in a project.

share_replicas

body

integer

The maximum number of share replicas that is allowed.

New in version 2.53

replica_gigabytes

body

integer

The maximum number of replica gigabytes that are allowed in a project. You cannot create a share, share replica, manage a share or extend a share if it is going to exceed the allowed replica gigabytes quota.

New in version 2.53

per_share_gigabytes

body

integer

The number of gigabytes per share allowed in a project.

New in version 2.62

backups

body

integer

The total maximum number of share backups that are allowed in a project.

New in version 2.80

backup_gigabytes

body

integer

The total maximum number of backup gigabytes that are allowed in a project.

New in version 2.80

Response Example

{
    "quota_class_set": {
        "share_groups": 50,
        "gigabytes": 1000,
        "share_group_snapshots": 50,
        "snapshots": 50,
        "snapshot_gigabytes": 1000,
        "shares": 50,
        "id": "default",
        "share_networks": 10,
        "share_replicas": 100,
        "replica_gigabytes": 1000,
        "per_share_gigabytes": -1,
        "backups": 50,
        "backup_gigabytes": 1000
    }
}
PUT
/v2/quota-class-sets/{quota_class_name}

Update quota classes for a project

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

quota_class_name

path

string

The name of the quota class for which to set quotas.

shares (Optional)

body

integer

The total maximum number of shares that are allowed in a project.

snapshots (Optional)

body

integer

The total maximum number of share snapshots that are allowed in a project.

gigabytes (Optional)

body

integer

The total maximum number of share gigabytes that are allowed in a project. You cannot request a share that exceeds the allowed gigabytes quota.

snapshot-gigabytes (Optional)

body

integer

The total maximum number of snapshot gigabytes that are allowed in a project.

share-networks (Optional)

body

integer

The total maximum number of share-networks that are allowed in a project.

share-replicas (Optional)

body

integer

The maximum number of share replicas that is allowed.

New in version 2.53

replica-gigabytes (Optional)

body

integer

The maximum number of replica gigabytes that are allowed in a project. You cannot create a share, share replica, manage a share or extend a share if it is going to exceed the allowed replica gigabytes quota.

New in version 2.53

per-share-gigabytes (Optional)

body

integer

The number of gigabytes per share allowed in a project.

New in version 2.62

backups (Optional)

body

integer

The total maximum number of share backups that are allowed in a project.

New in version 2.80

backup-gigabytes (Optional)

body

integer

The total maximum number of backup gigabytes that are allowed in a project.

New in version 2.80

Request Example

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

Response Parameters

Name

In

Type

Description

quota_class_set

body

object

A quota_class_set object.

share_groups

body

integer

The maximum number of share groups.

New in version 2.40

gigabytes

body

integer

The total maximum number of share gigabytes that are allowed in a project. You cannot request a share that exceeds the allowed gigabytes quota.

share_group_snapshots

body

integer

The maximum number of share group snapshots.

New in version 2.40

snapshots

body

integer

The total maximum number of share snapshots that are allowed in a project.

snapshot_gigabytes

body

integer

The total maximum number of snapshot gigabytes that are allowed in a project.

shares

body

integer

The total maximum number of shares that are allowed in a project.

share_networks

body

integer

The total maximum number of share-networks that are allowed in a project.

share_replicas

body

integer

The maximum number of share replicas that is allowed.

New in version 2.53

replica_gigabytes

body

integer

The maximum number of replica gigabytes that are allowed in a project. You cannot create a share, share replica, manage a share or extend a share if it is going to exceed the allowed replica gigabytes quota.

New in version 2.53

per_share_gigabytes

body

integer

The number of gigabytes per share allowed in a project.

New in version 2.62

backups

body

integer

The total maximum number of share backups that are allowed in a project.

New in version 2.80

backup_gigabytes

body

integer

The total maximum number of backup gigabytes that are allowed in a project.

New in version 2.80

Response Example

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

User messages (since API 2.37)

Lists, shows and deletes user messages.

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

GET
/v2/messages

List user messages

New in version 2.37.

Lists all user messages.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

limit (Optional)

query

integer

The maximum number of resource records to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of messages. A valid value is id, project_id, request_id, resource_type, action_id, detail_id, resource_id, message_level, expires_at, created_at.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

action_id (Optional)

query

string

The ID of the action during which the message was created.

detail_id (Optional)

query

string

The ID of the message detail.

message_level (Optional)

query

string

The message level.

project_id (Optional)

query

string

The ID of the project for which the message was created.

request_id (Optional)

query

string

The ID of the request during which the message was created.

resource_id (Optional)

query

string

The UUID of the resource for which the message was created.

resource_type (Optional)

query

string

The type of the resource for which the message was created.

created_since (Optional)

query

string

The date and time stamp when the query operation, only return user messages since it.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2021-11-10T09:49:58+08:00.

New in version 2.52

created_before (Optional)

query

string

The date and time stamp when the query operation, only return user messages before it.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2021-11-10T09:49:58+08:00.

New in version 2.52

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the message.

action_id

body

string

The ID of the action during which the message was created.

detail_id

body

string

The ID of the message detail.

message_level

body

string

The message level.

project_id

body

string

The ID of the project for which the message was created.

request_id

body

string

The UUID of the request during which the message was created.

resource_id

body

string

The UUID of the resource for which the message was created.

resource_type

body

string

The type of the resource for which the message was created.

message_members_links

body

array

The message member links.

expires_at

body

string

The date and time stamp when the resource message will expire within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

Response example

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

Show user message details

New in version 2.37.

Shows details for a user message.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

message_id (Optional)

path

string

The UUID of the message.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the message.

action_id

body

string

The ID of the action during which the message was created.

detail_id

body

string

The ID of the message detail.

message_level

body

string

The message level.

project_id

body

string

The ID of the project for which the message was created.

request_id

body

string

The UUID of the request during which the message was created.

resource_id

body

string

The UUID of the resource for which the message was created.

resource_type

body

string

The type of the resource for which the message was created.

message_links

body

array

The message links.

expires_at

body

string

The date and time stamp when the resource message will expire within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

Response example

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

Delete message

New in version 2.37.

Deletes a user message.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

message_id (Optional)

path

string

The UUID of the message.

Share access rules (since API v2.45)

Retrieve details about access rules

Note

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

GET
/v2/share-access-rules/{access_id}

Describe share access rule

New in version 2.45.

Retrieve details about a specified access rule.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

access_id

path

string

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

Response parameters

Name

In

Type

Description

share_id

body

string

The UUID of the share to which you are granted or denied access.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

access_type

body

string

The access rule type. A valid value for the share access rule type is one of the following values:

  • ip: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example 0.0.0.0/0 for IPv4 or ::/0 for IPv6.

  • cert: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_to

body

string

The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values:

  • ip: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example 0.0.0.0/0 for IPv4 or ::/0 for IPv6.

  • cert: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_key

body

string

The access credential of the entity granted share access.

state

body

string

Prior to versions 2.28, the state of all access rules of a given share is the same at all times. This could be new, active or error. Since 2.28, the state of each access rule of a share is independent of the others and can be queued_to_apply, applying, active, error, queued_to_deny or denying. A new rule starts out in queued_to_apply state and is successfully applied if it transitions to active state.

access_level

body

string

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

  • rw. Read and write (RW) access.

  • ro. Read-only (RO) access.

id

body

string

The access rule ID.

metadata

body

object

One or more access rule metadata key and value pairs as a dictionary of strings.

Response example

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

List share access rules

New in version 2.45.

Lists the share access rules on a share.

Note

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

Note

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_id

query

string

The share ID to filter share access rules with.

metadata

body

object

One or more metadata key and value pairs as a dictionary of strings.

Response parameters

Name

In

Type

Description

metadata

body

object

One or more access rule metadata key and value pairs as a dictionary of strings.

access_type

body

string

The access rule type. A valid value for the share access rule type is one of the following values:

  • ip: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example 0.0.0.0/0 for IPv4 or ::/0 for IPv6.

  • cert: Authenticates a client through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_key

body

string

The access credential of the entity granted share access.

access_to

body

string

The value that defines the access. The back end grants or denies the access to it. A valid value is one of these values:

  • ip: Authenticates a client through its IP address, that can be IPv4 or IPv6. You may specify a single client IP address or a range of IP addresses in CIDR notation. For example 0.0.0.0/0 for IPv4 or ::/0 for IPv6.

  • cert: Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • user: Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_level

body

string

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

  • rw. Read and write (RW) access.

  • ro. Read-only (RO) access.

state

body

string

Prior to versions 2.28, the state of all access rules of a given share is the same at all times. This could be new, active or error. Since 2.28, the state of each access rule of a share is independent of the others and can be queued_to_apply, applying, active, error, queued_to_deny or denying. A new rule starts out in queued_to_apply state and is successfully applied if it transitions to active state.

access_list

body

string

The object of the access rule. To list access rules, set this value to null.

id

body

string

The access rule ID.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

Response example

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

Share access rule metadata (since API v2.45)

Updates, and unsets share access rule metadata.

PUT
/v2/share-access-rules/{access_id}/metadata

Update share access rule metadata

New in version 2.45.

Updates the metadata for a share access rule.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

access_id

path

string

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

metadata

body

object

One or more access rule metadata key and value pairs as a dictionary of strings.

Request example

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

Response parameters

Name

In

Type

Description

metadata

body

object

One or more access rule metadata key and value pairs as a dictionary of strings.

Response example

{
    "metadata": {
        "aim": "changed_doc",
        "speed": "my_fast_access",
        "new_metadata_key": "new_information"
    }
}
DELETE
/v2/share-access-rules/{access_id}/metadata/{key}

Unset share access rule metadata

New in version 2.45.

Un-sets the metadata on a share access rule.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

access_id

path

string

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

key (Optional)

path

string

The key of a metadata item. For example, if the metadata on an existing share or access rule is as follows: "project": "my_test", "aim": "testing", the keys are “project” and “aim”.

Share groups (since API v2.31)

The share groups enable you to create a group of volumes and manage them together. A project can put shares be used in the same application together in a share group, such as consistency group snapshot, clone, backup, migrate, replicate, retype, etc.

Shares should be able to become a part of a share group only on share creation step. If share was created without provided share_group_id then this share won’t be able to become a part of any share group.

You can create a share group and associate it with multiple shares, list share groups, and show information for delete a share group.

Note

Share Group APIs are no longer considered experimental since API version 2.55. The availability_zone_id and consistent_snapshot_support fields were added to share_group object since version 2.34.

GET
/v2/share-groups

List share groups

New in version 2.31.

Lists all share groups.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name (Optional)

query

string

The user defined name of the resource to filter resources by.

description (Optional)

query

string

The user defined description text that can be used to filter resources.

status (Optional)

query

string

Filters by a share group status. A valid value is creating, error, available, deleting, error_deleting.

share_server_id (Optional)

query

string

The UUID of the share server.

snapshot_id (Optional)

query

string

The UUID of the share’s base snapshot to filter the request based on.

host (Optional)

query

string

The host name for the back end.

share_network_id (Optional)

query

string

The UUID of the share network to filter resources by.

share_group_type_id (Optional)

query

string

The share group type ID to filter share groups.

share_group_snapshot_id (Optional)

query

string

The source share group snapshot ID to list the share group.

New in version 2.31

share_types (Optional)

query

array

A list of one or more share type IDs. Allows filtering share groups.

limit (Optional)

query

integer

The maximum number of share groups members to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of shares. A valid value is id, status, size, host, share_proto, export_location, availability_zone, user_id, project_id, created_at, updated_at, display_name, name, share_type_id, share_type, share_network_id, share_network, snapshot_id, or snapshot.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

description~ (Optional)

query

string

The description pattern that can be used to filter shares, share snapshots, share networks or share groups.

New in version 2.36

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share group.

New in version 2.31

links

body

string

The share group links.

name

body

string

The user defined name of the resource.

status

body

string

The share group status, which is available, error, creating, or deleting.

description

body

string

The user defined description of the resource.

Response example

{
    "share_groups": [
        {
            "id": "b94a8548-2079-4be0-b21c-0a887acd31ca",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "bookmark"
                }
            ],
            "name": "My_share_group"
        },
        {
            "id": "306ea93c-32e9-4907-a117-148b3945749f",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
                    "rel": "bookmark"
                }
            ],
            "name": "Test_Share_group"
        }
    ]
}
GET
/v2/share-groups/detail

List share groups with details

New in version 2.31.

Lists all share groups with details.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name (Optional)

query

string

The user defined name of the resource to filter resources by.

description (Optional)

query

string

The user defined description text that can be used to filter resources.

status (Optional)

query

string

Filters by a share group status. A valid value is creating, error, available, deleting, error_deleting.

share_server_id (Optional)

query

string

The UUID of the share server.

snapshot_id (Optional)

query

string

The UUID of the share’s base snapshot to filter the request based on.

host (Optional)

query

string

The host name for the back end.

share_network_id (Optional)

query

string

The UUID of the share network to filter resources by.

share_group_type_id (Optional)

query

string

The share group type ID to filter share groups.

share_group_snapshot_id (Optional)

query

string

The source share group snapshot ID to list the share group.

New in version 2.31

share_types (Optional)

query

array

A list of one or more share type IDs. Allows filtering share groups.

limit (Optional)

query

integer

The maximum number of share groups members to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of shares. A valid value is id, status, size, host, share_proto, export_location, availability_zone, user_id, project_id, created_at, updated_at, display_name, name, share_type_id, share_type, share_network_id, share_network, snapshot_id, or snapshot.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

description~ (Optional)

query

string

The description pattern that can be used to filter shares, share snapshots, share networks or share groups.

New in version 2.36

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share group.

New in version 2.31

name

body

string

The user defined name of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share group status, which is available, error, creating, or deleting.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

host

body

string

The host name for the back end.

share_group_type_id

body

string

The share group type ID.

source_share_group_snapshot_id

body

string

The source share group snapshot ID to create the share group.

share_network_id

body

string

The share network ID where the resource is exported to.

share_types

body

array

A list of share type IDs.

links

body

string

The share group links.

availability_zone

body

string

The availability zone ID that the share group exists within.

New in version 2.34

consistent_snapshot_support

body

string

The consistency snapshot support.

New in version 2.34

Response example

{
    "share_groups": [
        {
            "id": "b94a8548-2079-4be0-b21c-0a887acd31ca",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
                    "rel": "bookmark"
                }
            ],
            "name": "My_share_group",
            "availability_zone": "nova",
            "consistent_snapshot_support": true,
            "share_group_type_id": "313df749-aac0-1a54-af52-10f6c991e80c",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "share_types": ["25747776-08e5-494f-ab40-a64b9d20d8f7"],
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "status": "available",
            "description": "My share group",
            "host": "manila2@generic1#GENERIC1",
            "source_share_group_snapshot_id": null,
            "created_at": "2015-09-18T10:25:24.000000"
        },
        {
            "id": "306ea93c-32e9-4907-a117-148b3945749f",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
                    "rel": "bookmark"
                }
            ],
            "name": "Test_Share_group",
            "availability_zone": "nova",
            "consistent_snapshot_support": true,
            "share_group_type_id": "313df749-aac0-1a54-af52-10f6c991e80c",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "share_types": ["25747776-08e5-494f-ab40-a64b9d20d8f7"],
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "status": "available",
            "description": "Test share group",
            "host": "manila2@generic1#GENERIC1",
            "source_share_group_snapshot_id": null,
            "created_at": "2015-09-18T10:25:24.000000"
        }
    ]
}
GET
/v2/share-groups/{share_group_id}

Show share group details

New in version 2.31.

Shows details for a share group.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_id

path

string

The UUID of the share group.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share group.

New in version 2.31

name

body

string

The user defined name of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share group status, which is available, error, creating, or deleting.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

host

body

string

The host name for the back end.

share_group_type_id

body

string

The share group type ID.

source_share_group_snapshot_id

body

string

The source share group snapshot ID to create the share group.

share_network_id

body

string

The share network ID where the resource is exported to.

share_types

body

array

A list of share type IDs.

links

body

string

The share group links.

availability_zone

body

string

The availability zone ID that the share group exists within.

New in version 2.34

consistent_snapshot_support

body

string

The consistency snapshot support.

New in version 2.34

Response example

{
    "share_groups": {
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/011d21e2-fbc3-4e4a-9993-9ea223f73264",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "consistent_snapshot_support": true,
        "share_group_type_id": "313df749-aac0-1a54-af52-10f6c991e80c",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "id": "011d21e2-fbc3-4e4a-9993-9ea223f73264",
        "share_types": ["25747776-08e5-494f-ab40-a64b9d20d8f7"],
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "status": "available",
        "description": "My custom share London",
        "host": "manila2@generic1#GENERIC1",
        "source_share_group_snapshot_id": null,
        "name": "share_London",
        "created_at": "2015-09-18T10:25:24.000000"
    }
}
POST
/v2/share-groups

Create share group

New in version 2.31.

Creates a share group.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

share_types (Optional)

body

array

A list of one or more share type IDs.

share_group_type (Optional)

body

string

The share group type ID to create a share group.

share_network (Optional)

body

string

The ID of a share network that the resource must be exported to. Note that when using a share type with the driver_handles_share_servers extra spec as False, you should not provide a share_network_id.

source_share_group_snapshot (Optional)

body

string

The source share group snapshot ID to create the share group.

availability_zone

body

string

The availability zone ID that the share group exists within.

New in version 2.34

Request example

{
    "share_group": {
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
        "name": "my_group",
        "description": "for_test",
        "share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "availability_zone": "nova",
        "share_network_id": "82168c2a-10bf-4013-bcc4-3d984136aee3",
        "source_share_group_snapshot_id": "69861c2a-10bf-4013-bcc4-3d020466aee3"
    }
}

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share group.

New in version 2.31

name

body

string

The user defined name of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share group status, which is available, error, creating, or deleting.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

host (Optional)

body

string

The share group host name.

share_group_type_id

body

string

The share group type ID.

source_share_group_snapshot_id

body

string

The source share group snapshot ID to create the share group.

share_network_id

body

string

The share network ID where the resource is exported to.

share_types

body

array

A list of share type IDs.

links

body

string

The share group links.

availability_zone

body

string

The availability zone ID that the share group exists within.

New in version 2.34

consistent_snapshot_support

body

string

The consistency snapshot support.

New in version 2.34

Response example

{
    "share_groups": {
        "status": "creating",
        "description": null,
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
                "rel": "bookmark"
            }
        ],
        "availability_zone": null,
        "source_share_group_snapshot_id": null,
        "share_network_id": null,
        "share_server_id": null,
        "host": null,
        "share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "consistent_snapshot_support": null,
        "id": "f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
        "name": null,
        "created_at": "2017-08-03T19:20:33.974421",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"]
    }
}
POST
/v2/share-groups/{share_group_id}/action

Reset share group state

New in version 2.31.

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_id

path

string

The UUID of the share group.

reset_status

body

object

The reset_status object.

status

body

string

The share group status, which is available, error, creating, or deleting.

Request example

{
    "reset_status": {
        "status": "error"
    }
}
PUT
/v2/share-groups/{share_group_id}

Update share group

New in version 2.31.

Updates a share group.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_id

path

string

The UUID of the share group.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

Request example

{
    "share_group": {
        "name": "new name",
        "description": "Changing the share group description."
    }
}

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share group.

New in version 2.31

name

body

string

The user defined name of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

status

body

string

The share group status, which is available, error, creating, or deleting.

description

body

string

The user defined description of the resource.

project_id

body

string

The ID of the project that owns the resource.

host (Optional)

body

string

The share group host name.

share_group_type_id

body

string

The share group type ID.

source_share_group_snapshot_id (Optional)

body

string

The source share group snapshot ID to create the share group.

share_network_id

body

string

The share network ID where the resource is exported to.

share_types

body

array

A list of share type IDs.

links

body

string

The share group links.

availability_zone

body

string

The availability zone ID that the share group exists within.

New in version 2.34

consistent_snapshot_support

body

string

The consistency snapshot support.

New in version 2.34

Response example

{
    "share_groups": {
        "status": "creating",
        "description": "Changing the share group description.",
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
                "rel": "bookmark"
            }
        ],
        "availability_zone": null,
        "source_share_group_snapshot_id": null,
        "share_network_id": null,
        "share_server_id": null,
        "host": null,
        "share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "consistent_snapshot_support": null,
        "id": "f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
        "name": "new name",
        "created_at": "2017-08-03T19:20:33.974421",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"]
    }
}
DELETE
/v2/share-groups/{share_group_id}

Delete share group

New in version 2.31.

Deletes a share group.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_id

path

string

The UUID of the share group.

force

body

string

To force-delete a share or share group, set this value to null. The force-delete action, unlike the delete action, ignores the share or share group status.

Share group types (since API v2.31)

A share group type enables you to filter or choose back ends before you create a share group.

You can set share group types as either public or private. By default a share group type is created as publicly accessible. Set share_group_type_access:is_public to False to make a share group type private.

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

Administrators can specify which share type(s) a given group type may contain. If Administrators do not explicitly associate share types with a given share group type, the service will associate the share type configured as the default_share_type with the share group type. When creating a share group, the scheduler picks one of the back ends that match a combination of the extra specs in the specified share type(s) and share group type.

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

  • Filter back ends by group scheduler. Specify these group extras specifications in this format: group_specs=value. For example, consistent_snapshot_support=true.

Note

Share Group Type APIs are no longer considered experimental since API version 2.55.

GET
/v2/share-group-types

List share group types

New in version 2.31.

Lists all share group 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.

group_specs (Optional)

query

string

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

New in version 2.66

Response parameters

Name

In

Type

Description

id

body

string

The share group type ID.

is_public

body

boolean

The level of visibility for the share group type. Set to true to make share group type public. Set to false to make it private. Default value is true.

share_types

body

array

A list of share type IDs.

name

body

string

The share group type name.

group_specs

body

object

The extra specifications for the share group type.

is_default

body

boolean

Defines the share group type created is default or not. If the returning value is true, then it is the default share group type, otherwise, it is not default.

New in version 2.46

Response example

{
    "share_group_types": [
        {
            "is_public": true,
            "group_specs": {},
            "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
            "id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
            "name": "test_group_type",
            "is_default": false
        }
    ]
}
GET
/v2/share-group-types/default

List default share group types

New in version 2.31.

Lists default share group types.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

Response parameters

Name

In

Type

Description

id

body

string

The share group type ID.

is_public

body

boolean

The level of visibility for the share group type. Set to true to make share group type public. Set to false to make it private. Default value is true.

share_types

body

array

A list of share type IDs.

name

body

string

The share group type name.

group_specs

body

object

The extra specifications for the share group type.

is_default

body

boolean

Defines the share group type created is default or not. If the returning value is true, then it is the default share group type, otherwise, it is not default.

New in version 2.46

Response example

{
    "share_group_type": {
        "is_public": true,
        "group_specs": {},
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
        "id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "name": "test_group_type",
        "is_default": true
    }
}
GET
/v2/share-group-types/{share_group_type_id}/group-specs

List share group types extra specs

New in version 2.31.

Lists the extra specifications for a share group type.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_type_id

body

string

The share group type ID.

Response parameters

Name

In

Type

Description

group_specs

body

object

The extra specifications for the share group type.

Response example

{
    "group_specs": {
        "snapshot_support": "True"
    }
}
POST
/v2/share-group-types

Create share group type

New in version 2.31.

Creates a share group type.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_types

body

array

A list of share type IDs.

name (Optional)

body

string

The name of the share group type resource. The value of this field is limited to 255 characters.

group_specs (Optional)

body

object

The extra specifications for the share group type.

is_public (Optional)

body

boolean

The level of visibility for the share group type. Set to true to make share group type public. Set to false to make it private. Default value is false.

Request example

{
    "share_group_type": {
        "is_public": true,
        "group_specs": {
            "snapshot_support": true
        },
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
        "name": "my_new_group_type"
    }
}

Response parameters

Name

In

Type

Description

id

body

string

The share group type ID.

group_specs

body

object

The extra specifications for the share group type.

name

body

string

The share group type name.

share_types

body

array

A list of share type IDs.

is_public

body

boolean

The level of visibility for the share group type. Set to true to make share group type public. Set to false to make it private. Default value is true.

is_default

body

boolean

Defines the share group type created is default or not. If the returning value is true, then it is the default share group type, otherwise, it is not default.

New in version 2.46

Response example

{
    "share_group_type": {
        "is_public": true,
        "group_specs": {},
        "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
        "id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
        "name": "test_group_type",
        "is_default": false
    }
}
GET
/v2/share-group-types/{share_group_type_id}/access

Show share group type access details

New in version 2.31.

Shows access details for a share group type.

You can view access details for private share group types only.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_type_id

body

string

The share group type ID.

Response parameters

Name

In

Type

Description

share_group_type_id

body

string

The share group type ID.

project_id

body

string

The ID of the project that has been granted access to the type resource.

Response example

{
    "share_group_type_access": [
        {
            "share_group_type_id": "1732f284-401d-41d9-a494-425451e8b4b8",
            "project_id": "818a3f48dcd644909b3fa2e45a399a27"
        },
        {
            "share_group_type_id": "1732f284-401d-41d9-a494-425451e8b4b8",
            "project_id": "e1284adea3ee4d2482af5ed214f3ad90"
        }
    ]
}
POST
/v2/share-group-types/{share_group_type_id}/group-specs

Set extra spec for share group type

New in version 2.31.

Sets an extra specification for the share group type.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_type_id

body

string

The share group type ID.

group_specs

body

object

The extra specifications for the share group type.

Request example

{
    "group_specs": {
        "my_group_key": "my_group_value"
    }
}

Response parameters

Name

In

Type

Description

group_specs

body

object

The extra specifications for the share group type.

Response example

{
    "group_specs": {
        "my_group_key": "my_group_value"
    }
}
DELETE
/v2/share-group-types/{share_group_type_id}/group-specs/{group_spec_key}

Unset an group spec

New in version 2.31.

Unsets an extra specification for the share type.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_type_id

body

string

The share group type ID.

group_spec_key

body

string

The extra specification key for the share group type.

POST
/v2/share-group-types/{share_group_type_id}/action

Add share group type access

New in version 2.31.

Adds share group type access for a project.

You can add access to private share group types only.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_type_id

path

string

The UUID of the share group type.

addProjectAccess

body

object

An object representing the project resource that access should be granted to.

project

body

string

The ID of the project that needs to have access to the type resource.

Request example

{
    "addProjectAccess": {
        "project": "e1284adea3ee4d2482af5ed214f3ad90"
    }
}
POST
/v2/share-group-types/{share_group_type_id}/action

Remove share group type access

New in version 2.31.

Removes share group type access from a project.

You can remove access from private share group types only.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_type_id

path

string

The UUID of the share group type.

removeProjectAccess

body

object

An object representing the project resource that access should be revoked from.

project

body

string

The ID of the project whose access to the type resource must be revoked.

Request example

{
    "removeProjectAccess": {
        "project": "818a3f48dcd644909b3fa2e45a399a27"
    }
}
DELETE
/v2/share-group-types/{share_group_type_id}

Delete share group type

New in version 2.31.

Deletes a share group type.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

share_group_type_id

path

string

The UUID of the share group type.

Share group snapshots (since API v2.31)

Use the Shared File Systems Service to make snapshots of share groups. A share group snapshot is a point-in-time, read-only copy of the data that is contained in a share group. You can create, update, and delete share group snapshots. After you create a share group snapshot, you can create a share group from it.

You can update a share group snapshot to rename it, change its description, or update its state.

As administrator, you can also reset the state of a group snapshot. Use the policy.yaml file to grant permissions for these actions to other roles.

Note

Share Group Snapshot APIs are no longer considered experimental since API version 2.55.

GET
/v2/share-group-snapshots

List share group snapshots

New in version 2.31.

Lists all share group snapshots.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name (Optional)

query

string

The user defined name of the resource to filter resources by.

description (Optional)

query

string

The user defined description text that can be used to filter resources.

status (Optional)

query

string

Filters by a share group snapshot status. A valid value is creating, error, available, deleting, error_deleting.

share_group_id (Optional)

query

string

The UUID of a share group to filter resource.

New in version 2.31

limit (Optional)

query

integer

The maximum number of share groups members to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of shares. A valid value is id, status, size, host, share_proto, export_location, availability_zone, user_id, project_id, created_at, updated_at, display_name, name, share_type_id, share_type, share_network_id, share_network, snapshot_id, or snapshot.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

Response parameters

Name

In

Type

Description

id

body

object

The share group snapshot ID.

name

body

string

The user defined name of the resource.

links

body

string

The share group snapshot links.

Response example

{
    "share_group_snapshot": [
        {
            "links": [
                {
                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                    "rel": "bookmark"
                }
            ],
            "name": null,
            "id": "46bf5875-58d6-4816-948f-8828423b0b9f"
        }
    ]
}
GET
/v2/share-group-snapshots/detail

List share group snapshots with details

New in version 2.31.

Lists all share group snapshots with details.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

name (Optional)

query

string

The user defined name of the resource to filter resources by.

description (Optional)

query

string

The user defined description text that can be used to filter resources.

status (Optional)

query

string

Filters by a share group snapshot status. A valid value is creating, error, available, deleting, error_deleting.

share_group_id (Optional)

query

string

The UUID of a share group to filter resource.

New in version 2.31

limit (Optional)

query

integer

The maximum number of share groups members to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of shares. A valid value is id, status, size, host, share_proto, export_location, availability_zone, user_id, project_id, created_at, updated_at, display_name, name, share_type_id, share_type, share_network_id, share_network, snapshot_id, or snapshot.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

Response parameters

Name

In

Type

Description

id

body

object

The share group snapshot ID.

project_id

body

string

The ID of the project that owns the resource.

status

body

string

Filters by a share group snapshot status. A valid value is creating, error, available, deleting, error_deleting.

share_group_id

body

string

The UUID of the share group.

New in version 2.31

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

members

body

string

The share group snapshot members.

links

body

string

The share group snapshot links.

Response example

{
    "share_group_snapshots": [
        {
            "status": "available",
            "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
            "links": [
                {
                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                    "rel": "bookmark"
                }
            ],
            "name": null,
            "members": [],
            "created_at": "2017-08-10T03:01:39.000000",
            "project_id": "e23850eeb91d4fa3866af634223e454c",
            "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
            "description": null
        },
        {
            "status": "available",
            "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
            "links": [
                {
                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
                    "rel": "bookmark"
                }
            ],
            "name": null,
            "members": [],
            "created_at": "2017-08-10T03:01:28.000000",
            "project_id": "e23850eeb91d4fa3866af634223e454c",
            "id": "9d8ed9be-4454-4df0-b0ae-8360b623d93d",
            "description": null
        }
    ]
}
GET
/v2/share-group-snapshots/{group_snapshot_id}/members

List share group snapshots members

New in version 2.31.

Lists all share group snapshots members.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

group_snapshot_id

path

string

The group snapshot ID.

Response parameters

Name

In

Type

Description

id

body

object

The share group snapshot ID.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

project_id

body

string

The ID of the project that owns the resource.

size

body

integer

The snapshot size, in GiBs.

share_protocol

body

string

The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, CephFS or MAPRFS. CephFS is supported starting with API v2.13.

name

body

string

The user defined name of the resource.

share_group_snapshot_id

body

object

The share group snapshot ID.

share_id

body

string

The UUID of the source share that was used to create the snapshot.

Response example

{
    "share_group_snapshot_members": [
        {
            "status": "available",
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "created_at": "2017-09-07T11:50:39.000000",
            "share_proto": "NFS",
            "share_size": 1,
            "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
            "size": 1
        },
        {
            "status": "available",
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "created_at": "2015-09-07T11:50:39.000000",
            "share_proto": "NFS",
            "share_size": 1,
            "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
            "size": 1
        }
    ]
}
GET
/v2/share-group-snapshots/{group_snapshot_id}

Show share group snapshot details

New in version 2.31.

Shows details for a share group snapshot.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

group_snapshot_id

path

string

The group snapshot ID.

Response parameters

Name

In

Type

Description

id

body

object

The share group snapshot ID.

project_id

body

string

The ID of the project that owns the resource.

status

body

string

Filters by a share group snapshot status. A valid value is creating, error, available, deleting, error_deleting.

share_group_id

body

string

The UUID of the share group.

New in version 2.31

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

members

body

string

The share group snapshot members.

links

body

string

The share group snapshot links.

Response example

{
    "share_group_snapshot": {
        "status": "creating",
        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "bookmark"
            }
        ],
        "name": null,
        "members": [],
        "created_at": "2017-08-10T03:01:39.442509",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
        "description": null
    }
}
POST
/v2/share-group-snapshots

Create share group snapshot

New in version 2.31.

Creates a snapshot from a share.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

share_group_id

body

string

The UUID of the share group.

New in version 2.31

Request example

{
    "share_group_snapshot": {
        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
        "name": "test",
        "description": "test description"
    }
}

Response parameters

Name

In

Type

Description

id

body

object

The share group snapshot ID.

project_id

body

string

The ID of the project that owns the resource.

status

body

string

Filters by a share group snapshot status. A valid value is creating, error, available, deleting, error_deleting.

share_group_id

body

string

The UUID of the share group.

New in version 2.31

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

members

body

string

The share group snapshot members.

links

body

string

The share group snapshot links.

Response example

{
    "share_group_snapshot": {
        "status": "creating",
        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "bookmark"
            }
        ],
        "name": null,
        "members": [],
        "created_at": "2017-08-10T03:01:39.442509",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
        "description": null
    }
}
POST
/v2/share-group-snapshots/{group_snapshot_id}/action

Reset share group snapshot state

New in version 2.31.

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

group_snapshot_id

path

string

The group snapshot ID.

status

body

string

Filters by a share group snapshot status. A valid value is creating, error, available, deleting, error_deleting.

Request example

{
    "reset_status": {
        "status": "error"
    }
}
PUT
/v2/share-group-snapshots/{group_snapshot_id}

Update share group snapshot

New in version 2.31.

Updates a share group snapshot.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

group_snapshot_id

path

string

The group snapshot ID.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

Request example

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

Response parameters

Name

In

Type

Description

id

body

object

The share group snapshot ID.

project_id

body

string

The ID of the project that owns the resource.

status

body

string

Filters by a share group snapshot status. A valid value is creating, error, available, deleting, error_deleting.

share_group_id

body

string

The UUID of the share group.

New in version 2.31

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

members

body

string

The share group snapshot members.

links

body

string

The share group snapshot links.

Response example

{
    "share_group_snapshot": {
        "status": "creating",
        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
        "links": [
            {
                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "self"
            },
            {
                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
                "rel": "bookmark"
            }
        ],
        "name": null,
        "members": [],
        "created_at": "2017-08-10T03:01:39.442509",
        "project_id": "e23850eeb91d4fa3866af634223e454c",
        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
        "description": null
    }
}
DELETE
/v2/share-group-snapshots/{group_snapshot_id}

Delete share group snapshot

New in version 2.31.

Deletes a share group snapshot.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

group_snapshot_id

path

string

The group snapshot ID.

Share transfer (since API v2.77)

Transfers a share across projects.

POST
/v2/share-transfers

Create a share transfer

Initiates a share transfer from a source project namespace to a destination project namespace.

Preconditions

  • The share status must be available

  • If the share has snapshots, those snapshots must be available

  • The share can not belong to share group

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

transfer

body

object

The transfer object.

name (Optional)

body

string

The transfer display name.

share_id

body

string

The UUID of the share.

Request Example

{
    "transfer": {
        "share_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
        "name": "test_transfer"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The transfer UUID.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

name (Optional)

body

string

The transfer display name.

resource_type

body

string

The type of the resource for the transfer.

resource_id

body

string

The UUID of the resource for the transfer.

auth_key

body

string

The authentication key for the transfer.

source_project_id

body

string

The ID of the project that owns the resource.

destination_project_id

body

string

UUID of the destination project to accept transfer resource.

accepted

body

boolean

Whether the transfer has been accepted.

expires_at

body

string

The date and time stamp when the resource transfer will expire. After transfer expired, will be automatically deleted.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

links

body

array

Pagination and bookmark links for the resource.

Response Example

{
    "transfer": {
        "id": "f21c72c4-2b77-445b-aa12-e8d1b44163a2",
        "created_at": "2022-09-06T08:17:43.629495",
        "name": "test_transfer",
        "resource_type": "share",
        "resource_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
        "auth_key": "406a2d67cdb09afe",
        "source_project_id": "714198c7ac5e45a4b785de732ea4695d",
        "destination_project_id": null,
        "accepted": false,
        "expires_at": "2022-09-06T08:22:43.629495",
        "links": [
            {
                "rel": "self",
                "href": "http://192.168.48.129/shar/v2/share-transfer/f21c72c4-2b77-445b-aa12-e8d1b44163a2"
            },
            {
                "rel": "bookmark",
                "href": "http://192.168.48.129/shar/share-transfer/f21c72c4-2b77-445b-aa12-e8d1b44163a2"
            }
        ]
    }
}
POST
/v2/share-transfers/{transfer_id}/accept

Accept a share transfer in the destination project namespace

Accepts a share transfer.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

413 - Request Entity Too Large

This operation cannot be completed.

Request

Name

In

Type

Description

transfer_id

path

string

The unique identifier for a transfer.

auth_key

body

string

The authentication key for the transfer.

clear_access_rules (Optional)

body

boolean

Whether clear all access rules when accept share.

Request Example

{
    "accept": {
        "auth_key": "d7ef426932068a33",
        "clear_access_rules": true
    }
}
GET
/v2/share-transfers

List share transfers for a project

Lists share transfers.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

limit (Optional)

query

integer

The maximum number of share groups members to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of transfers. A valid value is id, name, resource_type, resource_id, source_project_id, destination_project_id, created_at, expires_at.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

name (Optional)

query

string

The user defined name of the resource to filter resources by.

name~ (Optional)

query

string

The name pattern that can be used to filter shares, share snapshots, share networks, transfers or share groups.

New in version 2.36

resource_type (Optional)

query

string

The type of the resource for which the transfer was created.

Response Parameters

Name

In

Type

Description

transfers

body

array

List of transfers.

id

body

string

The transfer UUID.

resource_type

body

string

The type of the resource for the transfer.

resource_id

body

string

The UUID of the resource for the transfer.

name (Optional)

body

string

The transfer display name.

links

body

array

Pagination and bookmark links for the resource.

Response Example

{
    "transfers": [
        {
            "id": "02a948b4-671b-4c62-b13a-18d613cb4576",
            "resource_type": "share",
            "resource_id": "0fe7cf64-b879-4902-9d86-f80aeff12b06",
            "name": "transfer2",
            "links": [
                {
                    "rel": "self",
                    "href": "http://192.168.48.129/shar/v2/share-transfer/02a948b4-671b-4c62-b13a-18d613cb4576"
                },
                {
                    "rel": "bookmark",
                    "href": "http://192.168.48.129/shar/share-transfer/02a948b4-671b-4c62-b13a-18d613cb4576"
                }
            ]
        },
        {
            "id": "a10209ff-b55d-4fed-9f63-abea53b6f107",
            "resource_type": "share",
            "resource_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
            "name": "transfer1",
            "links": [
                {
                    "rel": "self",
                    "href": "http://192.168.48.129/shar/v2/share-transfer/a10209ff-b55d-4fed-9f63-abea53b6f107"
                },
                {
                    "rel": "bookmark",
                    "href": "http://192.168.48.129/shar/share-transfer/a10209ff-b55d-4fed-9f63-abea53b6f107"
                }
            ]
        }
    ]
}
GET
/v2/share-transfers/detail

List share transfers and details

Lists share transfers, with details.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

all_tenants (Optional)

query

boolean

(Admin only). Defines whether to list the requested resources for all projects. Set to 1 to list resources for all projects. Set to 0 to list resources only for the current project. Examples of resources include shares, snapshots, share networks, security services and share groups.

limit (Optional)

query

integer

The maximum number of share groups members to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of transfers. A valid value is id, name, resource_type, resource_id, source_project_id, destination_project_id, created_at, expires_at.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

Response Parameters

Name

In

Type

Description

transfers

body

array

List of transfers.

id

body

string

The transfer UUID.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

name (Optional)

body

string

The transfer display name.

resource_type

body

string

The type of the resource for the transfer.

resource_id

body

string

The UUID of the resource for the transfer.

source_project_id

body

string

The ID of the project that owns the resource.

destination_project_id

body

string

UUID of the destination project to accept transfer resource.

accepted

body

boolean

Whether the transfer has been accepted.

expires_at

body

string

The date and time stamp when the resource transfer will expire. After transfer expired, will be automatically deleted.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

links

body

array

Pagination and bookmark links for the resource.

Response Example

{
    "transfers": [
        {
            "id": "42b0fab4-df77-4f25-a958-5370e1c95ed2",
            "created_at": "2022-09-07T01:52:39.000000",
            "name": "transfer2",
            "resource_type": "share",
            "resource_id": "0fe7cf64-b879-4902-9d86-f80aeff12b06",
            "source_project_id": "714198c7ac5e45a4b785de732ea4695d",
            "destination_project_id": null,
            "accepted": false,
            "expires_at": "2022-09-07T01:57:39.000000",
            "links": [
                {
                    "rel": "self",
                    "href": "http://192.168.48.129/shar/v2/share-transfer/42b0fab4-df77-4f25-a958-5370e1c95ed2"
                },
                {
                    "rel": "bookmark",
                    "href": "http://192.168.48.129/shar/share-transfer/42b0fab4-df77-4f25-a958-5370e1c95ed2"
                }
            ]
        },
        {
            "id": "506a7e77-42e7-4f33-ac36-1d1dd7f2b9af",
            "created_at": "2022-09-07T01:52:30.000000",
            "name": "transfer1",
            "resource_type": "share",
            "resource_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
            "source_project_id": "714198c7ac5e45a4b785de732ea4695d",
            "destination_project_id": null,
            "accepted": false,
            "expires_at": "2022-09-07T01:57:30.000000",
            "links": [
                {
                    "rel": "self",
                    "href": "http://192.168.48.129/shar/v2/share-transfer/506a7e77-42e7-4f33-ac36-1d1dd7f2b9af"
                },
                {
                    "rel": "bookmark",
                    "href": "http://192.168.48.129/shar/share-transfer/506a7e77-42e7-4f33-ac36-1d1dd7f2b9af"
                }
            ]
        }
    ]
}
GET
/v2/share-transfers/{transfer_id}

Show share transfer detail

Shows details for a share transfer.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

transfer_id

path

string

The unique identifier for a transfer.

Response Parameters

Name

In

Type

Description

id

body

string

The transfer UUID.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

name (Optional)

body

string

The transfer display name.

resource_type

body

string

The type of the resource for the transfer.

resource_id

body

string

The UUID of the resource for the transfer.

source_project_id

body

string

The ID of the project that owns the resource.

destination_project_id

body

string

UUID of the destination project to accept transfer resource.

accepted

body

boolean

Whether the transfer has been accepted.

expires_at

body

string

The date and time stamp when the resource transfer will expire. After transfer expired, will be automatically deleted.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

links

body

array

Pagination and bookmark links for the resource.

Response Example

{
    "transfer": {
        "id": "d2035732-d0c0-4380-a44c-f978a264ab1a",
        "created_at": "2022-09-07T01:12:29.000000",
        "name": "transfer1",
        "resource_type": "share",
        "resource_id": "29476819-28a9-4b1a-a21d-3b2d203025a0",
        "source_project_id": "714198c7ac5e45a4b785de732ea4695d",
        "destination_project_id": null,
        "accepted": false,
        "expires_at": "2022-09-07T01:17:29.000000",
        "links": [
            {
                "rel": "self",
                "href": "http://192.168.48.129/shar/v2/share-transfer/d2035732-d0c0-4380-a44c-f978a264ab1a"
            },
            {
                "rel": "bookmark",
                "href": "http://192.168.48.129/shar/share-transfer/d2035732-d0c0-4380-a44c-f978a264ab1a"
            }
        ]
    }
}
DELETE
/v2/share-transfers/{transfer_id}

Delete a share transfer

Deletes a share transfer.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

transfer_id

path

string

The unique identifier for a transfer.

Resource Locks (since API v2.81)

Create, list, update and delete locks on user actions on resources.

POST
/v2/resource-locks

Create a resource lock

New in version 2.81.

Lock a specific action on a given resource.

Not all resources are supported, and not actions on supported resources can be prevented with this mechanism. A lock can only be removed or manipulated by the user that created it, or by a more privileged user. The cloud administrator can use a policy.yaml file to tweak permissions on who can manipulate and delete locks created by other users.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

service_token (Optional)

header

string

An auth-token specified via the header X-Service-Token. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the service role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.

resource_lock

body

object

A resource lock object when making resource lock requests. All other parameters are included in this object.

resource_id

body

string

The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.

resource_type

body

string

The type of resource that the ID in resource_id denotes. For example, share is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for share.

resource_action (Optional)

body

string

The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of resource_action is delete. Resource locks are not supported for all API actions. Currently support only exists for delete, and for specific resources. If not provided, the value of this parameter defaults to delete.

lock_reason (Optional)

body

string

A blob of text representing the reason for the specific resource lock.

Request Example

{
    "resource_lock": {
        "resource_id": "5a313549-d346-44b6-9650-738ce08a9fee",
        "resource_type": "share",
        "resource_action": "delete",
        "lock_reason": "Locked for deletion until year end audit."
    }
}

Response Parameters

Name

In

Type

Description

resource_lock

body

object

A resource lock object when making resource lock requests. All other parameters are included in this object.

id

body

string

The UUID identifying the specific resource lock.

user_id

body

string

The ID of the user the resource lock was created for.

project_id

body

string

The ID of the project that the resource lock was created for.

lock_context

body

string

The lock creator’s context. Resource locks can be created by users with different roles. If a user with admin role creates the lock, the value of this field is admin. If a user with service role creates the lock, the value of this field is service. For all other contexts, the value of this field is user. This field also determines the user’s role that is required to unlock or manipulate a lock by virtue of the service’s default RBAC.

resource_type

body

string

The type of resource that the ID in resource_id denotes. For example, share is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for share.

resource_id

body

string

The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.

resource_action

body

string

The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of resource_action is delete. Resource locks are not supported for all API actions. Currently support only exists for delete, and for specific resources.

lock_reason

body

string

A blob of text representing the reason for the specific resource lock.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

links

body

array

Pagination and bookmark links for the resource.

Response Example

{
  "resource_lock": {
    "id": "713dc92d-bf5e-4b04-875b-2b2d284d8f94",
    "user_id": "89de351d3b5744b9853ec4829aa0e714",
    "project_id": "db2e72fef7864bbbbf210f22da7f1158",
    "lock_context": "user",
    "resource_type": "share",
    "resource_id": "5a313549-d346-44b6-9650-738ce08a9fee",
    "resource_action": "delete",
    "lock_reason": "Locked for deletion until year end audit.",
    "created_at": "2023-07-17T22:11:48.144302",
    "updated_at": null,
    "links": [
      {
        "rel": "self",
        "href": "http://203.0.113.30/share/v2/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
      },
      {
        "rel": "bookmark",
        "href": "http://203.0.113.30/share/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
      }
    ]
  }
}
GET
/v2/resource-locks

List resource locks

New in version 2.81.

Retrieve resource locks with filters

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

service_token (Optional)

header

string

An auth-token specified via the header X-Service-Token. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the service role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.

id (Optional)

query

string

The ID of the resource lock to filter resource locks by.

resource_id (Optional)

query

string

The ID of the resource that the locks pertain to to filter resource locks by.

resource_action (Optional)

query

string

The action prevented by the filtered resource locks.

resource_type (Optional)

query

string

The type of the resource that the locks pertain to to filter resource locks by.

user_id (Optional)

query

string

The ID of a user to filter resource locks by.

project_id (Optional)

query

string

The ID of a project to filter resource locks by.

all_projects (Optional)

query

string

Set this parameter to True to get resource locks across all project namespaces.

lock_context (Optional)

query

string

The lock creator’s context to filter locks by.

created_since (Optional)

query

string

Search for the list of resources that were created after the specified date. The date is in ‘yyyy-mm-dd’ format.

created_before (Optional)

query

string

Search for the list of resources that were created prior to the specified date. The date is in ‘yyyy-mm-dd’ format.

lock_reason (Optional)

query

string

The lock reason that can be used to filter resource locks.

lock_reason~ (Optional)

query

string

The lock reason pattern that can be used to filter resource locks.

sort_key (Optional)

query

string

The key to sort a list of resource locks. A valid value is id, resource_id, resource_type, resource_action, user_id, project_id, created_at, updated_act, lock_context.

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

offset (Optional)

query

integer

The offset to define start point of resource listing.

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False. This query parameter is useful with pagination.

Response Parameters

Name

In

Type

Description

resource_locks

body

object

A resource locks object containing a collection or list of resource locks.

id

body

string

The UUID identifying the specific resource lock.

user_id

body

string

The ID of the user the resource lock was created for.

project_id

body

string

The ID of the project that the resource lock was created for.

lock_context

body

string

The lock creator’s context. Resource locks can be created by users with different roles. If a user with admin role creates the lock, the value of this field is admin. If a user with service role creates the lock, the value of this field is service. For all other contexts, the value of this field is user. This field also determines the user’s role that is required to unlock or manipulate a lock by virtue of the service’s default RBAC.

resource_type

body

string

The type of resource that the ID in resource_id denotes. For example, share is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for share.

resource_id

body

string

The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.

resource_action

body

string

The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of resource_action is delete. Resource locks are not supported for all API actions. Currently support only exists for delete, and for specific resources.

lock_reason

body

string

A blob of text representing the reason for the specific resource lock.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

links

body

array

Pagination and bookmark links for the resource.

count (Optional)

body

integer

The total count of requested resource before pagination is applied. This parameter is only present in the API response if “with_count=True” is supplied in the query.

Response Example

{
  "resource_locks": [
    {
      "id": "118750ee-b62b-4cae-9a94-7da29a4f831f",
      "user_id": "89de351d3b5744b9853ec4829aa0e714",
      "project_id": "db2e72fef7864bbbbf210f22da7f1158",
      "lock_context": "user",
      "resource_type": "share",
      "resource_id": "4c0b4d35-4ea8-4811-a1e2-a065c64225a8",
      "resource_action": "delete",
      "lock_reason": null,
      "created_at": "2023-07-17T22:53:18.894553",
      "updated_at": null,
      "links": [
        {
          "rel": "self",
          "href": "http://203.0.113.30/share/v2/resource_locks/118750ee-b62b-4cae-9a94-7da29a4f831f"
        },
        {
          "rel": "bookmark",
          "href": "http://203.0.113.30/share/resource_locks/118750ee-b62b-4cae-9a94-7da29a4f831f"
        }
      ]
    },
    {
      "id": "713dc92d-bf5e-4b04-875b-2b2d284d8f94",
      "user_id": "89de351d3b5744b9853ec4829aa0e714",
      "project_id": "db2e72fef7864bbbbf210f22da7f1158",
      "lock_context": "user",
      "resource_type": "share",
      "resource_id": "5a313549-d346-44b6-9650-738ce08a9fee",
      "resource_action": "delete",
      "lock_reason": "Locked for deletion until year end audit.",
      "created_at": "2023-07-17T22:11:48.144302",
      "updated_at": null,
      "links": [
        {
          "rel": "self",
          "href": "http://203.0.113.30/share/v2/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
        },
        {
          "rel": "bookmark",
          "href": "http://203.0.113.30/share/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
        }
      ]
    }
  ]
}
GET
/v2/resource-locks/{resource-lock-id}

Get a resource lock

New in version 2.81.

Retrieve a specific resource lock

By default, resource locks can be viewed by all users within a project that owns the locks. The cloud administrator can use a policy.yaml file to tweak this behavior.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

service_token (Optional)

header

string

An auth-token specified via the header X-Service-Token. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the service role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.

resource_id

path

string

The UUID of the resource lock.

Response Parameters

Name

In

Type

Description

resource_lock

body

object

A resource lock object when making resource lock requests. All other parameters are included in this object.

id

body

string

The UUID identifying the specific resource lock.

user_id

body

string

The ID of the user the resource lock was created for.

project_id

body

string

The ID of the project that the resource lock was created for.

lock_context

body

string

The lock creator’s context. Resource locks can be created by users with different roles. If a user with admin role creates the lock, the value of this field is admin. If a user with service role creates the lock, the value of this field is service. For all other contexts, the value of this field is user. This field also determines the user’s role that is required to unlock or manipulate a lock by virtue of the service’s default RBAC.

resource_type

body

string

The type of resource that the ID in resource_id denotes. For example, share is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for share.

resource_id

body

string

The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.

resource_action

body

string

The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of resource_action is delete. Resource locks are not supported for all API actions. Currently support only exists for delete, and for specific resources.

lock_reason

body

string

A blob of text representing the reason for the specific resource lock.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

links

body

array

Pagination and bookmark links for the resource.

Response Example

{
  "resource_lock": {
    "id": "713dc92d-bf5e-4b04-875b-2b2d284d8f94",
    "user_id": "89de351d3b5744b9853ec4829aa0e714",
    "project_id": "db2e72fef7864bbbbf210f22da7f1158",
    "lock_context": "user",
    "resource_type": "share",
    "resource_id": "5a313549-d346-44b6-9650-738ce08a9fee",
    "resource_action": "delete",
    "lock_reason": "Locked for deletion until year end audit.",
    "created_at": "2023-07-17T22:11:48.144302",
    "updated_at": null,
    "links": [
      {
        "rel": "self",
        "href": "http://203.0.113.30/share/v2/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
      },
      {
        "rel": "bookmark",
        "href": "http://203.0.113.30/share/resource_locks/713dc92d-bf5e-4b04-875b-2b2d284d8f94"
      }
    ]
  }
}
PUT
/v2/resource-locks/{resource-lock-id}

Update a resource lock

New in version 2.81.

Update a specific resource lock

By default, resource locks can be updated by the user that created the lock unless the lock_context is set to admin or service. A user with service role is required to manipulate locks that have a lock_context set to service. Users with admin role can manipulate all locks. Administrators can use policy.yaml to tweak this behavior.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

service_token (Optional)

header

string

An auth-token specified via the header X-Service-Token. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the service role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.

resource_id

path

string

The UUID of the resource lock.

resource_lock

body

object

A resource lock object when making resource lock requests. All other parameters are included in this object.

resource_action (Optional)

body

string

The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of resource_action is delete. Resource locks are not supported for all API actions. Currently support only exists for delete, and for specific resources.

lock_reason (Optional)

body

string

A blob of text representing the reason for the specific resource lock.

Request Example

{
    "resource_lock": {
        "lock_reason": "This is a protected share"
    }
}

Response Parameters

Name

In

Type

Description

resource_lock

body

object

A resource lock object when making resource lock requests. All other parameters are included in this object.

id

body

string

The UUID identifying the specific resource lock.

user_id

body

string

The ID of the user the resource lock was created for.

project_id

body

string

The ID of the project that the resource lock was created for.

lock_context

body

string

The lock creator’s context. Resource locks can be created by users with different roles. If a user with admin role creates the lock, the value of this field is admin. If a user with service role creates the lock, the value of this field is service. For all other contexts, the value of this field is user. This field also determines the user’s role that is required to unlock or manipulate a lock by virtue of the service’s default RBAC.

resource_type

body

string

The type of resource that the ID in resource_id denotes. For example, share is the resource type that is specified when the resource lock pertains to a share being locked from deletion. Resource locks are not supported for all resources. Currently support only exists for share.

resource_id

body

string

The UUID of the resource that the lock pertains to. For example, this can be the ID of the share that is locked from deletion.

resource_action

body

string

The action pertaining to a resource that the resource lock prevents. For example, if a resource lock prevents deletion of a share, the value of resource_action is delete. Resource locks are not supported for all API actions. Currently support only exists for delete, and for specific resources.

lock_reason

body

string

A blob of text representing the reason for the specific resource lock.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

links

body

array

Pagination and bookmark links for the resource.

Response Example

{
  "resource_lock": {
    "id": "118750ee-b62b-4cae-9a94-7da29a4f831f",
    "user_id": "89de351d3b5744b9853ec4829aa0e714",
    "project_id": "db2e72fef7864bbbbf210f22da7f1158",
    "lock_context": "user",
    "resource_type": "share",
    "resource_id": "4c0b4d35-4ea8-4811-a1e2-a065c64225a8",
    "resource_action": "delete",
    "lock_reason": "This is a protected share",
    "created_at": "2023-07-17T22:53:18.894553",
    "updated_at": "2023-07-17T23:18:44.284565",
    "links": [
      {
        "rel": "self",
        "href": "http://203.0.113.30/share/v2/resource_locks/118750ee-b62b-4cae-9a94-7da29a4f831f"
      },
      {
        "rel": "bookmark",
        "href": "http://203.0.113.30/share/resource_locks/118750ee-b62b-4cae-9a94-7da29a4f831f"
      }
    ]
  }
}
DELETE
/v2/resource-locks/{resource-lock-id}

Delete a resource lock

New in version 2.81.

Delete a specific resource lock

By default, resource locks can be deleted by the user that created the lock unless the lock_context is set to admin or service. A user with service role is required to delete locks that have a lock_context set to service. Users with admin role can delete any lock. Administrators can use policy.yaml to tweak this behavior.

This request provides no response body.

Response codes

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

service_token (Optional)

header

string

An auth-token specified via the header X-Service-Token. With the OpenStack Identity (Keystone) context, this token can be obtained by a user that has the service role. The presence of this header is used by resource lock API methods to set or match the lock user’s context. A resource lock created by a service user cannot be manipulated by non-service users.

resource_id

path

string

The UUID of the resource lock.

Shared File Systems API (EXPERIMENTAL)

Experimental APIs

Important

The following APIs are part of the experimental feature introduced in version 2.4. The APIs may change or be removed in future versions of the Shared File Systems API. All experimental APIs require the X-OpenStack-Manila-API-Experimental: True header to be sent in the requests.

Share Migration (since API v2.22)

The Share Migration API is an administrator-only experimental API that allows the invoker to select a destination pool to migrate a share to, while still allowing clients to access the source “share instance” during migration.

Share migration is implemented in a 2-phase approach. The first phase of migration is when operations that take the longest are performed, such as data copying or replication. After first phase of data copying is complete, it is up to administrator to trigger the second phase, often referred to as switchover phase, which may perform operations such as final sync and deleting the source share instance.

During the data copy phase, user can remain connected to the source, and may have to reconnect after the switchover phase. In order to migrate a share, manila may employ one of two mechanisms which are driver-assisted migration and host-assisted migration.

  • Driver-assisted migration: This mechanism is intended to make use of driver

    optimizations to migrate shares between pools of the same storage vendor. This mechanism allows migrating shares nondisruptively while the source remains writable, preserving all filesystem metadata and snapshots. The migration workload is performed in the storage back end.

  • Host-assisted migration: This mechanism is intended to migrate

    shares in an agnostic manner between two different pools, regardless of storage vendor. The implementation for this mechanism does not offer the same properties found in driver-assisted migration. In host-assisted migration, the source remains readable, snapshots must be deleted prior to starting the migration, filesystem metadata may be lost, and the clients will get disconnected by the end of migration. The migration workload is performed by the Data Service, which is a dedicated manila service for intensive data operations.

These methods provide different capabilities and affect how efficiently the data copy and switchover are achieved. Generally speaking, driver-assisted migration is limited to homogenous storage backends and when available, is expected to be faster and more efficient than host-assisted migration. Driver-assisted migration occurs on the storage backend, while host-assisted migration occurs on the OpenStack nodes running the manila data service.

When starting a migration, driver-assisted migration is attempted first. If the shared file system service detects it is not possible to perform the driver-assisted migration, it proceeds to attempt host-assisted migration.

Possible use cases for data migration include:

  • Migrating shares along with snapshots.

  • Bring down a physical storage device for maintenance

  • Free up space in a thinly-provisioned back end.

  • Load balancing among share servers.

  • Retyping a share

Note

Share Migration APIs are experimental APIs .

POST
/v2/shares/{share_id}/action

Start Migration

New in version 2.22.

Initiates share migration. This API will initiate the share data copy to the new host. The copy operation is non-disruptive.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id

body

string

The ID of the project that owns the resource.

share_id

path

string

The UUID of the share.

force_host_assisted_migration (Optional)

body

boolean

Forces the host-assisted mechanism to be used, thus using the Data Service to copy data across back ends. This parameter value defaults to False. When set to True, it skips the driver-assisted approach which would otherwise be attempted first. If this option is set to True, all driver-assisted options must be set to False.

preserve_snapshots

body

boolean

Specifies whether migration should enforce the preservation of all existing snapshots at the destination. When set to True and drivers are not capable of migrating the snapshots, migration will result in an error status. As of Ocata release, host-assisted migration cannot provide this capability.

preserve_metadata

body

boolean

Specifies whether migration should enforce the preservation of all file system metadata. When set to True and drivers are not capable of ensuring preservation of file system metadata, migration will result in an error status. As of Ocata release, host-assisted migration cannot provide any guarantees of preserving file system metadata.

nondisruptive

body

boolean

Specifies whether migration should only be performed without disrupting clients during migration. For such, it is also expected that the export location does not change. When set to True and drivers are not capable of allowing the share to remain accessible through the two phases of the migration, migration will result in an error status. As of Ocata release, host-assisted migration cannot provide this capability.

writable

body

boolean

Specifies whether migration should only be performed if the share can remain writable. When this behavior is set to True and drivers are not capable of allowing the share to remain writable, migration will result in an error status. If drivers are not capable of performing a nondisruptive migration, manila will ensure that the share will remain writable through the data copy phase of migration. However, during the switchover phase the share will be re-exported at the destination, causing the share to be rendered inaccessible for the duration of this phase. As of Ocata release, host-assisted migration cannot provide this capability.

new_share_type_id (Optional)

body

string

If willing to retype the share so it can be allocated in the desired destination pool, the invoker may supply a new share type to be used. This is often suited when the share is to be migrated to a pool which operates in the opposite driver mode.

new_share_network_id (Optional)

body

string

If willing to change the share’s share-network so it can be allocated in the desired destination pool, the invoker may supply a new share network to be used. This is often suited when the share is to be migrated to a pool which operates in a different availability zone or managed by a driver that handles share servers.

host

body

string

The target pool to which the share should be migrated to, in format host@backend#pool. E.g. ubuntu@generic1#GENERIC1.

Request example

{
    "migration_start":
        {
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "writable": true,
            "preserve_snapshots": true,
            "preserve_metadata": true,
            "nondisruptive": true,
            "host": "ubuntu@generic2#GENERIC2",
            "new_share_type_id": "foo_share_type_id",
            "new_share_network_id": "bar_share_network_id",
            "force_host_assisted_migration": false
        }
}
POST
/v2/shares/{share_id}/action

Complete Migration

New in version 2.22.

Completes share migration. This API will initiate the switch-over from the source to destination share. This operation can be disruptive.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id

body

string

The ID of the project that owns the resource.

share_id

path

string

The UUID of the share.

Request example

{
    "migration_complete":
        {
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
        }
}
POST
/v2/shares/{share_id}/action

Migration Get Process

New in version 2.22.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

share_id

path

string

The UUID of the share.

project_id

body

string

The ID of the project that owns the resource.

Response parameters

Name

In

Type

Description

details

body

object

Additional driver specific details of the migration progress.

New in version 2.59

total_progress

body

integer

Defines a total progress of share migration.

task_state

body

string

For the share migration, the migration task state. A valid value is null, migration_starting, migration_error, migration_success, migration_completing, or migrating. The task_state is null unless the share is migrated from one back-end to another.

New in version 2.5

Request example

{
    "migration_get_process":
        {
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
        }
}

Response_parameters

{
    "total_progress": 100,
    "task_state": "migration_driver_phase1_done"
}
POST
/v2/shares/{share_id}/action

Cancel Migration

New in version 2.22.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

share_id

path

string

The UUID of the share.

project_id

body

string

The ID of the project that owns the resource.

Request example

{
    "migration_cancel":
        {
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
        }
}

Share Server Migration (since API v2.57)

The Share Server Migration API is an administrator-only experimental API that allows the invoker to select a destination backend to migrate a share server to.

Share server migration uses a 2-phased approach. In the first phase of the migration, the data copying or replication operations are performed, so it’s the longer phase. After the first phase is finished, the administrator can trigger the second phase, which consists in final syncs and making the new share server available to be used and the latter one inactive.

During the data copy phase, source shares will remain available and writable if it was required by the administrator and supported by the share driver. After the second phase, users may need to reconnect to the shares affected by the migration. All shares belonging to a share server are migrated and their access rules are preserved through the migration. The share snapshots are going to be copied if specified by the administrator and/or supported by the driver.

Important

In order to migrate a share server, the administrator must make sure that none of the shares on the server are replicated or in a share group.

Note

Share Server Migration APIs are experimental APIs .

Possible uses for share server migration include:

  • Migrating a share server and all its shares and snapshots at once.

  • Bring down a physical storage device for maintenance.

  • Free up space in a thinly-provisioned back end.

  • Load balancing among backends.

POST
/v2/{project_id}/share_servers/{share_server_id}/action

Share Server Migration Check Compatibility

New in version 2.57.

Checks if a share driver can handle a share server migration according to the specified destination host and new_share_network_id, as well as the writable, nondisruptive and preserve_snapshots flags.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id

body

string

The ID of the project that owns the resource.

share_server_id

body

string

The UUID of the share server.

preserve_snapshots

body

boolean

Specifies whether migration should enforce the preservation of all existing snapshots at the destination. When set to True and drivers are not capable of migrating the snapshots, migration will result in an error status.

nondisruptive

body

boolean

Specifies whether share server migration should only be performed without disrupting clients during migration. For such, it is also expected that the export location does not change. When set to True and drivers are not capable of allowing the share server to remain accessible through the two phases of the migration, migration will result in an error status.

writable

body

boolean

Specifies whether migration should only be performed if the shares can remain writable. When this behavior is set to True and drivers are not capable of allowing the shares to remain writable, migration will result in an error status. If drivers are not capable of performing a nondisruptive migration, manila will ensure that the shares will remain writable through the data copy phase of migration. However, during the switchover phase all shares will be re-exported at the destination, causing the shares to be rendered inaccessible for the duration of this phase.

new_share_network_id (Optional)

body

string

If willing to change the share server’s share-network so it can be allocated in the desired destination backend, the invoker may supply a new share network to be used.

host

body

string

The target backend to which the share server should be migrated to, in format host@backend. E.g. ubuntu@generic1.

Response parameters

Name

In

Type

Description

compatible

body

boolean

Whether the destination backend can or can’t handle the share server migration considering the received entries for share_network_id, host, nondisruptive, writable and preserve_snapshots matched with the driver supported capabilities.

requested_capabilities

body

object

The parameters that were sent to the server in order to check if the destination host can handle the share server migration. This object contains the following attributes: writable, nondisruptive, preserve_snapshots, share_network_id and host.

supported_capabilities

body

object

The driver’s supported attributes for a share server migration. It will contain the following items: writable, nondisruptive, preserve_snapshots and share_network_id. Drivers will also report if they can perform migration_cancel and migration_get_progress operations. All of the mentioned parameters will be present in this object. All parameters but the share_network_id are boolean values.

Request example

{
    "migration_check": {
        "host": "foohost2@backend2",
        "preserve_snapshots": "True",
        "writable": "True",
        "nondisruptive": "True",
        "new_share_network_id": null
    }
}

Response example

{
    "compatible": false,
    "requested_capabilities": {
        "writable": "True",
        "nondisruptive": "True",
        "preserve_snapshots": "True",
        "share_network_id": null,
        "host": "foohost2@backend2"
    },
    "supported_capabilities": {
        "writable": true,
        "nondisruptive": false,
        "preserve_snapshots": true,
        "share_network_id": "1d04b755-649f-46a4-964c-be9f0395af13",
        "migration_cancel": true,
        "migration_get_progress": true
    }
}
POST
/v2/{project_id}/share_servers/{share_server_id}/action

Start a Share Server Migration

New in version 2.57.

Triggers a share server migration. This API will initiate the first phase of the share server migration to a new host.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

project_id

body

string

The ID of the project that owns the resource.

share_server_id

body

string

The UUID of the share server.

preserve_snapshots

body

boolean

Specifies whether migration should enforce the preservation of all existing snapshots at the destination. When set to True and drivers are not capable of migrating the snapshots, migration will result in an error status.

nondisruptive

body

boolean

Specifies whether share server migration should only be performed without disrupting clients during migration. For such, it is also expected that the export location does not change. When set to True and drivers are not capable of allowing the share server to remain accessible through the two phases of the migration, migration will result in an error status.

writable

body

boolean

Specifies whether migration should only be performed if the shares can remain writable. When this behavior is set to True and drivers are not capable of allowing the shares to remain writable, migration will result in an error status. If drivers are not capable of performing a nondisruptive migration, manila will ensure that the shares will remain writable through the data copy phase of migration. However, during the switchover phase all shares will be re-exported at the destination, causing the shares to be rendered inaccessible for the duration of this phase.

new_share_network_id (Optional)

body

string

If willing to change the share server’s share-network so it can be allocated in the desired destination backend, the invoker may supply a new share network to be used.

host

body

string

The target backend to which the share server should be migrated to, in format host@backend. E.g. ubuntu@generic1.

Request example

{
    "migration_start": {
        "host": "foohost2@backend2",
        "preserve_snapshots": "True",
        "writable": "True",
        "nondisruptive": "False",
        "new_share_network_id": null
    }
}
POST
/v2/{project_id}/share_servers/{share_server_id}/action

Complete Share Server Migration

New in version 2.57.

Completes share server migration. This API will initiate the switch-over from the source to destination share server. This operation can be disruptive.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

body

string

The ID of the project that owns the resource.

share_server_id

body

string

The UUID of the share server.

Response parameters

Name

In

Type

Description

total_progress

body

integer

Defines a total progress of share server migration.

task_state

body

string

For the share server migration, the migration task state. A valid value is null, migration_in_progress, migration_cancel_in_progress, migration_cancelled, migration_driver_starting, migration_driver_in_progress, or migration_phase_1_done.

destination_share_server_id

body

string

UUID of the share server that was created in the destination backend during a share server migration operation.

Request example

{
    "migration_complete": null
}

Response example

{
    "destination_share_server_id": "c2f71561-85e2-4ccb-a91a-e44f9ff6f7ef"
}
POST
/v2/{project_id}/share_servers/{share_server_id}/action

Share Server Migration Get Progress

New in version 2.57.

Returns the completed percentage and the destination share server id of an ongoing share server migration.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

409 - Conflict

This resource has an action in progress that would conflict with this request.

Request

Name

In

Type

Description

share_server_id

body

string

The UUID of the share server.

project_id

body

string

The ID of the project that owns the resource.

Response parameters

Name

In

Type

Description

total_progress

body

integer

Defines a total progress of share server migration.

task_state

body

string

For the share server migration, the migration task state. A valid value is null, migration_in_progress, migration_cancel_in_progress, migration_cancelled, migration_driver_starting, migration_driver_in_progress, or migration_phase_1_done.

destination_share_server_id

body

string

UUID of the share server that was created in the destination backend during a share server migration operation.

Request example

{
    "migration_get_progress": null
}

Response example

{
    "total_progress": 50,
    "task_state": "migration_driver_in_progress",
    "destination_share_server_id": "c2f71561-85e2-4ccb-a91a-e44f9ff6f7ef"
}
POST
/v2/{project_id}/share_servers/{share_server_id}/action

Cancel Share Server Migration

New in version 2.57.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

share_server_id

body

string

The UUID of the share server.

project_id

body

string

The ID of the project that owns the resource.

Request example

{
    "migration_cancel":null
}

Share backups (since API v2.80)

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

You can create, restore, update, list and delete share backups. After you create a share backup, you can access backup and use it. You can also restore a backup into a share as long as certain criteria are met e.g. size.

You can update a share backup to change its name or description. As administrator, you can also reset the state of a backup. Backup can be in one of the following states:

  • available

  • error

  • creating

  • deleting

  • restoring

During a backup or restore operation, share can be in one of the following states:

  • available

  • backup_creating

  • backup_restoring

  • backup_restoring_error

GET
/v2/share-backups

List share backups

New in version 2.80.

Lists all share backups.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

Request

Name

In

Type

Description

share_id (Optional)

query

string

The UUID of the share that the backup pertains to.

name~ (Optional)

query

string

The name pattern that can be used to filter share backups.

description~ (Optional)

query

string

The description pattern that can be used to filter share backups.

limit (Optional)

query

integer

The maximum number of resource records to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of share backups. A valid value is id, status, size, host, share_id availability_zone, created_at, updated_at, display_name, topic, progress and restore_progress

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

status (Optional)

query

string

Filters by a backup status. A valid filter value can be one of ‘creating’, ‘error’, ‘available’, ‘restoring’.

host (Optional)

query

string

The host name of the backup to query with. Querying by hostname is a privileged operation. If restricted by API policy, this query parameter may be silently ignored by the server.

topic (Optional)

query

string

Filters by a backup topic. A valid filter value can be one of ‘manila-data’, ‘manila-share’.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share backup.

share_id

body

string

The UUID of the share that the backup pertains to.

status

body

string

The status of backup which can be one of creating, error, available, restoring.

Response example

{
    "share_backups": [
        {
            "id": "1125c47a-0216-4ee0-a517-0460d63301a6",
            "name": "backup3",
            "share_id": "112dffd-f033-4248-a315-319ca2bd70c8",
            "status": "available"
        },
        {
            "id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
            "name": "backup1",
            "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
            "status": "creating"
        }
    ]
}
GET
/v2/share-backups/detail

List share backups with details

New in version 2.80.

Lists all share backups with details.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

Request

Name

In

Type

Description

share_id (Optional)

query

string

The UUID of the share that the backup pertains to.

name~ (Optional)

query

string

The name pattern that can be used to filter share backups.

description~ (Optional)

query

string

The description pattern that can be used to filter share backups.

limit (Optional)

query

integer

The maximum number of resource records to return.

offset (Optional)

query

integer

The offset to define start point of resource listing.

sort_key (Optional)

query

string

The key to sort a list of share backups. A valid value is id, status, size, host, share_id availability_zone, created_at, updated_at, display_name, topic, progress and restore_progress

sort_dir (Optional)

query

string

The direction to sort a list of resources. A valid value is asc, or desc.

status (Optional)

query

string

Filters by a backup status. A valid filter value can be one of ‘creating’, ‘error’, ‘available’, ‘restoring’.

host (Optional)

query

string

The host name of the backup to query with. Querying by hostname is a privileged operation. If restricted by API policy, this query parameter may be silently ignored by the server.

topic (Optional)

query

string

Filters by a backup topic. A valid filter value can be one of ‘manila-data’, ‘manila-share’.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share backup.

share_id

body

string

The UUID of the share that the backup pertains to.

status

body

string

The status of backup which can be one of creating, error, available, restoring.

size

body

integer

The share backup size, in GiBs.

availability_zone

body

string

The availability zone.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

progress

body

string

The progress of the backup creation in percentange.

restore_progress

body

string

The progress of the backup restoration in percentage.

Response example

{
    "share_backups": [
        {
            "id": "1125c47a-0216-4ee0-a517-0460d63301a6",
            "share_id": "112dffd-f033-4248-a315-319ca2bd70c8",
            "status": "available",
            "name": "backup3",
            "description": null,
            "size": 1,
            "created_at": "2023-08-16T12:34:57.000000",
            "updated_at": "2023-08-17T12:14:15.000000",
            "availability_zone": null,
            "progress": "100",
            "restore_progress": "0"
        },
        {
            "id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
            "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
            "status": "creating",
            "name": "backup1",
            "description": null,
            "size": 1,
            "created_at": "2023-08-16T13:03:59.020692",
            "updated_at": "2023-08-16T13:13:15.000002",
            "availability_zone": null,
            "progress": "0",
            "restore_progress": "0"
        }
    ]
}
GET
/v2/share-backups/{backup_id}

Show share backup details

New in version 2.80.

Shows details for a share backup.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

backup_id

path

string

The UUID of the share backup.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share backup.

share_id

body

string

The UUID of the share that the backup pertains to.

status

body

string

The status of backup which can be one of creating, error, available, restoring.

size

body

integer

The share backup size, in GiBs.

availability_zone

body

string

The availability zone.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

progress

body

string

The progress of the backup creation in percentange.

restore_progress

body

string

The progress of the backup restoration in percentage.

Response example

{
    "share_backup": {
        "id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
        "status": "available",
        "name": "backup1",
        "description": null,
        "size": 1,
        "created_at": "2023-08-16T13:03:59.000000",
        "updated_at": "2023-08-16T13:04:15.000000",
        "availability_zone": null,
        "progress": "100",
        "restore_progress": "0"
    }
}
POST
/v2/share-backups

Create share backup

New in version 2.80.

Creates a backup from a share.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

422 - Unprocessable Entity

The entity of the request is in a format not processable by the requested resource for the method.

Request

Name

In

Type

Description

share_id

body

string

The UUID of the share that the backup pertains to.

name (Optional)

body

string

The user defined name of the resource. The value of this field is limited to 255 characters.

description (Optional)

body

string

The user defined description of the resource. The value of this field is limited to 255 characters.

backup_options (Optional)

body

object

One or more backup options key and value pairs as a url encoded dictionary of strings.

Request example

{
    "share_backup": {
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
        "backup_options": {},
        "description": null,
        "name": "backup1"
    }
}

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share backup.

share_id

body

string

The UUID of the share that the backup pertains to.

status

body

string

The status of backup which can be one of creating, error, available, restoring.

size

body

integer

The share backup size, in GiBs.

availability_zone

body

string

The availability zone.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

progress

body

string

The progress of the backup creation in percentange.

restore_progress

body

string

The progress of the backup restoration in percentage.

Response example

{
    "share_backup": {
        "id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
        "status": "creating",
        "name": "backup1",
        "description": null,
        "size": 1,
        "created_at": "2023-08-16T13:03:59.020692",
        "updated_at": "2023-08-16T13:03:59.020692",
        "availability_zone": null,
        "progress": "0",
        "restore_progress": "0"
    }
}
PUT
/v2/share-backups/{backup_id}

Update share backup

New in version 2.80.

Updates a share backup.

You can update these attributes:

  • display_name, which changes the name of the share backup.

  • display_description, which changes the description of the share backup.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

backup_id

path

string

The UUID of the share backup.

display_name (Optional)

body

string

The user defined name of the resource. This field sets the name parameter.

display_description (Optional)

body

string

The user defined description of the resource. This field sets the description parameter.

Request example

{
    "share_backup": {
        "display_name": "backup2",
        "display_description": "I am changing a description also. Here is a backup"
    }
}

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share backup.

share_id

body

string

The UUID of the share that the backup pertains to.

status

body

string

The status of backup which can be one of creating, error, available, restoring.

size

body

integer

The share backup size, in GiBs.

availability_zone

body

string

The availability zone.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

The date and time stamp when the resource was created within the service’s database.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2019-03-27T09:49:58-05:00.

updated_at

body

string

The date and time stamp when the resource was last updated within the service’s database. If a resource was never updated after it was created, the value of this parameter is set to null.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2016-12-31T13:14:15-05:00.

progress

body

string

The progress of the backup creation in percentange.

restore_progress

body

string

The progress of the backup restoration in percentage.

Response example

{
    "share_backup": {
        "id": "fa32a89f-ed0f-4906-b1d7-92eedf98fbb5",
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30",
        "status": "available",
        "name": "backup2",
        "description": "I am changing a description also. Here is a backup",
        "size": 1,
        "created_at": "2023-08-16T13:18:55.000000",
        "updated_at": "2023-08-16T13:33:15.000000",
        "availability_zone": null,
        "progress": "100",
        "restore_progress": "0"
    }
}
DELETE
/v2/share-backups/{backup_id}

Delete share backup

New in version 2.80.

Deletes a share backup.

Preconditions

  • Share backup status must be available or error.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

backup_id

path

string

The UUID of the share backup.

POST
/v2/share-backups/{backup_id}/action

Restore a share backup

New in version 2.80.

Restores a share backup into original share.

Preconditions

  • Share backup status must be available.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

backup_id

path

string

The UUID of the share backup.

Request example

{
    "restore": null
}

Response parameters

Name

In

Type

Description

backup_id

body

string

The UUID of the share backup.

share_id

body

string

The UUID of the share that the backup pertains to.

Response example

{
    "restore": {
        "backup_id": "c1cdc0ce-4ddc-4018-9796-505d2e26fcc7",
        "share_id": "7b11dd53-546e-43cd-af0e-875434238c30"
    }
}
POST
/v2/share-backups/{backup_id}/action

Reset share backup status

New in version 2.80.

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id (Optional)

path

string

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

backup_id

path

string

The UUID of the share backup.

status (Optional)

body

string

The backup status, which can be available, error, creating, deleting, restoring.

Request example

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