Shared File Systems API

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

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.

Normal Response Codes: 300

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

Normal Response Codes: 200

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.
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 (Optional) query 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/{tenant_id}/extensions

List extensions

Lists all extensions.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

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 extension description.
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 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/{tenant_id}/limits

List share limits

Lists share limits.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

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. You can mount a share to and access a share from several hosts by several users at a time.

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

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/{tenant_id}/shares

List shares

Lists all shares.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
all_tenants (Optional) query boolean (Admin only). Defines whether to list shares for all tenants. Set to 1 to list shares for all tenants. Set to 0 to list shares only for the current tenant.
name (Optional) body string The share name.
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, unmanaged, extending, extending_error, shrinking, shrinking_error, or shrinking_possible_data_loss_error.
share_server_id body string The UUID of the share server.
metadata (Optional) body object One or more metadata key and value pairs as a dictionary of strings.
extra_specs body object The extra specifications for the share type.
share_type_id path string The UUID of the share type.
limit (Optional) query integer The maximum number of shares to return.
offset (Optional) query integer The offset to define start point of share 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.
snapshot_id (Optional) body string The UUID of the share’s base snapshot to filter the request based on.
host body string The share host name.
share_network_id body string The share network ID.
project_id (Optional) query string The UUID of the project in which the share was created. Useful with all_tenants parameter.
is_public (Optional) body boolean (Since API v2.8) 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.
consistency_group_id body string (Since API v2.4) The UUID of the consistency group where the share was created.

Response parameters

Name In Type Description
id body string The UUID of the share.
links body array The share links
name body string The share network name.

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"
        }
    ]
}
GET
/v2/{tenant_id}/shares/detail

List shares with details

Lists all shares, with details.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
all_tenants (Optional) query boolean (Admin only). Defines whether to list shares for all tenants. Set to 1 to list shares for all tenants. Set to 0 to list shares only for the current tenant.
name (Optional) body string The share name.
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, unmanaged, extending, extending_error, shrinking, shrinking_error, or shrinking_possible_data_loss_error.
share_server_id body string The UUID of the share server.
metadata (Optional) body object One or more metadata key and value pairs as a dictionary of strings.
extra_specs body object The extra specifications for the share type.
share_type_id path string The UUID of the share type.
limit (Optional) query integer The maximum number of shares to return.
offset (Optional) query integer The offset to define start point of share 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.
snapshot_id (Optional) body string The UUID of the share’s base snapshot to filter the request based on.
host body string The share host name.
share_network_id body string The share network ID.
project_id (Optional) query string The UUID of the project in which the share was created. Useful with all_tenants parameter.
is_public (Optional) body boolean (Since API v2.8) 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.
consistency_group_id body string (Since API v2.4) The UUID of the consistency group where the share was created.

Response parameters

Name In Type Description
share_type_name body string (Since API v2.6) The share type name. Minor versions support only the share_type parameter where the share type name is expected.
links body array The share links
availability_zone (Optional) body string (Since API v2.1) 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.

Deprecated in version 2.8

share_server_id body string The UUID of the share server.
snapshot_id (Optional) query 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 (Since API v2.6) The UUID of the share type. In minor versions, this parameter is a share type name, as a string.
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.

Deprecated in version 2.8

consistency_group_id (Optional) query string (Since API v2.4) The UUID of the consistency group where the share was created. You can omit this parameter if the share was created without a consistency group.
project_id body string The UUID of the project in which the share was created.
metadata (Optional) body object One or more metadata key and value pairs as a dictionary of strings.
status body string The consistency group snapshot status, which is available, creating, error, deleting, or error_deleting.
description (Optional) body string The share description.
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 (Since API v2.8) 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.
task_state body string (Since API v2.5) 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.
snapshot_support body boolean (Since API v2.2) An extra specification that filters back ends by whether they do or do not support share snapshots.
name (Optional) body string The share name.
has_replicas body boolean (Since API v2.11) Indicates whether a share has replicas or not.
replication_type (Optional) body string (Since API v2.11) The share replication type.
created_at body string

The date and time stamp when the share was created.

The date and time stamp format is ISO 8601:

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_proto body string The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.
source_cgsnapshot_member_id body string (Since API v2.4) If the share was created with consistency_group_id attribute, the snapshot member ID. The corresponding consistency group must be created from a snapshot with the current share as a member. Consistency groups and snapshots are the part of the Shared File Systems experimental API. For details, see Consistency groups and Consistency group snapshots.

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",
            "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,
            "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
            "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",
            "source_cgsnapshot_member_id": null
        },
        {
            "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",
            "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
            "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",
            "source_cgsnapshot_member_id": null
        }
    ]
}
GET
/v2/{tenant_id}/shares/{share_id}

Show share details

Shows details for a share.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
share_id body string The UUID of the share from which to create a snapshot.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Response parameters

Name In Type Description
share_type_name body string (Since API v2.6) The share type name. Minor versions support only the share_type parameter where the share type name is expected.
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.

Deprecated in version 2.8

share_server_id body string The UUID of the share server.
snapshot_id (Optional) query 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 (Since API v2.6) The UUID of the share type. In minor versions, this parameter is a share type name, as a string.
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.

Deprecated in version 2.8

consistency_group_id body string (Since API v2.4) The UUID of the consistency group where the share was created.
project_id body string The UUID of the project in which the share was created.
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 (Optional) body string The share description.
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 (Since API v2.8) 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.
task_state body string (Since API v2.5) 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.
snapshot_support body boolean (Since API v2.2) An extra specification that filters back ends by whether they do or do not support share snapshots.
name (Optional) body string The share name.
has_replicas body boolean (Since API v2.11) Indicates whether a share has replicas or not.
replication_type (Optional) body string (Since API v2.11) The share replication type.
created_at body string

The date and time stamp when the share was created.

The date and time stamp format is ISO 8601:

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_proto body string The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.
source_cgsnapshot_member_id body string (Since API v2.4) If the share was created with consistency_group_id attribute, the snapshot member ID. The corresponding consistency group must be created from a snapshot with the current share as a member. Consistency groups and snapshots are the part of the Shared File Systems experimental API. For details, see Consistency groups and Consistency group snapshots.

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",
        "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,
        "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
        "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",
        "source_cgsnapshot_member_id": null
    }
}
POST
/v2/{tenant_id}/shares

Create share

Creates a share.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409), unprocessableEntity(422)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_proto body string The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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 share name.
description (Optional) body string The share description.
display_name (Optional) body string The share name. The Shared File Systems API supports the use of both name and display_name attributes, which are inherited attributes from the Block Storage API.
display_description (Optional) body string The share description. The Shared File Systems API supports the use of both description and display_description parameters, which are inherited attributes from the Block Storage API.
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 (Since API v2.8) 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.
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.
consistency_group_id (Optional) body string (Since API v2.4) The UUID of the available consistency group in which the share will be created. The consistency group must support the share_type and share_network_id. For details, see Consistency groups.
availability_zone (Optional) body string (Since API v2.1) The availability zone.

Request example

