Shared File Systems API

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

The share links

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

The share links

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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

  • Number of share-networks.

  • Number of share-snapshots.

  • Number of shares.

  • Shares and total used memory, in GBs.

  • Snapshots and total used memory, in GBs.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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.

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.

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

Shares

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

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

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

  • NFS. Network File System (NFS).

  • CIFS. Common Internet File System (CIFS).

  • GLUSTERFS. Gluster file system (GlusterFS).

  • HDFS. Hadoop Distributed File System (HDFS).

  • CEPHFS. Ceph File System (CephFS).

  • MAPRFS. MapR File System (MAPRFS).

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

A share has one of these status values:

Share statuses

Status

Description

creating

The share is being created.

deleting

The share is being deleted.

deleted

The share was deleted.

error

An error occurred during share creation.

error_deleting

An error occurred during share deletion.

available

The share is ready to use.

inactive

The share is inactive.

manage_starting

Share manage started.

manage_error

Share manage failed.

unmanage_starting

Share unmanage started.

unmanage_error

Share cannot be unmanaged.

unmanaged

Share was unmanaged.

extending

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

extending_error

Extend share failed.

shrinking

Share is being shrunk.

shrinking_error

Failed to update quota on share shrinking.

shrinking_possible_data_loss_error

Shrink share failed due to possible data loss.

migrating

Share is currently migrating.

migrating_to

Share is a migration destination.

replication_change

The share is undergoing a replication change.

reverting

Share is being reverted to a snapshot.

reverting_error

Share revert to snapshot failed.

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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. A valid value is creating, error, available, deleting, error_deleting, manage_starting, manage_error, unmanage_starting, unmanage_error, migrating, extending, extending_error, shrinking, shrinking_error, or shrinking_possible_data_loss_error.

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.

New in version 2.43

share_type_id (Optional)

query

string

The UUID of a share type to query resources by.

snapshot_id (Optional)

query

string

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

host (Optional)

query

string

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

share_network_id (Optional)

query

string

The UUID of the share network to filter resources by.

project_id (Optional)

query

string

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

is_public (Optional)

query

boolean

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

share_group_id (Optional)

query

string

The UUID of a share group to filter resource.

New in version 2.31

export_location_id (Optional)

query

string

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

New in version 2.35

export_location_path (Optional)

query

string

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

New in version 2.35

name~ (Optional)

query

string

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

New in version 2.36

description~ (Optional)

query

string

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

New in version 2.36

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False.

New in version 2.42

limit (Optional)

query

integer

The maximum number of shares to return.

offset (Optional)

query

integer

The offset to define start point of share or share group listing.

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share.

links

body

array

The share links

name

body

string

The user defined name of the resource.

count (Optional)

body

integer

The total count of requested resource before pagination is applied.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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. A valid value is creating, error, available, deleting, error_deleting, manage_starting, manage_error, unmanage_starting, unmanage_error, migrating, extending, extending_error, shrinking, shrinking_error, or shrinking_possible_data_loss_error.

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.

New in version 2.43

share_type_id (Optional)

query

string

The UUID of a share type to query resources by.

name (Optional)

query

string

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

snapshot_id (Optional)

query

string

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

host (Optional)

query

string

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

share_network_id (Optional)

query

string

The UUID of the share network to filter resources by.

project_id (Optional)

query

string

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

is_public (Optional)

query

boolean

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

share_group_id (Optional)

query

string

The UUID of a share group to filter resource.

New in version 2.31

export_location_id (Optional)

query

string

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

New in version 2.35

export_location_path (Optional)

query

string

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

New in version 2.35

name~ (Optional)

query

string

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

New in version 2.36

description~ (Optional)

query

string

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

New in version 2.36

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False.

New in version 2.42

limit (Optional)

query

integer

The maximum number of shares to return.

offset (Optional)

query

integer

The offset to define start point of share or share group listing.

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

Response parameters

Name

In

Type

Description

share_type_name

body

string

Name of the share type.

links

body

array

The share links

availability_zone (Optional)

body

string

The availability zone.

New in version 2.1

share_network_id

body

string

The share network ID.

export_locations (Optional)

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

share_type

body

string

The UUID of the share type. In minor versions, this parameter is a share type name, as a string.

New in version 2.6

export_location (Optional)

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 (Optional)

body

object

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

status

body

string

The share status, which is creating, error, available, deleting, error_deleting, manage_starting, manage_error, unmanage_starting, unmanage_error, unmanaged, extend, extending_error, shrinking, shrinking_error, or shrinking_possible_data_loss_error.

description

body

string

The user defined description of the resource.

host

body

string

The share host name.

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

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share public. Set to false to make it private. Default value is false.

New in version 2.8

share_group_id

body

string

The UUID of the share group.

New in version 2.31

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. For details, see os-migrate_share extension request.

New in version 2.5

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.

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

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.

volume_type (Optional)

body

string

The volume type. 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. When you issue a create a share type request, you can submit a request body with either a share_type or volume_type object. 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_types and volume_types objects.

count (Optional)

body

integer

The total count of requested resource before pagination is applied.

New in version 2.42

Response example

{
    "shares": [
        {
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "share_network_id": "f9b2e754-ac01-4466-86e1-5c569424754e",
            "export_locations": [],
            "share_server_id": "87d8943a-f5da-47a4-b2f2-ddfa6794aa82",
            "share_group_id": null,
            "snapshot_id": null,
            "id": "f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc",
            "size": 1,
            "share_type": "25747776-08e5-494f-ab40-a64b9d20d8f7",
            "share_type_name": "default",
            "export_location": null,
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "metadata": {},
            "status": "error",
            "access_rules_status": "active",
            "description": "There is a share 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-16T18:19:50.000000",
            "share_proto": "NFS",
            "volume_type": "default"
        },
        {
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/c4a2ced4-2c9f-4ae1-adaa-6171833e64df",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/c4a2ced4-2c9f-4ae1-adaa-6171833e64df",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "share_network_id": "f9b2e754-ac01-4466-86e1-5c569424754e",
            "export_locations": [
                "10.254.0.5:/shares/share-50ad5e7b-f6f1-4b78-a651-0812cef2bb67"
            ],
            "share_server_id": "87d8943a-f5da-47a4-b2f2-ddfa6794aa82",
            "snapshot_id": null,
            "id": "c4a2ced4-2c9f-4ae1-adaa-6171833e64df",
            "size": 1,
            "share_type": "25747776-08e5-494f-ab40-a64b9d20d8f7",
            "share_type_name": "default",
            "export_location": "10.254.0.5:/shares/share-50ad5e7b-f6f1-4b78-a651-0812cef2bb67",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "metadata": {},
            "status": "available",
            "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",
            "share_proto": "NFS",
            "volume_type": "default"
        }
    ],
    "count": 10
}
GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_id

path

string

The UUID of the share.

Response parameters

Name

In

Type

Description

share_type_name

body

string

Name of the share type.

links

body

array

The share links

availability_zone

body

string

The availability zone.

share_network_id

body

string

The share network ID.

export_locations (Optional)

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

share_type

body

string

The UUID of the share type. In minor versions, this parameter is a share type name, as a string.

New in version 2.6

export_location (Optional)

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 (Optional)

body

object

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

status

body

string

The share status, which is creating, error, available, deleting, error_deleting, manage_starting, manage_error, unmanage_starting, unmanage_error, unmanaged, extend, extending_error, shrinking, shrinking_error, or shrinking_possible_data_loss_error.

description

body

string

The user defined description of the resource.

host (Optional)

body

string

The share host name.

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

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share public. Set to false to make it private. Default value is false.

New in version 2.8

share_group_id

body

string

The UUID of the share group.

New in version 2.31

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. For details, see os-migrate_share extension request.

New in version 2.5

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.

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

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.

volume_type (Optional)

body

string

The volume type. 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. When you issue a create a share type request, you can submit a request body with either a share_type or volume_type object. 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_types and volume_types objects.

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",
        "description": "My custom share London",
        "host": "manila2@generic1#GENERIC1",
        "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"
    }
}
POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 GBs. The requested share size cannot be greater than the allowed GB 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 share type name. 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. You cannot specify both the share_type and volume_type parameters.

volume_type (Optional)

body

string

The volume type. 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. When you issue a create a share type request, you can submit a request body with either a share_type or volume_type object. 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_types and volume_types objects.

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 public. Set to false to make it private. Default value is false.

New in version 2.8

share_group_id (Optional)

body

string

The UUID of the share group.

New in version 2.31

metadata (Optional)

body

object

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

share_network_id (Optional)

body

string

The UUID of a share network where the share server exists or will be created. If share_network_id is None and you provide a snapshot_id, the share_network_id value from the snapshot is used.

availability_zone (Optional)

body

string

The availability zone.

New in version 2.1

Request example

{
    "share": {
        "description": "My custom share London",
        "share_type": null,
        "share_proto": "nfs",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "share_group_id": null,
        "name": "share_London",
        "snapshot_id": null,
        "is_public": true,
        "size": 1,
        "metadata": {
            "project": "my_app",
            "aim": "doc"
        }
    }
}

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share.

status

body

string

The share status. A valid value is: - creating. The share is being created. - deleting. The share is being deleted. - error. An error occurred during share creation. - error_deleting. An error occurred during share deletion. - available. The share is ready to use. - 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.

links

body

array

The share links

project_id

body

string

The ID of the project that owns the resource.

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 GBs. The requested share size cannot be greater than the allowed GB quota. To view the allowed quota, issue a get limits request.

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

share_type

body

string

The UUID of the share type. In minor versions, this parameter is a share type name, as a string.

New in version 2.6

share_type_name

body

string

Name of the share type.

New in version 2.6

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

volume_type (Optional)

body

string

The volume type. 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. When you issue a create a share type request, you can submit a request body with either a share_type or volume_type object. 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_types and volume_types objects.

snapshot_id

body

string

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

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share public. Set to false to make it private. Default value is false.

New in version 2.8

share_group_id

body

string

The UUID of the share group.

New in version 2.31

metadata (Optional)

body

object

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

share_network_id

body

string

The share network ID.

availability_zone

body

string

The availability zone.

export_location (Optional)

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 (Optional)

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

host

body

string

The share host name.

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. For details, see os-migrate_share extension request.

New in version 2.5

share_server_id

body

string

The UUID of the share server.

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

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": {
        "status": 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"
    }
}
GET
/v2/{project_id}/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.json file to grant permissions for this action to other roles.

Note

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

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

422 - Unprocessable Entity

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

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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 share type name.

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. \\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 public. Set to false to make it private. 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

share

body

object

A share object.

links

body

array

The share links

availability_zone

body

string

The availability zone.

share_network_id

body

string

The share network ID.

export_locations (Optional)

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

share_type

body

string