{
    "share": {
        "description": "My custom share London",
        "share_type": null,
        "share_proto": "nfs",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "name": "share_London",
        "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
        "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 (Optional) query string The UUID of the project in which the share was created. Useful with all_tenants parameter.
share_proto body string The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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 share name.
description (Optional) body string The share description.
display_name (Optional) body string The share name. The Shared File Systems API supports the use of both name and display_name attributes, which are inherited attributes from the Block Storage API.
display_description (Optional) body string The share description. The Shared File Systems API supports the use of both description and display_description parameters, which are inherited attributes from the Block Storage API.
share_type body string (Since API v2.6) The UUID of the share type. In minor versions, this parameter is a share type name, as a string.
share_type_name body string (Since API v2.6) The share type name. Minor versions support only the share_type parameter where the share type name is expected.
has_replicas body boolean (Since API v2.11) Indicates whether a share has replicas or not.
replication_type (Optional) body string (Since API v2.11) The share replication type.
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) query string The UUID of the snapshot that was used to create the share.
is_public (Optional) body boolean (Since API v2.8) 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.
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.

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

Deprecated in version 2.8

host body string The share host name.
task_state body string (Since API v2.5) 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.
share_server_id body string The UUID of the share server.
consistency_group_id body string (Since API v2.4) The UUID of the consistency group where the share was created.
snapshot_support body boolean (Since API v2.2) An extra specification that filters back ends by whether they do or do not support share snapshots.
source_cgsnapshot_member_id body string (Since API v2.4) If the share was created with consistency_group_id attribute, the snapshot member ID. The corresponding consistency group must be created from a snapshot with the current share as a member. Consistency groups and snapshots are the part of the Shared File Systems experimental API. For details, see Consistency groups and Consistency group snapshots.
created_at body string

The date and time stamp when the share was created.

The date and time stamp format is ISO 8601:

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

{
    "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,
        "export_locations": [],
        "share_proto": "NFS",
        "host": null,
        "access_rules_status": "active",
        "has_replicas": false,
        "replication_type": null,
        "task_state": null,
        "snapshot_support": true,
        "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
        "source_cgsnapshot_member_id": null,
        "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/{tenant_id}/shares/manage

Manage share

Configures Shared File Systems to manage a share. This API is available for API versions later than or equal to 2.7

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409), unprocessableEntity(422)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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, or HDFS.
name (Optional) body string The share name.
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.
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 (Since API v2.8) 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.
description (Optional) body string The share description.

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

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.

Deprecated in version 2.8

share_server_id body string The UUID of the share server.
snapshot_id (Optional) query 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 (Since API v2.6) The UUID of the share type. In minor versions, this parameter is a share type name, as a string.
share_type_name body string (Since API v2.6) The share type name. Minor versions support only the share_type parameter where the share type name is expected.
has_replicas body boolean (Since API v2.11) Indicates whether a share has replicas or not.
replication_type (Optional) body string (Since API v2.11) The share replication type.
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.

Deprecated in version 2.8

consistency_group_id body string (Since API v2.4) The UUID of the consistency group where the share was created.
project_id body string The UUID of the project in which the share was created.
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 (Optional) body string The share description.
host (Optional) body string The share host name.
is_public (Optional) body boolean (Since API v2.8) 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.
snapshot_support body boolean (Since API v2.2) An extra specification that filters back ends by whether they do or do not support share snapshots.
name (Optional) body string The share name.
created_at body string

The date and time stamp when the share was created.

The date and time stamp format is ISO 8601:

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_proto body string The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.
source_cgsnapshot_member_id body string (Since API v2.4) If the share was created with consistency_group_id attribute, the snapshot member ID. The corresponding consistency group must be created from a snapshot with the current share as a member. Consistency groups and snapshots are the part of the Shared File Systems experimental API. For details, see Consistency groups and Consistency group snapshots.

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": 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",
        "consistency_group_id": null,
        "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": "2015-09-17T16:21:12.000000",
        "share_proto": "NFS",
        "volume_type": "d",
        "source_cgsnapshot_member_id": null
    }
}
PUT
/v2/{tenant_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.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), unprocessableEntity(422)

Request

Name In Type Description
is_public (Optional) body boolean (Since API v2.8) 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.
display_name (Optional) body string The snapshot name. If you specify this attribute, the snapshot name is updated.
display_description (Optional) body string The share description. If you specify this parameter, the share description is updated.
share_id body string The UUID of the share from which to create a snapshot.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

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

Response parameters

Name In Type Description
share_type_name body string (Since API v2.6) The share type name. Minor versions support only the share_type parameter where the share type name is expected.
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.

Deprecated in version 2.8

share_server_id body string The UUID of the share server.
snapshot_id (Optional) query 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 (Since API v2.6) The UUID of the share type. In minor versions, this parameter is a share type name, as a string.
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.

Deprecated in version 2.8

consistency_group_id body string (Since API v2.4) The UUID of the consistency group where the share was created.
project_id body string The UUID of the project in which the share was created.
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 (Optional) body string The share description.
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 (Since API v2.8) 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.
task_state body string (Since API v2.5) 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.
snapshot_support body boolean (Since API v2.2) An extra specification that filters back ends by whether they do or do not support share snapshots.
name (Optional) body string The share name.
has_replicas body boolean (Since API v2.11) Indicates whether a share has replicas or not.
replication_type (Optional) body string (Since API v2.11) The share replication type.
created_at body string

The date and time stamp when the share was created.

The date and time stamp format is ISO 8601:

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_proto body string The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.
source_cgsnapshot_member_id body string (Since API v2.4) If the share was created with consistency_group_id attribute, the snapshot member ID. The corresponding consistency group must be created from a snapshot with the current share as a member. Consistency groups and snapshots are the part of the Shared File Systems experimental API. For details, see Consistency groups and Consistency group snapshots.

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",
        "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,
        "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
        "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",
        "source_cgsnapshot_member_id": null
    }
}
DELETE
/v2/{tenant_id}/shares/{share_id}

Delete share

Deletes a share.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.
consistency_group_id (Optional) query string (Since API v2.4) The UUID of the consistency group where the share was created. You can omit this parameter if the share was created without a consistency group.

Share export locations (since API v2.9)

Set of APIs used for viewing export locations of shares.

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

GET
/v2/{tenant_id}/shares/{share_id}/export_locations

List export locations

Lists all export locations for a share.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

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.
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.
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/{tenant_id}/shares/{share_id}/export_locations/​{export_location_id}

Show single export location

Show details of an export location belonging to a share.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.
export_location_id body string The share export location UUID.

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.
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.
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 share export location was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share export location was 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, 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/{tenant_id}/shares/{share_id}/metadata

Show share metadata

Shows the metadata for a share.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

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

Set share metadata

Sets the metadata on a share.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
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.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

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/{tenant_id}/shares/{share_id}/metadata

Update share metadata

Updates the metadata for a share.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
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.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

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"
    }
}
DELETE
/v2/{tenant_id}/shares/{share_id}/metadata/{key}

Unset share metadata