The UUID of the share type. In minor versions, this parameter is a share type name, as a string.

New in version 2.6

share_type_name

body

string

Name of the share type.

New in version 2.6

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

export_location (Optional)

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 (Optional)

body

object

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

status

body

string

The share status, which is available, manage_starting, or manage_error.

share_server_id

body

string

The UUID of the share server.

New in version 2.49

description

body

string

The user defined description of the resource.

host (Optional)

body

string

The share host name.

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share public. Set to false to make it private. Default value is false.

New in version 2.8

share_group_id

body

string

The UUID of the share group.

New in version 2.31

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.

volume_type (Optional)

body

string

The volume type. 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. When you issue a create a share type request, you can submit a request body with either a share_type or volume_type object. 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_types and volume_types objects.

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.",
        "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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 public. Set to false to make it private. Default value is false.

New in version 2.8

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

share_type_name

body

string

Name of the share type.

New in version 2.6

links

body

array

The share links

availability_zone

body

string

The availability zone.

share_network_id

body

string

The share network ID.

export_locations (Optional)

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

share_type

body

string

The UUID of the share type. In minor versions, this parameter is a share type name, as a string.

New in version 2.6

export_location (Optional)

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 (Optional)

body

object

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

status

body

string

The share status, which is creating, error, available, deleting, error_deleting, manage_starting, manage_error, unmanage_starting, unmanage_error, unmanaged, extend, extending_error, shrinking, shrinking_error, or shrinking_possible_data_loss_error.

description

body

string

The user defined description of the resource.

host (Optional)

body

string

The share host name.

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

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share public. Set to false to make it private. Default value is false.

New in version 2.8

share_group_id

body

string

The UUID of the share group.

New in version 2.31

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. For details, see os-migrate_share extension request.

New in version 2.5

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.

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

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.

volume_type (Optional)

body

string

The volume type. 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. When you issue a create a share type request, you can submit a request body with either a share_type or volume_type object. 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_types and volume_types objects.

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"
    }
}
DELETE
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_id

path

string

The UUID of the share.

Response parameters

Name

In

Type

Description

id

body

string

The share export location UUID.

share_instance_id

body

string

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

path

body

string

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

is_admin_only

body

boolean

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

preferred

body

boolean

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

New in version 2.14

Response example

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

path

string

The project ID of the user or service making the API request.

share_id

path

string

The UUID of the share.

export_location_id

path

string

The UUID of the export location.

Response parameters

Name

In

Type

Description

id

body

string

The share export location UUID.

share_instance_id

body

string

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

path

body

string

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

is_admin_only

body

boolean

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

preferred

body

boolean

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

New in version 2.14

created_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

updated_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

Response example

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

Share metadata

Shows, sets, updates, and unsets share metadata.

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_id

path

string

The UUID of the share.

key

body

object

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

Response parameters

Name

In

Type

Description

metadata

body

object

A single metadata key and value pair.

Response example

{
    "meta": {
        "project": "my_app"
    }
}
POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 (Optional)

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_id

path

string

The UUID of the share.

key

body

object

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

Share actions

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

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

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

  • available

  • error

  • creating

  • deleting

  • error_deleting

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

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

POST
/v2/{project_id}/shares/{share_id}/action

Grant access

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

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

  • rw. Read and write (RW) access.

  • ro. Read-only (RO) access.

You must also specify one of these supported authentication methods:

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

Important

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

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

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

Grants access to a share.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - 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_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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - cert. Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. - user. Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_metadata (Optional)

body

object

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

Request example

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

Response parameters

Name

In

Type

Description

share_id

body

string

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

created_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

updated_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

access_type

body

string

The access rule type. A valid value for the share access rule type is one of the following values: - ip. Authenticates an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - 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_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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - cert. Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation. - user. Authenticates by a user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

access_key

body

string

The access credential of the entity granted share access.

New in version 2.21

access

body

object

The access object.

access_level

body

string

The access level to the share. To grant or deny access to a share, you specify one of the following share access levels: - rw. Read and write (RW) access. - ro. Read- only (RO) access.

id

body

string

The access rule ID.

access_metadata

body

object

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

Response example

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

Revoke access

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

share_id

path

string

The UUID of the share.

deny_access

body

object

The deny_access object.

access_id

body

string

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

Request example

{
    "deny_access": {
        "access_id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452"
    }
}
POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - 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_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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - 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/{project_id}/shares/{share_id}/action

Reset share state

Administrator only. Explicitly updates the state of a share.

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

share_id

path

string

The UUID of the share.

reset_status

body

object

The reset_status object.

status

body

string

The share access status, which is new, error, active.

Request example

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

Force-delete share

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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

Request example

{
    "extend": {
        "new_size": 2
    }
}
POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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

Request example

{
    "shrink": {
        "new_size": 1
    }
}
POST
/v2/{project_id}/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.json file to grant permissions for this action to other roles.

Preconditions:

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

Note

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

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

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_id

path

string

The UUID of the share.

snapshot_id

body

string

The UUID of the snapshot.

Request example

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

Share snapshots

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

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

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

  • available

  • error

  • creating

  • deleting

  • error_deleting

  • manage_starting

  • manage_error

  • unmanage_starting

  • unmanage_error

  • restoring

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

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

all_tenants (Optional)

query

boolean

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

name~ (Optional)

query

string

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

New in version 2.36

description~ (Optional)

query

string

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

New in version 2.36

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the snapshot.

name

body

string

The user defined name of the resource.

Response example

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

path

string

The project ID of the user or service making the API request.

all_tenants (Optional)

query

boolean

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

name~ (Optional)

query

string

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

New in version 2.36

description~ (Optional)

query

string

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

New in version 2.36

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the snapshot.

status

body

string

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

share_id

body

string

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

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

created_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

share_proto

body

string

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

share_size

body

integer

The share snapshot size, in GBs.

size

body

integer

The snapshot size, in GBs.

project_id

body

string

ID of the project that the snapshot belongs to.

New in version 2.17

user_id

body

string

ID of the user that the snapshot was created by.

New in version 2.17

Response example

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

path

string

The project ID of the user or service making the API request.

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

size

body

integer

The snapshot size, in GBs.

project_id

body

string

ID of the project that the snapshot belongs to.

New in version 2.17

user_id

body

string

ID of the user that the snapshot was created by.

New in version 2.17

Response example

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

Create share snapshot

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

path

string

The project ID of the user or service making the API request.

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

provider_location

body

string

Provider location of the snapshot on the backend.

size

body

integer

The snapshot size, in GBs.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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

provider_location

body

string

Provider location of the snapshot on the backend.

size

body

integer

The snapshot size, in GBs.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/snapshots/{snapshot_id}/action

Reset share snapshot state

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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/{project_id}/snapshots/{snapshot_id}/action

Force-delete share snapshot

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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

size

body

integer

The snapshot size, in GBs.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

snapshot_id

path

string

The UUID of the snapshot.

Share snapshot instances (since API v2.19)

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

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

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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.json file to grant permissions for this action to other roles.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

all_tenants (Optional)

query

boolean

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

name~ (Optional)

query

string

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

New in version 2.36

description~ (Optional)

query

string

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

New in version 2.36

Response parameters

Name

In

Type

Description

id

body

string

The share network ID.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

all_tenants (Optional)

query

boolean

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

name~ (Optional)

query

string

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

New in version 2.36

description~ (Optional)

query

string

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

New in version 2.36

Response parameters

Name

In

Type

Description

id

body

string

The share network ID.

project_id

body

string

The ID of the project that owns the resource.

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.

segmentation_id

body

integer

The segmentation ID.

cidr

body

string

The CIDR.

ip_version

body

integer

The IP version of the network. A valid value is 4 or 6.

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

mtu

body

integer

The MTU value of a share network.

New in version 2.20

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
        }
    ]
}
GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_network_id

path

string

The UUID of the share network.

Response parameters

Name

In

Type

Description

id

body

string

The share network ID.

project_id

body

string

The ID of the project that owns the resource.

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.

segmentation_id

body

integer

The segmentation ID.

cidr

body

string

The CIDR.

ip_version

body

integer

The IP version of the network. A valid value is 4 or 6.

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

mtu

body

integer

The MTU value of a share network.

New in version 2.20

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
    }
}
POST
/v2/{project_id}/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.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

neutron_net_id (Optional)

body

string

The UUID of a neutron network when setting up or updating a share network 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 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.

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

Response parameters

Name

In

Type

Description

id

body

string

The share network ID.

project_id

body

string

The ID of the project that owns the resource.

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.

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

mtu

body

integer

The MTU value of a share network.

New in version 2.20

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
    }
}
POST
/v2/{project_id}/share-networks/{share_network_id}/action

Add security service to share network

Adds a security service to a share network.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

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

Request

Name

In

Type

Description

project_id

body

string

The ID of the project that owns the resource.

share_network_id

path

string

The UUID of the share network.

security_service_id

body

string

The security service ID.

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The share network ID.

project_id

body

string

The ID of the project that owns the resource.

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.

segmentation_id

body

integer

The segmentation ID.

cidr

body

string

The CIDR.

ip_version

body

integer

The IP version of the network. A valid value is 4 or 6.

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

mtu

body

integer

The MTU value of a share network.

New in version 2.20

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
    }
}
POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 share network ID.

project_id

body

string

The ID of the project that owns the resource.

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.

segmentation_id

body

integer

The segmentation ID.

cidr

body

string

The CIDR.

ip_version

body

integer

The IP version of the network. A valid value is 4 or 6.

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

mtu

body

integer

The MTU value of a share network.

New in version 2.20

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
    }
}
PUT
/v2/{project_id}/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.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making 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

path

string

The project ID of the user or service making the API request.

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 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 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 share network ID.

project_id

body

string

The ID of the project that owns the resource.

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.

segmentation_id

body

integer

The segmentation ID.

cidr

body

string

The CIDR.

ip_version

body

integer

The IP version of the network. A valid value is 4 or 6.

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

mtu

body

integer

The MTU value of a share network.

New in version 2.20

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
    }
}
DELETE
/v2/{project_id}/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.

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

path

string

The project ID of the user or service making the API request.

share_network_id

path

string

The UUID of the share network.

Security services

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

The Shared File Systems service supports three security service types:

  • ldap. LDAP.

  • kerberos. Kerberos.

  • active_directory. Microsoft Active Directory.

You can configure a security service with these options:

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

  • An IP address or host name.

  • A domain.

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

  • A user or group name.

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

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

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

all_tenants (Optional)

query

boolean

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

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

id

body

string

The security service ID.

project_id

body

string

The ID of the project that owns the resource.

type

body

string

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

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

dns_ip

body

string

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

user

body

string

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

password

body

string

The user password, if you specify a user.

domain

body

string

The security service domain.