Un-sets the metadata on a share.

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

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.
key (Optional) body object The key of a metadata item. For example, if share metadata 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/{tenant_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. 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.

Grants access to a share.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
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.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

{
    "allow_access": {
        "access_level": "rw",
        "access_type": "ip",
        "access_to": "0.0.0.0/0"
    }
}

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 access rule was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the access rule was 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.

If the access rule was never updated, this value is null.

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.

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

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
deny_access body object The deny_access object.
access_id body string The UUID of the access rule to which access is granted.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

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

List access rules

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

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
access_list body string The object of the access rule. To list access rules, set this value to null.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

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 access rule was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the access rule was 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.

If the access rule was never updated, this value is null.

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/{tenant_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.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
reset_status body object The reset_status object.
status body string The share access status, which is new, error, active.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

{
    "reset_status": {
        "status": "error"
    }
}
POST
/v2/{tenant_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.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
force_delete body string To force-delete a share, set this value to null. The force-delete action, unlike the delete action, ignores the share status.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

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

Extend share

Increases the size of a share.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
extend body object The extend object.
new_size body integer New size of the share, in GBs.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

{
    "extend": {
        "new_size": 2
    }
}
POST
/v2/{tenant_id}/shares/{share_id}/action

Shrink share

Shrinks the size of a share.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
shrink body object The shrink object.
new_size body integer New size of the share, in GBs.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

{
    "shrink": {
        "new_size": 1
    }
}
POST
/v2/{tenant_id}/shares/{share_id}/action

Unmanage share

This API is available in versions later than or equal to 2.7

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
unmanage body string To unmanage a share, set this value to null.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

{
    "unmanage": null
}
POST
/v2/{tenant_id}/shares/{share_id}/action

Revert share to snapshot

Reverts a share to the specified snapshot, which must be the most recent one known to manila. This API is available in versions later than or equal to 2.27.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
snapshot_id body string The UUID of the snapshot.
share_id path string The UUID of the share.
tenant_id path string The tenant ID in a multi-tenancy cloud.

Request example

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

Share snapshots

Use the shared file 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. 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/{tenant_id}/snapshots

List share snapshots

Lists all share snapshots.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

Response parameters

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

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/{tenant_id}/snapshots/detail

List share snapshots with details

Lists all share snapshots with details.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

Response parameters

Name In Type Description
id body 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.
share_id body string The UUID of the source share that was used to create the snapshot.
name body string The snapshot name.
description body string The snapshot description.
created_at body string

The date and time stamp when the snapshot was created.

The date and time stamp format is ISO 8601:

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_proto body string The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.

Response example

{
    "snapshots": [
        {
            "status": "creating",
            "share_id": "d94a8548-2079-4be0-b21c-0a887acd31ca",
            "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",
            "size": 1
        },
        {
            "status": "available",
            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
            "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",
            "size": 1
        }
    ]
}
GET
/v2/{tenant_id}/snapshots/{snapshot_id}

Show share snapshot details

Shows details for a share snapshot.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.

Response parameters

Name In Type Description
id body 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.
share_id body string The UUID of the source share that was used to create the snapshot.
name body string The snapshot name.
description body string The snapshot description.
created_at body string

The date and time stamp when the snapshot was created.

The date and time stamp format is ISO 8601:

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_proto body string The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.

Response example

{
    "snapshot": {
        "status": "available",
        "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
        "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",
        "size": 1
    }
}
POST
/v2/{tenant_id}/snapshots

Create share snapshot

Creates a snapshot from a share.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), unprocessableEntity(422)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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 snapshot name.
display_name (Optional) body string The snapshot name. The Shared File Systems API supports the use of both name and display_name attributes, which are inherited attributes from the Block Storage API.
description (Optional) body string The snapshot description.
display_description (Optional) body string The snapshot description. The shared file systems API supports the use of both name and display_name attributes, which are inherited attributes from the block storage API.

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 (Optional) 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 snapshot name.
description body string The snapshot description.
created_at body string

The date and time stamp when the snapshot was created.

The date and time stamp format is ISO 8601:

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_proto body string The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.

Response example

{
    "snapshot": {
        "status": "creating",
        "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
        "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",
        "size": 1
    }
}
POST
/v2/{tenant_id}/snapshots/manage

Manage share snapshot

(Since API v2.12) Configures Shared File Systems to manage a share snapshot.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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 snapshot name.
display_name (Optional) body string The snapshot name. The Shared File Systems API supports the use of both name and display_name attributes, which are inherited attributes from the Block Storage API.
description (Optional) body string The snapshot description.
display_description (Optional) body string The snapshot description. The shared file systems API supports the use of both name and display_name attributes, which are inherited attributes from the block storage API.
driver_options (Optional) body object A set of one or more key and value pairs, as a dictionary of strings, that describe driver options.

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 snapshot name.
description body string The snapshot description.
created_at body string

The date and time stamp when the snapshot was created.

The date and time stamp format is ISO 8601:

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_proto body string The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.

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",
        "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/{tenant_id}/snapshots/{snapshot_id}/action

Unmanage share snapshot

(Since API v2.12) Configures Shared File Systems to stop managing a share snapshot.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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/{tenant_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.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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/{tenant_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.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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/{tenant_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.
  • is_public. Changes the level of visibility.

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

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), unprocessableEntity(422)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
display_name (Optional) body string The snapshot name. The Shared File Systems API supports the use of both name and display_name attributes, which are inherited attributes from the Block Storage API.
display_description (Optional) body string The snapshot description. The shared file systems API supports the use of both name and display_name attributes, which are inherited attributes from the block storage API.

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 (Optional) 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 snapshot name.
description body string The snapshot description.
created_at body string

The date and time stamp when the snapshot was created.

The date and time stamp format is ISO 8601:

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_proto body string The file system protocol of a share snapshot. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.

Response example

{
    "snapshot": {
        "status": "available",
        "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
        "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": "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/{tenant_id}/snapshots/{snapshot_id}

Delete share snapshot

Deletes a share snapshot.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.

Share networks

A share network stores network information that share servers can use where shares are hosted. You can associate a share with a single share network. When you create a share, you can optionally specify the ID of a share network through which instances can access the share.

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:

  • Neutron network. Specify a network ID and subnet ID.

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

A share network 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.
GET
/v2/{tenant_id}/share-networks

List share networks

Lists all share networks.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

Response parameters

Name In Type Description
id body string The share network ID.
name body string The name of a share network.

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/{tenant_id}/share-networks/detail

List share networks with details

Lists all share networks with details.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

Response parameters

Name In Type Description
id body string The share network ID.
project_id body string The UUID of the project where the share network was created.
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 name of a share network.
description body string The share network description.
created_at body string

The date and time stamp when the share network was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share network was 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

{
    "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"
        },
        {
            "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"
        },
        {
            "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
        }
    ]
}
GET
/v2/{tenant_id}/share-networks/{share_network_id}

Show share network details

Shows details for a share network.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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 UUID of the project where the share network was created.
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 name of a share network.
description body string The share network description.
created_at body string

The date and time stamp when the share network was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share network was 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

{
    "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"
    }
}
POST
/v2/{tenant_id}/share-networks

Create share network

Creates a share network.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), entityTooLarge(413), unprocessableEntity(422)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
neutron_net_id (Optional) body string The UUID of a neutron network when setting up 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 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 name of a share network.
description body string The share network description.

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 UUID of the project where the share network was created.
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 name of a share network.
description body string The share network description.
created_at body string

The date and time stamp when the share network was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share network was 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

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

Add security service to share network

Adds a security service to a share network.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The UUID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the administrative tenant.
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 UUID of the project where the share network was created.
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 name of a share network.
description body string The share network description.
created_at body string

The date and time stamp when the share network was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share network was 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

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

Remove security service from share network

Removes a security service from a share network.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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 UUID of the project where the share network was created.
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 name of a share network.
description body string The share network description.
created_at body string

The date and time stamp when the share network was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share network was 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

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

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), unprocessableEntity(422)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_network_id path string The UUID of the share network.
name (Optional) body string The name of a share network.
description body string The share network description.

Request example

{
    "share_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 UUID of the project where the share network was created.
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 name of a share network.
description body string The share network description.
created_at body string

The date and time stamp when the share network was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share network was 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

{
    "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"
    }
}
DELETE
/v2/{tenant_id}/share-networks/{share_network_id}

Delete share network

Deletes a share network.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_network_id path string The UUID of the share network.

Security services

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

You can associate a share with from one to 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.
  • An IP address or host name.
  • A domain.
  • A user or group name.
  • The password for the user, if you specify a user name.
GET
/v2/{tenant_id}/security-services

List security services

Lists all security services.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

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 security service name.

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/{tenant_id}/security-services/detail

List security services with details

Lists all security services with details.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

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 UUID of the project where the security service was created.
type body string The security service type. A valid value is ldap, kerberos, or active_directory.
name body string The security service name.
description body string Description of the security service in plain text.
dns_ip body string The DNS IP address that is used inside the tenant network.
user body string The security service user or group name that is used by the tenant.
password body string The user password, if you specify a user.
domain body string The security service domain.
server body string The security service host name or IP address.
updated_at body string

The date and time stamp when the security service was 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.

created_at body string

The date and time stamp when the security service was created.

The date and time stamp format is ISO 8601:

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

{
    "security_services": [
        {
            "status": "new",
            "domain": 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,
            "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/{tenant_id}/security-services/{security_service_id}

Show security service details

Shows details for a security service.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
security_service_id (Optional) 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 UUID of the project where the security service was created.
type body string The security service type. A valid value is ldap, kerberos, or active_directory.
name body string The security service name.
description body string Description of the security service in plain text.
dns_ip body string The DNS IP address that is used inside the tenant network.
user body string The security service user or group name that is used by the tenant.
password body string The user password, if you specify a user.
domain body string The security service domain.
server body string The security service host name or IP address.
updated_at body string

The date and time stamp when the security service was 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.

created_at body string

The date and time stamp when the security service was created.

The date and time stamp format is ISO 8601:

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

{
    "security_service": {
        "status": "new",
        "domain": 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/{tenant_id}/security-services

Create security service

Creates a security service.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), unprocessableEntity(422)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
type body string The security service type. A valid value is ldap, kerberos, or active_directory.
name body string The security service name.
description (Optional) body string The security service description. If you specify this value, the description is updated.
dns_ip (Optional) body string The DNS IP address that is used inside the tenant network.
user (Optional) body string The security service user or group name that is used by the tenant.
password (Optional) body string The user password, if you specify a user.
domain (Optional) body string The security service domain.
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 UUID of the project where the security service was created.
type body string The security service type. A valid value is ldap, kerberos, or active_directory.
name body string The security service name.
description body string Description of the security service in plain text.
dns_ip body string The DNS IP address that is used inside the tenant network.
user body string The security service user or group name that is used by the tenant.
password body string The user password, if you specify a user.
domain body string The security service domain.
server body string The security service host name or IP address.
updated_at body string

The date and time stamp when the security service was 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.

created_at body string

The date and time stamp when the security service was created.

The date and time stamp format is ISO 8601:

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

{
    "security_service": {
        "status": "new",
        "domain": 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/{tenant_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.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), unprocessableEntity(422)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
security_service_id (Optional) 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 body string The security service name.
description (Optional) body string The security service description. If you specify this value, the description is updated.
dns_ip (Optional) body string The DNS IP address that is used inside the tenant network.
user (Optional) body string The security service user or group name that is used by the tenant.
password (Optional) body string The user password, if you specify a user.
domain (Optional) body string The security service domain.
server (Optional) body string The security service host name or IP address.

Request example

{
    "security_service": {
        "domain": "my_domain",
        "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 UUID of the project where the security service was created.
type body string The security service type. A valid value is ldap, kerberos, or active_directory.
name body string The security service name.
description body string Description of the security service in plain text.
dns_ip body string The DNS IP address that is used inside the tenant network.
user body string The security service user or group name that is used by the tenant.
password body string The user password, if you specify a user.
domain body string The security service domain.
server body string The security service host name or IP address.
updated_at body string

The date and time stamp when the security service was 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.

created_at body string

The date and time stamp when the security service was created.

The date and time stamp format is ISO 8601:

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

{
    "security_service": {
        "status": "new",
        "domain": "my_domain",
        "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/{tenant_id}/security-services/{security_service_id}

Delete security service

Deletes a security service.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
security_service_id (Optional) 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/{tenant_id}/share-servers

List share servers

Lists all share servers.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

Response parameters

Name In Type Description
id body string The share server ID.
project_id body string The project ID.
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.
host body string The share server host name or IP address.
updated_at body string

The date and time stamp when the share server was 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

{
    "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/{tenant_id}/share-servers/{share_server_id}/detail

Show share server details

Shows details for a share server.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_server_id body string The UUID of the share server.

Response parameters

Name In Type Description
id body string The share server ID.
project_id body string The project ID.
status body string The share server status, which is active, error, creating, or deleting.
backend_details body string 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.
host body string The share server host name or IP address.
created_at body string

The date and time stamp when the share server was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share server was 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

{
    "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/{tenant_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.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_server_id body string The UUID of the share server.

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/{tenant_id}/share_instances

List share instances

Lists all share instances.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

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 share instance export location was created.

The date and time stamp format is ISO 8601:

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

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

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

replica_state body string (Since API v2.11) The share replica state. Has set value only when replication is used. List of possible values: active, in_sync, out_of_sync, and error.
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.

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

Deprecated in version 2.8

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",
            "export_location": "10.254.0.3:/shares/share-081f7030-c54f-42f5-98ee-93a37393e0f2",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "export_locations": [
                "10.254.0.3:/shares/share-081f7030-c54f-42f5-98ee-93a37393e0f2"
            ],
            "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",
            "export_location": "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
            "export_locations": [
                "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b"
            ],
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
        }
    ]
}
GET
/v2/{tenant_id}/share_instances/{share_instance_id}

Show share instance details

Shows details for a share instance.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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 share instance export location was created.

The date and time stamp format is ISO 8601:

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

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

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

replica_state body string (Since API v2.11) The share replica state. Has set value only when replication is used. List of possible values: active, in_sync, out_of_sync, and error.
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.

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

Deprecated in version 2.8

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",
        "export_location": "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "export_locations": [
            "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b"
        ],
        "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
        "host": "manila2@generic1#GENERIC1",
        "access_rules_status": "active",
        "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
    }
}
POST
/v2/{tenant_id}/share_instances/{share_instance_id}/action

Reset share instance state

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

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

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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/{tenant_id}/share_instances/{share_instance_id}/action

Force-delete share instance

Administrator only. Force-deletes a share instance.

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

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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/{tenant_id}/share_instances/{share_instance_id}/export_locations

List export locations

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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.
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.
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/{tenant_id}/share_instances/{share_instance_id}/export_locations/{export_location_id}

Show single export location

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_instance_id body string The UUID of the share instance that this export location belongs to.
export_location_id body string The share export location UUID.

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.
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.
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 share export location was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the share export location was 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, 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/{tenant_id}/types

List share types

Lists all share types.

Normal response codes: 200

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

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

Response example

{
    "volume_types": [
        {
            "os-share-type-access:is_public": true,
            "required_extra_specs": {
                "driver_handles_share_servers": "True"
            },
            "extra_specs": {
                "snapshot_support": "True",
                "driver_handles_share_servers": "True"
            },
            "name": "default",
            "id": "be27425c-f807-4500-a056-d00721db45cf"
        },
        {
            "os-share-type-access:is_public": true,
            "required_extra_specs": {
                "driver_handles_share_servers": "false"
            },
            "extra_specs": {
                "snapshot_support": "True",
                "driver_handles_share_servers": "false"
            },
            "name": "d",
            "id": "f015bebe-c38b-4c49-8832-00143b10253b"
        }
    ],
    "share_types": [
        {
            "os-share-type-access:is_public": true,
            "required_extra_specs": {
                "driver_handles_share_servers": "True"
            },
            "extra_specs": {
                "snapshot_support": "True",
                "driver_handles_share_servers": "True"
            },
            "name": "default",
            "id": "be27425c-f807-4500-a056-d00721db45cf"
        },
        {
            "os-share-type-access:is_public": true,
            "required_extra_specs": {
                "driver_handles_share_servers": "false"
            },
            "extra_specs": {
                "snapshot_support": "True",
                "driver_handles_share_servers": "false"
            },
            "name": "d",
            "id": "f015bebe-c38b-4c49-8832-00143b10253b"
        }
    ]
}
GET
/v2/{tenant_id}/types/default

List default share types

Lists default share types.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.

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

Response example

{
    "volume_type": {
        "required_extra_specs": null,
        "extra_specs": {
            "snapshot_support": "True",
            "driver_handles_share_servers": "True"
        },
        "name": "default",
        "id": "be27425c-f807-4500-a056-d00721db45cf"
    },
    "share_type": {
        "required_extra_specs": null,
        "extra_specs": {
            "snapshot_support": "True",
            "driver_handles_share_servers": "True"
        },
        "name": "default",
        "id": "be27425c-f807-4500-a056-d00721db45cf"
    }
}
GET
/v2/{tenant_id}/types/{share_type_id}/extra_specs

List extra specs

Lists the extra specifications for a share type.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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.

Response example

{
    "extra_specs": {
        "snapshot_support": "True",
        "driver_handles_share_servers": "True"
    }
}
POST
/v2/{tenant_id}/types

Create share type

Creates a share type.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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.
name body string The share type name.

Request example

{
    "volume_type": {
        "os-share-type-access:is_public": true,
        "extra_specs": {
            "driver_handles_share_servers": true,
            "snapshot_support": true
        },
        "name": "my_new_volume_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.
os-share-type-access:is_public (Optional) body boolean Indicates whether a share type is publicly accessible. Default is true, or publicly accessible.
name body string The share type name.

Response example

{
    "volume_type": {
        "os-share-type-access:is_public": true,
        "required_extra_specs": {
            "driver_handles_share_servers": true
        },
        "extra_specs": {
            "snapshot_support": "True",
            "driver_handles_share_servers": "True"
        },
        "name": "my_new_volume_type",
        "id": "1d600d02-26a7-4b23-af3d-7d51860fe858"
    },
    "share_type": {
        "os-share-type-access:is_public": true,
        "required_extra_specs": {
            "driver_handles_share_servers": true
        },
        "extra_specs": {
            "snapshot_support": "True",
            "driver_handles_share_servers": "True"
        },
        "name": "my_new_volume_type",
        "id": "1d600d02-26a7-4b23-af3d-7d51860fe858"
    }
}
GET
/v2/{tenant_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.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_type_id path string The UUID of the share type.

Response parameters

Name In Type Description
share_type_id body string The share type ID of the member.
project_id body string The UUID of the project for which access to the share type is granted.

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/{tenant_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.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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/{tenant_id}/types/{share_type_id}/extra_specs/{extra-spec-key}

Unset an extra spec

Unsets an extra specification for the share type.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_type_id path string The UUID of the share type.
extra-spec-key body string The extra specification key
POST
/v2/{tenant_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.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_type_id path string The UUID of the share type.
project body string The UUID of the project to which access to the share type is granted.

Request example

{
    "addProjectAccess": {
        "project": "e1284adea3ee4d2482af5ed214f3ad90"
    }
}
POST
/v2/{tenant_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.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_type_id path string The UUID of the share type.
project body string The UUID of the project to which access to the share type is granted.

Request example

{
    "removeProjectAccess": {
        "project": "818a3f48dcd644909b3fa2e45a399a27"
    }
}
DELETE
/v2/{tenant_id}/types/{share_type_id}

Delete share type

Deletes a share type.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_type_id path string The UUID of the share type.

Scheduler Stats - Storage Pools

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

GET
/v2/{tenant_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.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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.

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": [
        {
            "host": "manila2",
            "name": "manila2@generic1#GENERIC1",
            "pool": "GENERIC1",
            "backend": "generic1"
        },
        {
            "host": "manila2",
            "name": "manila2@unmanage1#UNMANAGE1",
            "pool": "UNMANAGE1",
            "backend": "unmanage1"
        },
        {
            "host": "manila2",
            "name": "manila2@ams_backend#AMS_BACKEND",
            "pool": "AMS_BACKEND",
            "backend": "ams_backend"
        }
    ]
}
GET
/v2/{tenant_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.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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.

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.
consistency_group_support body string

Specifies the level of support for scheduling shares within consistency groups if the pool supports this feature. Valid values are host, pool and false. If host, shares within a consistency group can span multiple storage pools belonging to a host#backend combination. If pool, shares created within a given consistency group can only be scheduled within that pool. If false, the pool cannot accept scheduling consistency groups, and hence any shares belonging to consistency groups.

New in version 2.4

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": [
        {
            "host": "LONDON",
            "capabilities": {
                "qos": false,
                "driver_version": "1.0",
                "snapshot_support": true,
                "timestamp": "2016-07-05T22:40:32.632330",
                "share_backend_name": "GENERIC1",
                "total_capacity_gb": "unknown",
                "driver_handles_share_servers": true,
                "consistency_group_support": "pool",
                "server_pools_mapping": {},
                "pools": null,
                "vendor_name": "Open Source",
                "reserved_percentage": 0,
                "free_capacity_gb": "unknown",
                "storage_protocol": "NFS_CIFS",
                "replication_domain": null
            },
            "name": "openstack3@generic1#GENERIC1",
            "pool": "GENERIC1",
            "backend": "generic1"
        }
    ]
}

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/{tenant_id}/services?host={host}&binary={binary}&zone={zone}&state={state}&status={status}

List services

Lists all services optionally filtered with the specified search options.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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 service was 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

{
    "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/{tenant_id}/services/enable

Enable service

Enables a service.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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/{tenant_id}/services/disable

Disable service

Disables a service.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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/{tenant_id}/availability-zones

List availability zones

Lists all availability zones.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The UUID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the administrative tenant.

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 availability zone was created.

The date and time stamp format is ISO 8601:

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.

updated_at body string

The date and time stamp when the availability zone was 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

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

Configures Shared File Systems to manage or unmanage a share.

POST
/v2/{tenant_id}/os-share-manage

Manage share

Minimum Supported API Version: 1.0, 2.0 Last supported API Version: 2.6

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.

This API was removed in API version 2.7; please see share actions for the new version of the API to utilize this feature.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
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, or HDFS.
name (Optional) body string The share name.
display_name (Optional) body string The share name. The Shared File Systems API supports the use of both name and display_name attributes, which are inherited attributes from the Block Storage API.
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.
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 (Since API v2.8) 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.
description (Optional) body string The share description.
display_description (Optional) body string The share description. The Shared File Systems API supports the use of both description and display_description parameters, which are inherited attributes from the Block Storage API.

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

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.

Deprecated in version 2.8

share_server_id body string The UUID of the share server.
snapshot_id (Optional) query 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 (Since API v2.6) The UUID of the share type. In minor versions, this parameter is a share type name, as a string.
share_type_name body string (Since API v2.6) The share type name. Minor versions support only the share_type parameter where the share type name is expected.
has_replicas body boolean (Since API v2.11) Indicates whether a share has replicas or not.
replication_type (Optional) body string (Since API v2.11) The share replication type.
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.

Deprecated in version 2.8

consistency_group_id (Optional) query string (Since API v2.4) The UUID of the consistency group where the share was created.
project_id body string The UUID of the project where the share was created.
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 (Optional) body string The share description.
host (Optional) query string The share host name.
is_public (Optional) body boolean (Since API v2.8) 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.
snapshot_support body boolean (Since API v2.2) An extra specification that filters back ends by whether they do or do not support share snapshots.
name (Optional) body string The share name.
created_at body string

The date and time stamp when the share was created.

The date and time stamp format is ISO 8601:

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_proto body string The Shared File Systems protocol. A valid value is NFS, CIFS, GlusterFS, HDFS, or CephFS. 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.
source_cgsnapshot_member_id body string (Since API v2.4) If the share was created with consistency_group_id attribute, the snapshot member ID. The corresponding consistency group must be created from a snapshot with the current share as a member. Consistency groups and snapshots are the part of the Shared File Systems experimental API. For details, see Consistency groups and Consistency group snapshots.

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": 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",
        "consistency_group_id": null,
        "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": "2015-09-17T16:21:12.000000",
        "share_proto": "NFS",
        "volume_type": "d",
        "source_cgsnapshot_member_id": null
    }
}
POST
/v2/{tenant_id}/os-share-unmanage/{share_id}/unmanage

Unmanage share

Minimum Supported API Version: 1.0, 2.0 Last supported API Version: 2.6

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

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

Share unmanage operation is not supported for shares that are created on top of share servers (created with share networks). You should remove any snapshots and share replicas before attempting to unmanage a share.

This API was removed in API version 2.7; please see share actions for the new version of the API to utilize this feature.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_id path string The UUID of the share.

Quota sets

Provides quotas management support.

Important

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

GET
/v2/{tenant_id}/quota-sets/{tenant_id}/defaults

Show default quota set

Shows default quotas for a tenant.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
tenant_id path string The UUID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the administrative tenant.

Response parameters

Name In Type Description
quota_set body object The quota_set object.
id body string The UUID of the tenant for which you manage quotas.
gigabytes body integer The number of gigabytes allowed for each tenant.
snapshots body integer The number of snapshots allowed for each tenant.
shares body integer The number of shares allowed for each tenant.
snapshot_gigabytes body integer The number of gigabytes for the snapshots allowed for each tenant.
share_networks body integer The number of share networks allowed for each tenant.

Response example

{
    "quota_set": {
        "gigabytes": 1000,
        "shares": 50,
        "snapshot_gigabytes": 1000,
        "snapshots": 50,
        "id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_networks": 10
    }
}
GET
/v2/{tenant_id}/quota-sets/{tenant_id}?user_id={user_id}

Show quota set

Shows quotas for a tenant.

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

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
tenant_id path string The UUID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the administrative tenant.
user_id (Optional) query string The UUID of the user. If you specify this query parameter, you update the quotas for this user in the tenant. If you omit this parameter, you update the quotas for the project.

Response parameters

Name In Type Description
quota_set body object The quota_set object.
id body string The UUID of the tenant for which you manage quotas.
gigabytes body integer The number of gigabytes allowed for each tenant.
snapshots body integer The number of snapshots allowed for each tenant.
shares body integer The number of shares allowed for each tenant.
snapshot_gigabytes body integer The number of gigabytes for the snapshots allowed for each tenant.
share_networks body integer The number of share networks allowed for each tenant.

Response example

{
    "quota_set": {
        "gigabytes": 1000,
        "shares": 50,
        "snapshot_gigabytes": 1000,
        "snapshots": 50,
        "id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_networks": 10
    }
}
GET
/v2/{tenant_id}/quota-sets/{tenant_id}/detail?user_id={user_id}

Show quota set in detail

Shows quotas for a tenant in detail.

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

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
tenant_id path string The UUID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the administrative tenant.
user_id (Optional) query string The UUID of the user. If you specify this query parameter, you update the quotas for this user in the tenant. If you omit this parameter, you update the quotas for the project.

Response parameters

Name In Type Description
quota_set body object The quota_set object.
id body string The UUID of the tenant for which you manage quotas.
gigabytes body object

The limit, in_use, reserved number of gigabytes allowed for each tenant.

New in version 2.25

snapshots body object

The limit, in_use, reserved number of snapshots allowed for each tenant.

New in version 2.25

shares body object

The limit, in_use, reserved number of shares allowed for each tenant.

New in version 2.25

snapshot_gigabytes body object

The limit, in_use, reserved number of gigabytes for the snapshots allowed for each tenant.

New in version 2.25

share_networks body object

The limit, in_use, reserved number of share networks allowed for each tenant.

New in version 2.25

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

Update quota set

Updates quotas for a tenant.

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

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
tenant_id path string The UUID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the administrative tenant.
user_id (Optional) query string The UUID of the user. If you specify this query parameter, you update the quotas for this user in the tenant. If you omit this parameter, you update the quotas for the 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 tenant.
snapshots (Optional) body integer The number of snapshots for the tenant.
snapshot_gigabytes (Optional) body integer The number of gigabytes for the snapshots for the tenant.
shares (Optional) body integer The number of shares for the tenant.
share_networks (Optional) body integer The number of share networks for the tenant.

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 UUID of the tenant for which you manage quotas.
gigabytes body integer The number of gigabytes allowed for each tenant.
snapshots body integer The number of snapshots allowed for each tenant.
shares body integer The number of shares allowed for each tenant.
snapshot_gigabytes body integer The number of gigabytes for the snapshots allowed for each tenant.
share_networks body integer The number of share networks allowed for each tenant.

Response example

{
    "quota_set": {
        "gigabytes": 1000,
        "snapshot_gigabytes": 999,
        "shares": 50,
        "snapshots": 49,
        "share_networks": 9
    }
}
DELETE
/v2/{tenant_id}/quota-sets/{tenant_id}?user_id={user_id}

Delete quota set

Deletes quotas for a tenant. 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 tenant. If you omit this parameter, you delete the quotas for the project.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
tenant_id path string The UUID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the administrative tenant.
user_id (Optional) query string The UUID of the user. If you specify this query parameter, you update the quotas for this user in the tenant. If you omit this parameter, you update the quotas for the project.

Shared File Systems API (EXPERIMENTAL)

Share Migration

As an administrator, you can migrate a share with its data from one location to another in a manner that is transparent to users and workloads.

Possible use cases for data migration include:

  • Bring down a physical storage device for maintenance without disrupting workloads.
  • Modify the properties of a share.
  • Free up space in a thinly-provisioned back end.

Note

Share Migration APIs are part an the experimental feature introduced in version 2.5. The APIs may change or be removed in further versions of the Shared File Systems API. The changes are documented within each API below. All experimental APIs require the X-OpenStack-Manila-API-Experimental: True header to be sent in the requests.

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

Migrate share (versions 2.5 to 2.14)

Migrates a share from one back end to another.

You can migrate a share from one back end to another but both back ends must set the driver_handles_share_servers parameter to False. If a share driver handles one of the back ends, this action is not supported. You can configure a back end in the manila.conf file.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_id path string The UUID of the share.
os-migrate_share body object The migrate_share object.
migrate_share body object The migrate_share object.
host body string The host pool of the destination back end, in this format: host@backend#POOL. - host. The host name for the destination back end. - backend. The name of the destination back end. - POOL. The pool name for the destination back end.
force_host_copy body boolean Enables or disables generic host-based forced migrations, which bypasses driver optimizations. Default value is false.
POST
/v2/{tenant_id}/shares/{share_id}/action

Start Migration (Since version 2.15)

Initiates share migration. This API will initiate the share data copy to the new host. The copy operation is non-disruptive.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_id path string The UUID of the share.
migrate-start body object The migrate-start object.
host body string The host pool of the destination back end, in this format: host@backend#POOL. - host. The host name for the destination back end. - backend. The name of the destination back end. - POOL. The pool name for the destination back end.
notify body string Enables or disables notification of data copying completed
force_host_copy body boolean Enables or disables generic host-based forced migrations, which bypasses driver optimizations. Default value is false.
POST
/v2/{tenant_id}/shares/{share_id}/action

Complete Migration (Since version 2.15)

Completes share migration. This API will initiate the switch-over from the source to destination share. This operation is disruptive.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_id path string The UUID of the share.
migration_complete body object The migration_complate object.
host body string The host pool of the destination back end, in this format: host@backend#POOL. - host. The host name for the destination back end. - backend. The name of the destination back end. - POOL. The pool name for the destination back end.
notify body string Enables or disables notification of data copying completed
force_host_copy body boolean Enables or disables generic host-based forced migrations, which bypasses driver optimizations. Default value is false.

Consistency groups (since API v2.4)

Consistency groups enable you to create snapshots at the exact same point in time from multiple file system shares. For example, a database might place its tables, logs, and configuration on separate shares. To restore this database from a previous point in time, it makes sense to restore the logs, tables, and configuration together from the exact same point in time.

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

Note

Consistency groups APIs are part of an experimental feature introduced in version 2.4. The APIs may change or be removed in further versions of the Shared File Systems API. All experimental APIs require the X-OpenStack-Manila-API-Experimental: True header to be sent in the requests.

GET
/v2/{tenant_id}/consistency-groups

List consistency groups

Lists all consistency groups.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
all_tenants (Optional) query boolean (Admin only). Defines whether to list consistency groups for all tenants. Set to 1 to list consistency groups for all tenants. Set to 0 to list consistency groups only for the current tenant.
limit (Optional) query integer The maximum number of consistency groups to return.
offset (Optional) query integer The offset to define start point of consistency group listing.

Response parameters

Name In Type Description
consistency_groups body array The consistency_groups object.
consistency_group body array The consistency_group object.
id body string The UUID of the consistency group.
name body string The consistency group name.
link body array The consistency group links.

Response example

{
    "consistency_groups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/6f519a48-3183-46cf-a32f-41815f813986",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/6f519a48-3183-46cf-a32f-41815f813986",
                    "rel": "bookmark"
                }
            ],
            "name": "my-cg1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/aed36625-a6d7-4681-ba59-c7ba3d18c148",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/aed36625-a6d7-4681-ba59-c7ba3d18c148",
                    "rel": "bookmark"
                }
            ],
            "name": "my-cg2"
        }
    ]
}
GET
/v2/{tenant_id}/consistency-groups/detail

List consistency groups with details

Lists all consistency groups with details.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
all_tenants (Optional) query boolean (Admin only). Defines whether to list consistency groups for all tenants. Set to 1 to list consistency groups for all tenants. Set to 0 to list consistency groups only for the current tenant.
limit (Optional) query integer The maximum number of consistency groups to return.
offset (Optional) query integer The offset to define start point of consistency group listing.

Response parameters

Name In Type Description
consistency_groups body array The consistency_groups object.
consistency_group body array The consistency_group object.
id body string The UUID of the consistency group.
status body string The consistency group status. A valid value is creating, available, error, deleting, or error_deleting.
links body array The consistency group links.
name body string The consistency group name.
description body string The consistency group description.
source_cgsnapshot_id body string The consistency group snapshot ID. A valid value is null or the ID of the consistency group snapshot, if the consistency group was created from a snapshot.
created_at body string

The date and time stamp when the consistency group was created.

The date and time stamp format is ISO 8601:

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_network_id body string The UUID of the share network.
host body string The consistency group host name.
project_id body string The ID of the project in which the consistency group snapshot was created.
share_server_id body string The UUID of the share server.
share_types body array A list of share type IDs.

Response example

{
    "consistency_groups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/6f519a48-3183-46cf-a32f-41815f813986",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/6f519a48-3183-46cf-a32f-41815f813986",
                    "rel": "bookmark"
                }
            ],
            "name": "my-cg1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/aed36625-a6d7-4681-ba59-c7ba3d18c148",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/aed36625-a6d7-4681-ba59-c7ba3d18c148",
                    "rel": "bookmark"
                }
            ],
            "name": "my-cg2"
        }
    ]
}
GET
/v2/{tenant_id}/consistency-groups/{consistency_group_id}