ou

body

string

The security service ou.

New in version 2.44

server

body

string

The security service host name or IP address.

updated_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

created_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

Response example

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

path

string

The project ID of the user or service making the API request.

security_service_id

path

string

The UUID of the security service.

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

id

body

string

The security service ID.

project_id

body

string

The ID of the project that owns the resource.

type

body

string

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

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

dns_ip

body

string

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

user

body

string

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

password

body

string

The user password, if you specify a user.

domain

body

string

The security service domain.

ou

body

string

The security service ou.

New in version 2.44

server

body

string

The security service host name or IP address.

updated_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

created_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

Response example

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

path

string

The project ID of the user or service making the API request.

type

body

string

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

name (Optional)

body

string

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

description (Optional)

body

string

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

dns_ip (Optional)

body

string

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

user (Optional)

body

string

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

password (Optional)

body

string

The user password, if you specify a user.

domain (Optional)

body

string

The security service domain.

ou (Optional)

body

string

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

New in version 2.44

server (Optional)

body

string

The security service host name or IP address.

Request example

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

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

id

body

string

The security service ID.

project_id

body

string

The ID of the project that owns the resource.

type

body

string

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

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

dns_ip

body

string

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

user

body

string

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

password

body

string

The user password, if you specify a user.

domain

body

string

The security service domain.

ou

body

string

The security service ou.

New in version 2.44

server

body

string

The security service host name or IP address.

updated_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

created_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

Response example

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

path

string

The project ID of the user or service making the API request.

security_service_id

path

string

The UUID of the security service.

type

body

string

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

name (Optional)

body

string

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

description (Optional)

body

string

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

dns_ip (Optional)

body

string

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

user (Optional)

body

string

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

password (Optional)

body

string

The user password, if you specify a user.

domain (Optional)

body

string

The security service domain.

ou (Optional)

body

string

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

New in version 2.44

server (Optional)

body

string

The security service host name or IP address.

Request example

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

Response parameters

Name

In

Type

Description

status

body

string

The security service status.

id

body

string

The security service ID.

project_id

body

string

The ID of the project that owns the resource.

type

body

string

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

name

body

string

The user defined name of the resource.

description

body

string

The user defined description of the resource.

dns_ip

body

string

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

user

body

string

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

password

body

string

The user password, if you specify a user.

domain

body

string

The security service domain.

ou

body

string

The security service ou.

New in version 2.44

server

body

string

The security service host name or IP address.

updated_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

created_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

Response example

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

path

string

The project ID of the user or service making the API request.

security_service_id

path

string

The UUID of the security service.

Share servers

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

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

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

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

The possible share servers statuses are:

Share server statuses

Status

Description

active

Share server was successfully set up.

error

The set up or deletion of the share server failed.

deleting

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

creating

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

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 share network ID.

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.

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",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73"
        }
    ]
}
GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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

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",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73"
    }
}
GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_server_id

body

string

The UUID of the share server.

POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 share network ID.

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

{
    "share_server": {
        "host": "myhost@mybackend",
        "share_network_id": "78cef6eb-648a-4bbd-9ae1-d2eaaf594cc0",
        "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 share network 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.

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.

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",
        "created_at": "2019-03-06T11:59:41.000000",
        "backend_details": {},
        "is_auto_deletable": false,
        "identifier": "4ef3507e-0513-4140-beda-f619ab30d424"
    }
}
POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/share-servers/{share_server_id}/action

Reset status (since API v2.49)

New in version 2.49.

Resets a share server status

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

404 - Not Found

The requested resource could not be found.

Request parameters

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

share_server_id

body

string

The UUID of the share server.

status

body

string

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

Request example

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

Response parameters

There is no body content for the response.

Share instances (since API v2.3)

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

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 instance status. A valid value is available, error, creating, deleting, and error_deleting.

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 from which the share instance was created.

availability_zone

body

string

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.

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 (Optional)

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 (Optional)

body

array

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

Available until version 2.8

cast_rules_to_readonly

body

string

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

New in version 2.30

share_network_id

body

string

The share network ID.

share_server_id

body

string

The UUID of the share server.

host

body

string

The share instance host name.

id

body

string

The share instance ID.

Response example

{
    "share_instances": [
        {
            "status": "error",
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T08:41:20.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "id": "081f7030-c54f-42f5-98ee-93a37393e0f2"
        },
        {
            "status": "available",
            "share_id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T08:51:34.000000",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
        }
    ]
}
GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_instance_id

path

string

The UUID of the share instance.

Response parameters

Name

In

Type

Description

status

body

string

The share instance status. A valid value is available, error, creating, deleting, and error_deleting.

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 from which the share instance was created.

availability_zone

body

string

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.

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 (Optional)

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 (Optional)

body

array

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

Available until version 2.8

cast_rules_to_readonly

body

string

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

New in version 2.30

share_network_id

body

string

The share network ID.

share_server_id

body

string

The UUID of the share server.

host

body

string

The share instance host name.

id

body

string

The share instance ID.

Response example

{
    "share_instance": {
        "status": "available",
        "share_id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
        "availability_zone": "nova",
        "replica_state": null,
        "created_at": "2015-09-07T08:51:34.000000",
        "cast_rules_to_readonly": false,
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
        "host": "manila2@generic1#GENERIC1",
        "access_rules_status": "active",
        "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
    }
}
POST
/v2/{project_id}/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.json file to grant permissions for this action to other roles.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

share_instance_id

path

string

The UUID of the share instance.

status

body

string

The share instance status. A valid value is available, error, creating, deleting, and error_deleting.

Request example

{
    "reset_status": {
        "status": "available"
    }
}
POST
/v2/{project_id}/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.json file to grant permissions for this action to other roles.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

share_instance_id

path

string

The UUID of the share instance.

force_delete

body

string

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

Request example

{
    "force_delete": null
}

Share instance export locations (since API v2.9)

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

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

Lists all export locations for a share instance.

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

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_instance_id

path

string

The UUID of the share instance.

Response parameters

Name

In

Type

Description

id

body

string

The share export location UUID.

share_instance_id

body

string

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

path

body

string

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

is_admin_only

body

boolean

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

preferred

body

boolean

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

New in version 2.14

Response example

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

path

string

The project ID of the user or service making the API request.

share_instance_id

path

string

The UUID of the share instance.

export_location_id

path

string

The UUID of the export location.

Response parameters

Name

In

Type

Description

id

body

string

The share export location UUID.

share_instance_id

body

string

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

path

body

string

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

is_admin_only

body

boolean

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

preferred

body

boolean

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

New in version 2.14

created_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

updated_at

body

string

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

The date and time stamp format is ISO 8601:

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

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

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

Response example

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

Share types

A share type enables you to filter or choose back ends before you create a share. A share type behaves in the same way as a Block Storage volume type behaves.

You set a share type to private or public and manage the access to the private share types.

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

Important

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

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

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

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

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

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

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

    Set to False when an administrator rather than a share driver manages the share server life cycle.

  • snapshot_support. Filters back ends by whether they do or do not support share snapshots.

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

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

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

  • Filter back ends. Specify these unqualified extra specifications in this format: extra_spec=value. For example, netapp_raid_type=raid4.

  • Set data for the driver. Except for the special capabilities prefix, you specify these qualified extra specifications with its prefix followed by a colon: vendor:extra_spec=value. For example, netapp:thin_provisioned=true.

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

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

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

GET
/v2/{project_id}/types

List share types

Lists all share types.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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.

New in version 2.43

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share type.

name

body

string

Name of the share type.

required_extra_specs

body

object

The required extra specifications for the share type.

extra_specs

body

object

The extra specifications for the share type.

driver_handles_share_servers

body

boolean

An extra specification that defines the driver mode for share server, or storage, life cycle management. The Shared File Systems service creates a share server for the export of shares. This value is true when the share driver manages, or handles, the share server life cycle. This value is false when an administrator rather than a share driver manages the storage life cycle.

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

snapshot_support (Optional)

body

boolean

An extra specification that filters back ends by whether they do or do not support share snapshots.

mount_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to mount share snapshots.

New in version 2.32

revert_to_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots.

New in version 2.27

share_type_access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

New in version 2.7

create_share_from_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots.

New in version 2.24

description

body

string

The description of the share type.

New in version 2.41

is_default

body

boolean

Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

New in version 2.46

Response example

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

path

string

The project ID of the user or service making the API request.

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share type.

required_extra_specs

body

object

The required extra specifications for the share type.

extra_specs

body

object

The extra specifications for the share type.

driver_handles_share_servers

body

boolean

An extra specification that defines the driver mode for share server, or storage, life cycle management. The Shared File Systems service creates a share server for the export of shares. This value is true when the share driver manages, or handles, the share server life cycle. This value is false when an administrator rather than a share driver manages the storage life cycle.

snapshot_support (Optional)

body

boolean

An extra specification that filters back ends by whether they do or do not support share snapshots.

share_type_access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

New in version 2.7

name

body

string

Name of the share type.

description

body

string

The description of the share type.

New in version 2.41

is_default

body

boolean

Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

New in version 2.46

Response example

{
    "share_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "id": "420e6a31-3f3d-4ed7-9d11-59450372182a",
        "name": "default",
        "is_default": true,
        "description": "share type description"
    },
    "volume_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "id": "420e6a31-3f3d-4ed7-9d11-59450372182a",
        "name": "default",
        "is_default": true,
        "description": "share type description"
    }
}
GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_type_id

path

string

The UUID of the share type.

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the share type.

required_extra_specs

body

object

The required extra specifications for the share type.

extra_specs

body

object

The extra specifications for the share type.

driver_handles_share_servers

body

boolean

An extra specification that defines the driver mode for share server, or storage, life cycle management. The Shared File Systems service creates a share server for the export of shares. This value is true when the share driver manages, or handles, the share server life cycle. This value is false when an administrator rather than a share driver manages the storage life cycle.

snapshot_support (Optional)

body

boolean

An extra specification that filters back ends by whether they do or do not support share snapshots.

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

mount_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to mount share snapshots.

New in version 2.32

revert_to_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots.

New in version 2.27

create_share_from_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots.

New in version 2.24

share_type_access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

New in version 2.7

name

body

string

Name of the share type.

description

body

string

The description of the share type.

New in version 2.41

is_default

body

boolean

Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

New in version 2.46

Response Example

{
    "share_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "id": "2780fc88-526b-464a-a72c-ecb83f0e3929",
        "name": "default-share-type",
        "is_default": true,
        "description": "manila share type"
    },
    "volume_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": "True"
        },
        "id": "2780fc88-526b-464a-a72c-ecb83f0e3929",
        "name": "default-share-type",
        "is_default": true,
        "description": "manila share type"
    }
}
GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_type_id

path

string

The UUID of the share type.