Show consistency group details

Shows details for a consistency group.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
consistency_group_id path string The UUID of the consistency group.

Response parameters

Name In Type Description
consistency_group body array The consistency_group object.
id body string The UUID of the consistency group.
status body string The consistency group status. A valid value is creating, available, error, deleting, or error_deleting.
links body array The consistency group links.
name body string The consistency group name.
description body string The consistency group description.
source_cgsnapshot_id body string The consistency group snapshot ID. A valid value is null or the ID of the consistency group snapshot, if the consistency group was created from a snapshot.
created_at body string

The date and time stamp when the consistency group was created.

The date and time stamp format is ISO 8601:

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_network_id body string The UUID of the share network.
host body string The consistency group host name.
project_id body string The ID of the project in which the consistency group snapshot was created.
share_server_id body string The UUID of the share server.
share_types body array A list of share type IDs.

Response example

{
    "consistency_group": {
        "status": "available",
        "description": "My first CG.",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/9397c191-8427-4661-a2e8-b23820dc01d4",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/9397c191-8427-4661-a2e8-b23820dc01d4",
                "rel": "bookmark"
            }
        ],
        "source_cgsnapshot_id": null,
        "created_at": "2015-09-16T16:50:31.000000",
        "share_network_id": "f9b2e754-ac01-4466-86e1-5c569424754e",
        "share_server_id": null,
        "host": "manila2@generic1#GENERIC1",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_types": [
            "be27425c-f807-4500-a056-d00721db45cf"
        ],
        "id": "9397c191-8427-4661-a2e8-b23820dc01d4",
        "name": "cg1"
    }
}
POST
/v2/{tenant_id}/consistency-groups

Create consistency group

Creates a consistency group.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
share_types (Optional) body array A list of share type IDs.
name (Optional) body string The consistency group name.
description (Optional) body string The consistency group description.
share_network_id body string The UUID of the share network.
source_cgsnapshot_id body string The consistency group snapshot ID. A valid value is null or the ID of the consistency group snapshot, if the consistency group was created from a snapshot.

Request example

{
    "consistency_group": {
        "share_types": [
            "d2ad4f9d-cae3-4660-b0b6-58c06b385203"
        ],
        "name": "my-cg1",
        "share_network_id": "d8ae6799-2567-4a89-aafb-fa4424350d2b",
        "description": "my first consistency group"
    }
}

Response parameters

Name In Type Description
consistency_group body array The consistency_group object.
id body string The UUID of the consistency group.
status body string The consistency group status. A valid value is creating, available, error, deleting, or error_deleting.
links body array The consistency group links.
name body string The consistency group name.
description body string The consistency group description.
source_cgsnapshot_id body string The consistency group snapshot ID. A valid value is null or the ID of the consistency group snapshot, if the consistency group was created from a snapshot.
created_at body string

The date and time stamp when the consistency group was created.

The date and time stamp format is ISO 8601:

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_network_id body string The UUID of the share network.
host body string The consistency group host name.
project_id body string The ID of the project in which the consistency group snapshot was created.
share_server_id body string The UUID of the share server.
share_types body array A list of share type IDs.