Response parameters

Name

In

Type

Description

extra_specs

body

object

The extra specifications for the share type.

driver_handles_share_servers

body

boolean

An extra specification that defines the driver mode for share server, or storage, life cycle management. The Shared File Systems service creates a share server for the export of shares. This value is true when the share driver manages, or handles, the share server life cycle. This value is false when an administrator rather than a share driver manages the storage life cycle.

snapshot_support (Optional)

body

boolean

An extra specification that filters back ends by whether they do or do not support share snapshots.

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

mount_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to mount share snapshots.

New in version 2.32

revert_to_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots.

New in version 2.27

create_share_from_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots.

New in version 2.24

Response example

{
    "extra_specs": {
        "replication_type": "readable",
        "driver_handles_share_servers": "True",
        "create_share_from_snapshot_support": "True",
        "revert_to_snapshot_support": "False",
        "mount_snapshot_support": "False",
        "snapshot_support": "True"
    }
}
POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

extra_specs

body

object

The extra specifications for the share type.

driver_handles_share_servers

body

boolean

An extra specification that defines the driver mode for share server, or storage, life cycle management. The Shared File Systems service creates a share server for the export of shares. This value is true when the share driver manages, or handles, the share server life cycle. This value is false when an administrator rather than a share driver manages the storage life cycle.

snapshot_support (Optional)

body

boolean

An extra specification that filters back ends by whether they do or do not support share snapshots.

os-share-type-access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

Available until version 2.6

name (Optional)

body

string

Name of the share type. The value of this field is limited to 255 characters.

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

mount_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to mount share snapshots.

New in version 2.32

revert_to_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots.

New in version 2.27

create_share_from_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots.

New in version 2.24

description (Optional)

body

string

The description of the share type. The value of this field is limited to 255 characters.

New in version 2.41

Request example

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

Response parameters

Name

In

Type

Description

id

body

string

The UUID of the share type.

required_extra_specs

body

object

The required extra specifications for the share type.

extra_specs

body

object

The extra specifications for the share type.

driver_handles_share_servers

body

boolean

An extra specification that defines the driver mode for share server, or storage, life cycle management. The Shared File Systems service creates a share server for the export of shares. This value is true when the share driver manages, or handles, the share server life cycle. This value is false when an administrator rather than a share driver manages the storage life cycle.

snapshot_support (Optional)

body

boolean

An extra specification that filters back ends by whether they do or do not support share snapshots.

os-share-type-access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

Available until version 2.6

share_type_access:is_public (Optional)

body

boolean

Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.

New in version 2.7

name

body

string

Name of the share type.

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

mount_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to mount share snapshots.

New in version 2.32

revert_to_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots.

New in version 2.27

create_share_from_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots.

New in version 2.24

description

body

string

The description of the share type.

New in version 2.41

is_default

body

boolean

Defines the share type created is default or not. If the returning value is true, then it is the default share type, otherwise, it is not default.

New in version 2.46

Response example

{
    "share_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": true
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "replication_type": "readable",
            "driver_handles_share_servers": "True",
            "mount_snapshot_support": "False",
            "revert_to_snapshot_support": "False",
            "create_share_from_snapshot_support": "True",
            "snapshot_support": "True"
        },
        "id": "7fa1342b-de9d-4d89-bdc8-af67795c0e52",
        "name": "testing",
        "is_default": false,
        "description": "share type description"
    },
    "volume_type": {
        "required_extra_specs": {
            "driver_handles_share_servers": true
        },
        "share_type_access:is_public": true,
        "extra_specs": {
            "replication_type": "readable",
            "driver_handles_share_servers": "True",
            "mount_snapshot_support": "False",
            "revert_to_snapshot_support": "False",
            "create_share_from_snapshot_support": "True",
            "snapshot_support": "True"
        },
        "id": "7fa1342b-de9d-4d89-bdc8-af67795c0e52",
        "name": "testing",
        "is_default": false,
        "description": "share type description"
    }
}
GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_type_id

path

string

The UUID of the share type.

extra_specs

body

object

The extra specifications for the share type.

Request example

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

Response parameters

Name

In

Type

Description

extra_specs

body

object

The extra specifications for the share type.

Response example

{
    "extra_specs": {
        "my_key": "my_value"
    }
}
DELETE
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_type_id

path

string

The UUID of the share type.

extra-spec-key

path

string

The extra specification key

POST
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

share_type_id

path

string

The UUID of the share type.

PUT
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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.

extra_specs

body

object

The extra specifications for the share type.

driver_handles_share_servers

body

boolean

An extra specification that defines the driver mode for share server, or storage, life cycle management. The Shared File Systems service creates a share server for the export of shares. This value is true when the share driver manages, or handles, the share server life cycle. This value is false when an administrator rather than a share driver manages the storage life cycle.

snapshot_support (Optional)

body

boolean

An extra specification that filters back ends by whether they do or do not support share snapshots.

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.

replication_type (Optional)

body

string

The share replication type.

mount_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to mount share snapshots.

revert_to_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to revert shares to snapshots.

create_share_from_snapshot_support (Optional)

body

boolean

Boolean extra spec used for filtering of back ends by their capability to create shares from snapshots.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

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.

Response example

{
    "disabled": false,
    "binary": "manila-share",
    "host": "openstackhost@generic#pool_0"
}
PUT
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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.

Request example

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

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.

Response example

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

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

Response parameters

Name

In

Type

Description

availability_zones