Response example

{
    "consistency_group": {
        "status": "creating",
        "description": "my first consistency group",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/6f519a48-3183-46cf-a32f-41815f813986",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/6f519a48-3183-46cf-a32f-41815f813986",
                "rel": "bookmark"
            }
        ],
        "source_cgsnapshot_id": null,
        "created_at": "2015-09-16T09:28:52.880949",
        "share_network_id": "d8ae6799-2567-4a89-aafb-fa4424350d2b",
        "host": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_types": [
            "d2ad4f9d-cae3-4660-b0b6-58c06b385203"
        ],
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "name": "my-cg1"
    }
}
PUT
/v2/{tenant_id}/consistency-groups/{consistency_group_id}

Update consistency group

Updates a consistency group.

You can update only these attributes:

  • name, which changes the consistency group name.
  • description, which changes the consistency group description.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The UUID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the administrative tenant.
consistency_group_id path string The UUID of the consistency group.
name (Optional) body string The consistency group name.
description (Optional) body string The consistency group description.

Request example

{
    "consistency_group": {
        "description": "Edited description"
    }
}

Response parameters

Name In Type Description
consistency_group body array The consistency_group object.
id body string The UUID of the consistency group.
status body string The consistency group status. A valid value is creating, available, error, deleting, or error_deleting.
links body array The consistency group links.
name body string The consistency group name.
description body string The consistency group description.
source_cgsnapshot_id body string The consistency group snapshot ID. A valid value is null or the ID of the consistency group snapshot, if the consistency group was created from a snapshot.
created_at body string

The date and time stamp when the consistency group was created.

The date and time stamp format is ISO 8601:

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_network_id body string The share network ID.
host body string The consistency group host name.
project_id body string The ID of the project in which the consistency group snapshot was created.
share_server_id body string The UUID of the share server.
share_types body array A list of share type IDs.

Response example

{
    "consistency_group": {
        "status": "error",
        "description": "Edited description",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/aed36625-a6d7-4681-ba59-c7ba3d18c148",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/aed36625-a6d7-4681-ba59-c7ba3d18c148",
                "rel": "bookmark"
            }
        ],
        "source_cgsnapshot_id": null,
        "created_at": "2015-09-16T09:31:15.000000",
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
        "host": null,
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "share_types": [
            "be27425c-f807-4500-a056-d00721db45cf"
        ],
        "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
        "name": "my-cg2"
    }
}
POST
/v2/{tenant_id}/consistency-groups/{consistency_group_id}/action

Reset consistency group state

Administrator only. Explicitly updates the state of a consistency group.

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

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
consistency_group_id path string The UUID of the consistency group.
reset_status body object The reset_status object.
os-reset_status body object The reset_status object.
status body string The consistency group snapshot status, which is available, creating, error, deleting, or error_deleting.

Request example

{
    "reset_status": {
        "status": "available"
    }
}
POST
/v2/{tenant_id}/consistency-groups/{consistency_group_id}/action

Force-delete consistency group

Administrator only. Force-deletes a consistency group.

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

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
consistency_group_id path string The UUID of the consistency group.
os-force_delete body object The force_delete object.
force_delete body string To force-delete a consistency group snapshot, set this value to null.

Request example

{
    "force_delete": null
}
DELETE
/v2/{tenant_id}/consistency-groups/{consistency_group_id}

Delete consistency group

Deletes a consistency group.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
consistency_group_id path string The UUID of the consistency group.

Consistency group snapshots (since API v2.4)

You can create snapshots of consistency groups. To create a snapshot, you specify the ID of the consistency group that you want to snapshot. After you create a consistency group snapshot, you can create a consistency group from it.

A consistency group snapshot can have member shares. To add a member share, include the consistency_group_id parameter in the create share request. This ID must match the ID of the consistency group from which the consistency group snapshot was created. Then, when you use consistency group snapshots to restore data, you can easily determine which shares belong to a consistency group.

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

Note

Consistency group snapshot APIs are part of an experimental feature introduced in version 2.4. The APIs may change or be removed in further versions of the Shared File Systems API. All experimental APIs require the X-OpenStack-Manila-API-Experimental: True header to be sent in the requests.

GET
/v2/{tenant_id}/cgsnapshots

List consistency group snapshots

Lists all consistency group snapshots.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
limit (Optional) query integer The maximum number of consistency groups snapshots to return.
offset (Optional) query integer The offset to define start point of consistency group snapshot listing.
all_tenants (Optional) query boolean (Admin only). Defines whether to list consistency group snapshots for all tenants. Set to 1 to list consistency groups for all tenants. Set to 0 to list consistency groups only for the current tenant.

Response parameters

Name In Type Description
cgsnapshots body array The cgsnapshots object
cgsnapshot body object The cgsnapshot object
id body string The consistency group snapshot ID.
name body string The consistency group snapshot name.
cgsnapshot_links (Optional) body array The consistency share snapshot links.

Response example

{
    "cgsnapshots": [
        {
            "id": "7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
                    "rel": "bookmark"
                }
            ],
            "name": "snapshot_CG2"
        },
        {
            "id": "b44c894d-4bec-47aa-b389-cc8c6f0044a5",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5",
                    "rel": "bookmark"
                }
            ],
            "name": "snapshot_cg1"
        }
    ]
}
GET
/v2/{tenant_id}/cgsnapshots/detail

List consistency group snapshots with details

Lists all consistency group snapshots with details.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
limit (Optional) query integer The maximum number of consistency groups snapshots to return.
offset (Optional) query integer The offset to define start point of consistency group snapshot listing.
all_tenants (Optional) query boolean (Admin only). Defines whether to list consistency group snapshots for all tenants. Set to 1 to list consistency groups for all tenants. Set to 0 to list consistency groups only for the current tenant.

Response parameters

Name In Type Description
cgsnapshots body array The cgsnapshots object
cgsnapshot body object The cgsnapshot object
id body string The consistency group snapshot ID.
status body string The consistency group snapshot status, which is available, creating, error, deleting, or error_deleting.
links body array The share links
project_id body string The ID of the project in which the consistency group snapshot was created.
consistency_group_id body string The ID of the consistency group from which the snapshot was created.
name body string The consistency group snapshot name.
description body string The consistency group snapshot description.
created_at body string The date and time stamp when the consistency group snapshot was created.
cgsnapshot_links (Optional) body array The consistency share snapshot links.