body

string

Top level response body element.

id

body

string

The availability zone ID.

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/{project_id}/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.json file to grant permissions for this action to other roles.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

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

Request

Name

In

Type

Description

project_id

path

string

The project ID of the user or service making the API request.

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 share type name.

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

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share public. Set to false to make it private. 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.

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

The share links

availability_zone

body

string

The availability zone.

share_network_id

body

string

The share network ID.

export_locations (Optional)

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

share_type

body

string

The UUID of the share type. In minor versions, this parameter is a share type name, as a string.

New in version 2.6

share_type_name

body

string

Name of the share type.

has_replicas

body

boolean

Indicates whether a share has replicas or not.

New in version 2.11

replication_type (Optional)

body

string

The share replication type.

New in version 2.11

export_location (Optional)

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 (Optional)

body

object

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

status

body

string

The share status, which is available, manage_starting, or manage_error.

description

body

string

The user defined description of the resource.

host

body

string

The share host name.

is_public (Optional)

body

boolean

The level of visibility for the share. Set to true to make share public. Set to false to make it private. Default value is false.

New in version 2.8

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.

volume_type (Optional)

body

string

The volume type. 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. When you issue a create a share type request, you can submit a request body with either a share_type or volume_type object. 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_types and volume_types objects.

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.",
        "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/{project_id}/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.json 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

path

string

The project ID of the user or service making the API request.

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 and share group snapshots were added to quota management APIs in API version 2.40.

GET
/v2/{project_id}/quota-sets/{project_id}/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

path

string

The project ID of the user or service making the API request.

project_id

path

string

The ID of the project whose quotas must be acted upon by the API. This ID can be different from the first project ID in the URI. For example, in a multi-tenant cloud, the first ID in the URI 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.

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.

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
    }
}
GET
/v2/{project_id}/quota-sets/{project_id}?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

path

string

The project ID of the user or service making the API request.

project_id

path

string

The ID of the project whose quotas must be acted upon by the API. This ID can be different from the first project ID in the URI. For example, in a multi-tenant cloud, the first ID in the URI 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.

user_id (Optional)

query

string

The ID of the user. If you specify this query parameter, you update the quotas for this user in the project. If you omit this parameter, you update the quotas for the whole project.

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.

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

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
    }
}
GET
/v2/{project_id}/quota-sets/{project_id}/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

path

string

The project ID of the user or service making the API request.

project_id

path

string

The ID of the project whose quotas must be acted upon by the API. This ID can be different from the first project ID in the URI. For example, in a multi-tenant cloud, the first ID in the URI 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.

user_id (Optional)

query

string

The ID of the user. If you specify this query parameter, you update the quotas for this user in the project. If you omit this parameter, you update the quotas for the whole project.

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.

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

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}
    }
}
PUT
/v2/{project_id}/quota-sets/{project_id}?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

path

string

The project ID of the user or service making the API request.

project_id

path

string

The ID of the project whose quotas must be acted upon by the API. This ID can be different from the first project ID in the URI. For example, in a multi-tenant cloud, the first ID in the URI 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.

user_id (Optional)

query

string

The ID of the user. If you specify this query parameter, you update the quotas for this user in the project. If you omit this parameter, you update the quotas for the whole project.

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.

New in version 2.39

Request example

{
    "quota_set": {
        "snapshot_gigabytes": 999,
        "snapshots": 49,
        "share_networks": 9
    }
}

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

Response example

{
    "quota_set": {
        "gigabytes": 1000,
        "snapshot_gigabytes": 999,
        "shares": 50,
        "snapshots": 49,
        "share_networks": 9,
        "share_groups": 12,
        "share_group_snapshots": 12
    }
}
DELETE
/v2/{project_id}/quota-sets/{project_id}?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

path

string

The project ID of the user or service making the API request.

project_id

path

string

The ID of the project whose quotas must be acted upon by the API. This ID can be different from the first project ID in the URI. For example, in a multi-tenant cloud, the first ID in the URI 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.

user_id (Optional)

query

string

The ID of the user. If you specify this query parameter, you update the quotas for this user in the project. If you omit this parameter, you update the quotas for the whole project.

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.

New in version 2.39

Quota class set

Quota classes can be shown and updated for a project.

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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.

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
    }
}
PUT
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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.

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.

Response Example

{
    "quota_class_set": {
        "share_groups": 50,
        "gigabytes": 20,
        "share_group_snapshots": 50,
        "snapshots": 50,
        "snapshot_gigabytes": 1000,
        "shares": 50,
        "share_networks": 10
    }
}

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

limit (Optional)

query

integer

The maximum number of shares to return.

offset (Optional)

query

integer

The offset to define start point of share or share group listing.

sort_key (Optional)

query

string

The key to sort a list of 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 shares. 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.

Response parameters

Name

In

Type

Description

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.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

message_id (Optional)

path

string

The UUID of the message.

Response parameters

Name

In

Type

Description

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.

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/{project_id}/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

path

string

The project ID of the user or service making the API request.

message_id (Optional)

path

string

The UUID of the message.

Share access rules (since API v2.45)

Retrieve details about access rules

GET
/v2/{project_id}/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

path

string

The project ID of the user or service making the API request.

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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - 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_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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - 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

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.

access_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/{project_id}/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.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making 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

path

string

The project ID of the user or service making the API request.

share_id

query

string

The share ID to filter share access rules with.

metadata (Optional)

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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - 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_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 an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. - 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/{project_id}/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