Response example

{
    "cgsnapshots": [
        {
            "status": "available",
            "name": "snapshot_CG2",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
                    "rel": "bookmark"
                }
            ],
            "created_at": "2015-09-16T17:37:40.000000",
            "consistency_group_id": "2d5c2600-ae67-4dff-b13c-a1c20b335e8e",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "id": "7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
            "description": "Snapshot of CG2"
        },
        {
            "status": "available",
            "name": "snapshot_cg1",
            "links": [
                {
                    "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5",
                    "rel": "self"
                },
                {
                    "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5",
                    "rel": "bookmark"
                }
            ],
            "created_at": "2015-09-16T17:34:15.000000",
            "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "id": "b44c894d-4bec-47aa-b389-cc8c6f0044a5",
            "description": "Snapshot of cg1"
        }
    ]
}
GET
/v2/{tenant_id}/cgsnapshots/{cgsnapshot_id}

Show consistency group snapshot details

Shows details for a consistency group snapshot.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
cgsnapshot_id (Optional) path string The UUID of the consistency group snapshot.

Response parameters

Name In Type Description
cgsnapshot body object The cgsnapshot object
id body string The consistency group snapshot ID.
status body string The consistency group snapshot status, which is available, creating, error, deleting, or error_deleting.
links body array The share links
project_id body string The ID of the project in which the consistency group snapshot was created.
consistency_group_id body string The ID of the consistency group from which the snapshot was created.
name body string The consistency group snapshot name.
description body string The consistency group snapshot description.
created_at body string The date and time stamp when the consistency group snapshot was created.
cgsnapshot_links (Optional) body array The consistency share snapshot links.

Response example

{
    "cgsnapshot": {
        "status": "available",
        "name": "snapshot_cg1",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5",
                "rel": "bookmark"
            }
        ],
        "created_at": "2015-09-16T17:34:15.000000",
        "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "id": "b44c894d-4bec-47aa-b389-cc8c6f0044a5",
        "description": "Snapshot of cg1"
    }
}
GET
/v2/{tenant_id}/cgsnapshots/{cgsnapshot_id}/members

List consistency group snapshot members

Shows information about a consistency group snapshot member.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
cgsnapshot_id path string The UUID of the consistency group snapshot.
limit (Optional) query integer The maximum number of consistency groups snapshot members to return.
offset (Optional) query integer The offset to define start point of consistency group snapshot member listing.

Response parameters

Name In Type Description
cgsnapshot_members body array The cgsnapshot_members object
id body string The consistency group snapshot member ID.
share_id body string The ID of the share that is a consistency group snapshot member.
share_type_id body string The share type ID of the member.
created_at body string The date and time stamp when the member was created.
cgsnapshot_id path string The UUID of the consistency group snapshot.
share_protocol body string The file system protocol of the member, which is NFS, CIFS, GlusterFS, HDFS or CEPHFS.
project_id body string The ID of the project in which the consistency group snapshot member was created.
size body integer The member size, in GBs.
cgsnapshot_members_links body array The consistency share snapshot member links.

Response example

{
    "cgsnapshot_members": [
        {
            "share_type_id": "be27425c-f807-4500-a056-d00721db45cf",
            "share_id": "609e4924-f062-45e0-928d-7b739348c4d6",
            "created_at": "2015-09-16T17:34:15.000000",
            "cgsnapshot_id": "b44c894d-4bec-47aa-b389-cc8c6f0044a5",
            "share_protocol": "NFS",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "id": "84098fde-40ec-4c96-a908-bc532c52b3af",
            "size": 1
        },
        {
            "share_type_id": "be27425c-f807-4500-a056-d00721db45cf",
            "share_id": "c4a2ced4-2c9f-4ae1-adaa-6171833e64df",
            "created_at": "2015-09-16T17:34:15.000000",
            "cgsnapshot_id": "b44c894d-4bec-47aa-b389-cc8c6f0044a5",
            "share_protocol": "NFS",
            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
            "id": "db492d38-dd3a-4d6b-a3b6-e65377990892",
            "size": 1
        }
    ]
}
POST
/v2/{tenant_id}/cgsnapshots

Create consistency group snapshot

Creates a consistency group snapshot.

You can create a consistency group snapshot for a consistency group in available state only.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
consistency_group_id body string The ID of the consistency group from which to create a snapshot.
name (Optional) body string The consistency group snapshot name.
description (Optional) body string The consistency group snapshot description.

Request example

{
    "cgsnapshot": {
        "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
        "name": "snapshot_cg1",
        "description": "Snapshot of cg1"
    }
}

Response parameters

Name In Type Description
cgsnapshot body object The cgsnapshot object
id body string The consistency group snapshot ID.
status body string The consistency group snapshot status, which is available, creating, error, deleting, or error_deleting.
links body array The share links
project_id body string The ID of the project in which the consistency group snapshot was created.
consistency_group_id body string The ID of the consistency group from which the snapshot was created.
name body string The consistency group snapshot name.
description body string The consistency group snapshot description.
created_at body string The date and time stamp when the consistency group snapshot was created.
cgsnapshot_links (Optional) body array The consistency share snapshot links.

Response example

{
    "cgsnapshot": {
        "status": "creating",
        "name": "snapshot_cg1",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5",
                "rel": "bookmark"
            }
        ],
        "created_at": "2015-09-16T17:34:06.031997",
        "consistency_group_id": "9397c191-8427-4661-a2e8-b23820dc01d4",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "id": "b44c894d-4bec-47aa-b389-cc8c6f0044a5",
        "description": "Snapshot of cg1"
    }
}
POST
/v2/{tenant_id}/cgsnapshots/{cgsnapshot_id}/action

Reset consistency group snapshot state

Administrator only. Explicitly updates the state of a consistency group snapshot.

Administrators can use the policy.json file to permit other roles to complete this action.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
cgsnapshot_id (Optional) path string The UUID of the consistency group snapshot.
reset_status body object The reset_status object.
os-reset_status body object The reset_status object.
status body string The consistency group snapshot status, which is available, creating, error, deleting, or error_deleting.

Request example

{
    "reset_status": {
        "status": "error"
    }
}
POST
/v2/{tenant_id}/cgsnapshots/{cgsnapshot_id}/action

Force-delete consistency group snapshot

Administrator only. Force-deletes a consistency group snapshot.

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

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
cgsnapshot_id path string The UUID of the consistency group snapshot.
force_delete body string To force-delete a consistency group snapshot, set this value to null.

Request example

{
    "force_delete": null
}
PUT
/v2/{tenant_id}/cgsnapshots/{cgsnapshot_id}

Update consistency group snapshot

Updates a consistency group snapshot.

You can update only these attributes:

  • name, which changes the consistency group snapshot name.
  • description, which changes the consistency group snapshot description.

Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
cgsnapshot_id path string The UUID of the consistency group snapshot.
name (Optional) body string The consistency group snapshot name.
description (Optional) body string The consistency group snapshot description.

Request example

{
    "cgsnapshot": {
        "description": "Changed description: there is a snapshot of CG2"
    }
}

Response parameters

Name In Type Description
cgsnapshot body object The cgsnapshot object
id body string The consistency group snapshot ID.
status body string The consistency group snapshot status, which is available, creating, error, deleting, or error_deleting.
links body array The share links
project_id body string The ID of the project in which the consistency group snapshot was created.
consistency_group_id body string The ID of the consistency group from which the snapshot was created.
name body string The consistency group snapshot name.
description body string The consistency group snapshot description.
created_at body string The date and time stamp when the consistency group snapshot was created.
cgsnapshot_links (Optional) body array The consistency share snapshot links.

Response example

{
    "cgsnapshot": {
        "status": "available",
        "name": "snapshot_CG2",
        "links": [
            {
                "href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
                "rel": "self"
            },
            {
                "href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
                "rel": "bookmark"
            }
        ],
        "created_at": "2015-09-16T17:37:40.000000",
        "consistency_group_id": "2d5c2600-ae67-4dff-b13c-a1c20b335e8e",
        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
        "id": "7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6",
        "description": "Changed description: there is a snapshot of CG2"
    }
}
DELETE
/v2/{tenant_id}/cgsnapshots/{cgsnapshot_id}

Delete consistency group snapshot

Deletes a consistency group snapshot.

Normal response codes: 202 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
tenant_id path string The tenant ID in a multi-tenancy cloud.
cgsnapshot_id path string The UUID of the consistency group snapshot.
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

Contents