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
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.
A list of version objects that describe the API versions available.
id
body
string
A common name for the version in question. Informative only, it has no real semantic meaning.
updated
body
string
A date and time stamp for API versions. This field presents no meaningful
information.
status
body
string
The status of this API version. This can be one of:
CURRENT: this is the preferred version of the API to use
SUPPORTED: this is an older, but still supported version of the API
DEPRECATED: a deprecated version of the API that is slated for removal
links
body
array
The share links
media-types
body
object
Media types supported by the API.
version
body
string
If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.
min_version
body
string
If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.
Note
The updated and media-types parameters in the response are
vestigial and provide no useful information. They will probably be
deprecated and removed in the future.
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.
A common name for the version in question. Informative only, it has no real semantic meaning.
status
body
string
The status of this API version. This can be one of:
CURRENT: this is the preferred version of the API to use
SUPPORTED: this is an older, but still supported version of the API
DEPRECATED: a deprecated version of the API that is slated for removal
links
body
array
The share links
version
body
string
If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.
updated
body
string
A date and time stamp for API versions. This field presents no meaningful
information.
min_version
body
string
If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.
media-types
body
object
Media types supported by the API.
Note
The updated and media-types parameters in the response are
vestigial and provide no useful information. They will probably be
deprecated and removed in the future.
{"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 are the resource limitations that are allowed for each
tenant (project). An administrator can configure limits in the
manila.conf file.
Users can query their rate and absolute limits. The absolute limits
contain information about:
Total maximum share memory, in GiBs.
Number of share-networks.
Number of share-snapshots.
Number of shares.
Shares and total used memory, in GiBs.
Snapshots and total used memory, in GiBs.
Number of share replicas (since API version 2.53).
Share replicas and total used memory, in GiBs (since API version 2.53).
Rate limits control the frequency at which users can issue specific
API requests. Administrators use rate limiting to configure limits
on the type and number of API calls that can be made in a specific
time interval. For example, a rate limit can control the number of
GET requests that can be processed during a one-minute period.
The total maximum number of share gigabytes that
are allowed in a project. You cannot request a share that exceeds
the allowed gigabytes quota.
maxTotalSnapshotGigabytes
body
integer
The total maximum number of snapshot gigabytes
that are allowed in a project.
maxTotalShares
body
integer
The total maximum number of shares that are
allowed in a project.
maxTotalShareSnapshots
body
integer
The total maximum number of share snapshots that
are allowed in a project.
maxTotalShareNetworks
body
integer
The total maximum number of share-networks that
are allowed in a project.
maxTotalShareReplicas
body
integer
The maximum number of share replicas that is allowed.
New in version 2.53
maxTotalReplicaGigabytes
body
integer
The maximum number of replica gigabytes that are allowed in a project.
You cannot create a share, share replica, manage a share or extend a
share if it is going to exceed the allowed replica gigabytes quota.
New in version 2.53
totalSharesUsed
body
integer
The total number of created shares in a project.
totalShareSnapshotsUsed
body
integer
The total number of created share snapshots in a
project.
totalShareNetworksUsed
body
integer
The total number of created share-networks in a
project.
totalShareGigabytesUsed
body
integer
The total number of gigabytes used in a project
by shares.
totalSnapshotGigabytesUsed
body
integer
The total number of gigabytes used in a project
by snapshots.
totalShareReplicasUsed
body
integer
The total number of created share replicas in a project.
totalReplicaGigabytesUsed
body
integer
The total number of replica gigabytes used in a
project by share replicas.
uri (Optional)
body
string
A human-readable URI of a rate limit.
regex (Optional)
body
string
An API regular expression. For example,
^/shares for the /shares API URI or .* for any URI.
value (Optional)
body
integer
The number of API requests that are allowed
during a time interval. Used in conjunction with the unit
parameter, expressed as value per unit. For example, 120
requests are allowed per minute.
verb (Optional)
body
string
The HTTP method for the API request. For example,
GET, POST, DELETE, and so on.
remaining (Optional)
body
integer
The remaining number of allowed requests.
unit (Optional)
body
string
The time interval during which a number of API
requests are allowed. A valid value is SECOND, MINUTE,
HOUR, or DAY. Used in conjunction with the value
parameter, expressed as value per unit. For example, 120
requests are allowed per minute.
next-available (Optional)
body
string
The date and time stamp when next issues are available.
A share is a remote, mountable file system. In the APIs below, a share
resource is a representation of this remote file system within the Shared
File Systems service. This resource representation includes useful metadata,
communicating the characteristics of the remote file system as determined by
the user and the Shared File Systems service.
You can create a share and associate it with a network, list
shares, and show information for, update, and delete a share.
To create a share, specify one of these supported protocols:
NFS. Network File System (NFS).
CIFS. Common Internet File System (CIFS).
GLUSTERFS. Gluster file system (GlusterFS).
HDFS. Hadoop Distributed File System (HDFS).
CEPHFS. Ceph File System (CephFS).
MAPRFS. MapR File System (MAPRFS).
You can also create snapshots of shares. To create a snapshot, you
specify the ID of the share that you want to snapshot.
A share has one of these status values:
Share statuses
Status
Description
creating
The share is being created.
creating_from_snapshot
The share is being created from a parent snapshot.
deleting
The share is being deleted.
deleted
The share was deleted.
error
An error occurred during share creation.
error_deleting
An error occurred during share deletion.
available
The share is ready to use.
inactive
The share is inactive.
manage_starting
Share manage started.
manage_error
Share manage failed.
unmanage_starting
Share unmanage started.
unmanage_error
Share cannot be unmanaged.
unmanaged
Share was unmanaged.
extending
The extend, or increase, share size request was issued
successfully.
The project ID of the user or service making the API request.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list the requested resources for
all projects. Set to 1 to list resources for all projects.
Set to 0 to list resources only for the current project. Examples
of resources include shares, snapshots, share networks, security services
and share groups.
name (Optional)
query
string
The user defined name of the resource to filter resources by.
status (Optional)
query
string
Filters by a share status. A valid value is
creating, creating_from_snapshot, error, available,
deleting, error_deleting, manage_starting, manage_error,
unmanage_starting, unmanage_error, migrating,
extending, extending_error, shrinking,
shrinking_error, or shrinking_possible_data_loss_error.
share_server_id (Optional)
query
string
The UUID of the share server.
metadata (Optional)
query
object
One or more metadata key and value pairs as a
url encoded dictionary of strings.
extra_specs (Optional)
query
string
The extra specifications as a set of one or more
key-value pairs. In each pair, the key is the name of the extra
specification and the value is the share type that was used to
filter search share type list.
New in version 2.43
share_type_id (Optional)
query
string
The UUID of a share type to query resources by.
snapshot_id (Optional)
query
string
The UUID of the share’s base snapshot to filter the request based on.
host (Optional)
query
string
The host name of the resource to query with. Querying by hostname is a
privileged operation. If restricted by API policy, this query parameter
may be silently ignored by the server.
share_network_id (Optional)
query
string
The UUID of the share network to filter resources by.
project_id (Optional)
query
string
The ID of the project that owns the resource. This query parameter is
useful in conjunction with the all_tenants parameter.
is_public (Optional)
query
boolean
A boolean query parameter that, when set to true, allows retrieving
public resources that belong to all projects.
share_group_id (Optional)
query
string
The UUID of a share group to filter resource.
New in version 2.31
export_location_id (Optional)
query
string
The export location UUID that can be used to filter shares or
share instances.
New in version 2.35
export_location_path (Optional)
query
string
The export location path that can be used to filter shares or
share instances.
New in version 2.35
name~ (Optional)
query
string
The name pattern that can be used to filter shares,
share snapshots, share networks or share groups.
New in version 2.36
description~ (Optional)
query
string
The description pattern that can be used to filter shares,
share snapshots, share networks or share groups.
New in version 2.36
with_count (Optional)
query
boolean
Whether to show count in API response or not, default is False.
New in version 2.42
limit (Optional)
query
integer
The maximum number of shares to return.
offset (Optional)
query
integer
The offset to define start point of share or share group
listing.
sort_key (Optional)
query
string
The key to sort a list of shares. A valid value
is id, status, size, host, share_proto,
export_location, availability_zone, user_id,
project_id, created_at, updated_at, display_name,
name, share_type_id, share_type, share_network_id,
share_network, snapshot_id, or snapshot.
sort_dir (Optional)
query
string
The direction to sort a list of shares. A valid
value is asc, or desc.
The project ID of the user or service making the API request.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list the requested resources for
all projects. Set to 1 to list resources for all projects.
Set to 0 to list resources only for the current project. Examples
of resources include shares, snapshots, share networks, security services
and share groups.
status (Optional)
query
string
Filters by a share status. A valid value is
creating, creating_from_snapshot, error, available,
deleting, error_deleting, manage_starting, manage_error,
unmanage_starting, unmanage_error, migrating,
extending, extending_error, shrinking,
shrinking_error, or shrinking_possible_data_loss_error.
share_server_id (Optional)
query
string
The UUID of the share server.
metadata (Optional)
query
object
One or more metadata key and value pairs as a
url encoded dictionary of strings.
extra_specs (Optional)
query
string
The extra specifications as a set of one or more
key-value pairs. In each pair, the key is the name of the extra
specification and the value is the share type that was used to
filter search share type list.
New in version 2.43
share_type_id (Optional)
query
string
The UUID of a share type to query resources by.
name (Optional)
query
string
The user defined name of the resource to filter resources by.
snapshot_id (Optional)
query
string
The UUID of the share’s base snapshot to filter the request based on.
host (Optional)
query
string
The host name of the resource to query with. Querying by hostname is a
privileged operation. If restricted by API policy, this query parameter
may be silently ignored by the server.
share_network_id (Optional)
query
string
The UUID of the share network to filter resources by.
project_id (Optional)
query
string
The ID of the project that owns the resource. This query parameter is
useful in conjunction with the all_tenants parameter.
is_public (Optional)
query
boolean
A boolean query parameter that, when set to true, allows retrieving
public resources that belong to all projects.
share_group_id (Optional)
query
string
The UUID of a share group to filter resource.
New in version 2.31
export_location_id (Optional)
query
string
The export location UUID that can be used to filter shares or
share instances.
New in version 2.35
export_location_path (Optional)
query
string
The export location path that can be used to filter shares or
share instances.
New in version 2.35
name~ (Optional)
query
string
The name pattern that can be used to filter shares,
share snapshots, share networks or share groups.
New in version 2.36
description~ (Optional)
query
string
The description pattern that can be used to filter shares,
share snapshots, share networks or share groups.
New in version 2.36
with_count (Optional)
query
boolean
Whether to show count in API response or not, default is False.
New in version 2.42
limit (Optional)
query
integer
The maximum number of shares to return.
offset (Optional)
query
integer
The offset to define start point of share or share group
listing.
sort_key (Optional)
query
string
The key to sort a list of shares. A valid value
is id, status, size, host, share_proto,
export_location, availability_zone, user_id,
project_id, created_at, updated_at, display_name,
name, share_type_id, share_type, share_network_id,
share_network, snapshot_id, or snapshot.
sort_dir (Optional)
query
string
The direction to sort a list of shares. A valid
value is asc, or desc.
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Available until version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id
body
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
The UUID of the share type. In minor versions, this parameter is
a share type name, as a string.
One or more metadata key and value pairs as a
dictionary of strings.
status
body
string
The share status, which is creating, creating_from_snapshot,
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.
progress
body
string
The progress of the share creation.
New in version 2.54
description
body
string
The user defined description of the resource.
host
body
string
The share host name.
access_rules_status
body
string
The share instance access rules status. A valid value is active,
error, or syncing. In versions prior to 2.28, syncing was
represented with status out_of_sync.
New in version 2.10
is_public (Optional)
body
boolean
The level of visibility for the share. Set to true to make
share public. Set to false to make it private. Default value
is false.
New in version 2.8
share_group_id
body
string
The UUID of the share group.
New in version 2.31
task_state
body
string
For the share migration, the migration task state. A valid
value is null, migration_starting, migration_error,
migration_success, migration_completing, or migrating.
The task_state is null unless the share is migrated from
one back-end to another. For details, see os-migrate_share
extension request.
New in version 2.5
snapshot_support
body
boolean
An extra specification that filters back ends by whether
they do or do not support share snapshots.
New in version 2.2
name
body
string
The user defined name of the resource.
has_replicas
body
boolean
Indicates whether a share has replicas or not.
New in version 2.11
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, CephFS,
MAPRFS, CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
count (Optional)
body
integer
The total count of requested resource before pagination is applied.
{"shares":[{"links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc","rel":"bookmark"}],"availability_zone":"nova","share_network_id":"f9b2e754-ac01-4466-86e1-5c569424754e","export_locations":[],"share_server_id":"87d8943a-f5da-47a4-b2f2-ddfa6794aa82","share_group_id":null,"snapshot_id":null,"id":"f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc","size":1,"share_type":"25747776-08e5-494f-ab40-a64b9d20d8f7","share_type_name":"default","export_location":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","metadata":{},"status":"error","progress":null,"access_rules_status":"active","description":"There is a share description.","host":"manila2@generic1#GENERIC1","task_state":null,"is_public":true,"snapshot_support":true,"name":"my_share4","has_replicas":false,"replication_type":null,"created_at":"2015-09-16T18:19:50.000000","share_proto":"NFS","volume_type":"default"},{"links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/c4a2ced4-2c9f-4ae1-adaa-6171833e64df","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/c4a2ced4-2c9f-4ae1-adaa-6171833e64df","rel":"bookmark"}],"availability_zone":"nova","share_network_id":"f9b2e754-ac01-4466-86e1-5c569424754e","export_locations":["10.254.0.5:/shares/share-50ad5e7b-f6f1-4b78-a651-0812cef2bb67"],"share_server_id":"87d8943a-f5da-47a4-b2f2-ddfa6794aa82","snapshot_id":null,"id":"c4a2ced4-2c9f-4ae1-adaa-6171833e64df","size":1,"share_type":"25747776-08e5-494f-ab40-a64b9d20d8f7","share_type_name":"default","export_location":"10.254.0.5:/shares/share-50ad5e7b-f6f1-4b78-a651-0812cef2bb67","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","metadata":{},"status":"available","progress":"100%","access_rules_status":"active","description":"Changed description.","host":"manila2@generic1#GENERIC1","task_state":null,"is_public":true,"snapshot_support":true,"name":"my_share4","has_replicas":false,"replication_type":null,"created_at":"2015-09-16T17:26:28.000000","share_proto":"NFS","volume_type":"default"}],"count":10}
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Available until version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id
body
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
The UUID of the share type. In minor versions, this parameter is
a share type name, as a string.
One or more metadata key and value pairs as a
dictionary of strings.
status
body
string
The share status, which is creating, creating_from_snapshot,
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.
progress
body
string
The progress of the share creation.
New in version 2.54
description
body
string
The user defined description of the resource.
host (Optional)
body
string
The share host name.
access_rules_status
body
string
The share instance access rules status. A valid value is active,
error, or syncing. In versions prior to 2.28, syncing was
represented with status out_of_sync.
New in version 2.10
is_public (Optional)
body
boolean
The level of visibility for the share. Set to true to make
share public. Set to false to make it private. Default value
is false.
New in version 2.8
share_group_id
body
string
The UUID of the share group.
New in version 2.31
task_state
body
string
For the share migration, the migration task state. A valid
value is null, migration_starting, migration_error,
migration_success, migration_completing, or migrating.
The task_state is null unless the share is migrated from
one back-end to another. For details, see os-migrate_share
extension request.
New in version 2.5
snapshot_support
body
boolean
An extra specification that filters back ends by whether
they do or do not support share snapshots.
New in version 2.2
name
body
string
The user defined name of the resource.
has_replicas
body
boolean
Indicates whether a share has replicas or not.
New in version 2.11
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, CephFS,
MAPRFS, CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
The project ID of the user or service making the API request.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, CephFS,
MAPRFS, CephFS supported is starting with API v2.13.
size
body
integer
The share size, in GBs. The requested share size
cannot be greater than the allowed GB quota. To view the allowed
quota, issue a get limits request.
name (Optional)
body
string
The user defined name of the resource. The value of this field is
limited to 255 characters.
description (Optional)
body
string
The user defined description of the resource. The value of this field is
limited to 255 characters.
display_name (Optional)
body
string
The user defined name of the resource. This field sets the name
parameter.
display_description (Optional)
body
string
The user defined description of the resource. This field sets the
description parameter.
share_type (Optional)
body
string
The share type name. If you omit this parameter,
the default share type is used. To view the default share type set
by the administrator, issue a list default share types request.
You cannot specify both the share_type and volume_type
parameters.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
snapshot_id (Optional)
body
string
The UUID of the share’s base snapshot.
is_public (Optional)
body
boolean
The level of visibility for the share. Set to true to make
share public. Set to false to make it private. Default value
is false.
New in version 2.8
share_group_id (Optional)
body
string
The UUID of the share group.
New in version 2.31
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
share_network_id (Optional)
body
string
The UUID of a share network where the share
server exists or will be created. If share_network_id is
None and you provide a snapshot_id, the
share_network_id value from the snapshot is used.
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. - creating_from_snapshot.
The share is being created from a parent snapshot.
progress
body
string
The progress of the share creation.
New in version 2.54
links
body
array
The share links
project_id
body
string
The ID of the project that owns the resource.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, CephFS,
MAPRFS, CephFS supported is starting with API v2.13.
size
body
integer
The share size, in GBs. The requested share size
cannot be greater than the allowed GB quota. To view the allowed
quota, issue a get limits request.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
share_type
body
string
The UUID of the share type. In minor versions, this parameter is
a share type name, as a string.
New in version 2.6
share_type_name
body
string
Name of the share type.
New in version 2.6
has_replicas
body
boolean
Indicates whether a share has replicas or not.
New in version 2.11
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
snapshot_id
body
string
The UUID of the snapshot that was used to create
the share.
is_public (Optional)
body
boolean
The level of visibility for the share. Set to true to make
share public. Set to false to make it private. Default value
is false.
New in version 2.8
share_group_id
body
string
The UUID of the share group.
New in version 2.31
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Available until version 2.8
host
body
string
The share host name.
task_state
body
string
For the share migration, the migration task state. A valid
value is null, migration_starting, migration_error,
migration_success, migration_completing, or migrating.
The task_state is null unless the share is migrated from
one back-end to another. For details, see os-migrate_share
extension request.
New in version 2.5
share_server_id
body
string
The UUID of the share server.
snapshot_support
body
boolean
An extra specification that filters back ends by whether
they do or do not support share snapshots.
New in version 2.2
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The project ID of the user or service making the API request.
share
body
object
A share object.
protocol
body
string
The Shared File Systems protocol of the share to
manage. A valid value is NFS, CIFS, GlusterFS,
CEPHFS, HDFS or MAPRFS.
name (Optional)
body
string
The user defined name of the resource. The value of this field is
limited to 255 characters.
share_type (Optional)
body
string
The share type name.
driver_options (Optional)
body
object
A set of one or more key and value pairs, as a
dictionary of strings, that describe driver options. Details for
driver options should be taken from appropriate share driver
documentation.
export_path
body
string
The share export path in the format appropriate
for the protocol: - NFS protocol. 10.0.0.1:/foo_path. For
example, 10.254.0.5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5. - CIFS protocol.
\\10.0.0.1\foo_name_of_cifs_share.
service_host
body
string
The manage-share service host in this format:
host@backend#POOL. - host. The host name for the back
end. - backend. The name of the back end. - POOL. The
pool name for the back end.
share_server_id
body
string
The UUID of the share server.
New in version 2.49
is_public (Optional)
body
boolean
The level of visibility for the share. Set to true to make
share public. Set to false to make it private. Default value
is false.
New in version 2.8
description (Optional)
body
string
The user defined description of the resource. The value of this field is
limited to 255 characters.
{"share":{"protocol":"nfs","name":"accounting_p8787","share_type":"gold","driver_options":{"opt1":"opt1","opt2":"opt2"},"export_path":"192.162.10.6:/shares/share-accounting_p8787","service_host":"manila2@openstackstor01#accountingpool","is_public":true,"description":"Common storage for spreadsheets and presentations. Please contact John Accessman to be added to the users of this drive.","share_server_id":"00137b40-ca06-4ae8-83a3-2c5989eebcce"}}
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Available until version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id
body
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
The UUID of the share type. In minor versions, this parameter is
a share type name, as a string.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, CephFS,
MAPRFS, CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Available until version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id
body
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
The UUID of the share type. In minor versions, this parameter is
a share type name, as a string.
One or more metadata key and value pairs as a
dictionary of strings.
status
body
string
The share status, which is creating, creating_from_snapshot,
error, available, deleting, error_deleting,
manage_starting, manage_error, unmanage_starting,
unmanage_error, unmanaged, extend,
extending_error, shrinking, shrinking_error, or
shrinking_possible_data_loss_error.
description
body
string
The user defined description of the resource.
host (Optional)
body
string
The share host name.
access_rules_status
body
string
The share instance access rules status. A valid value is active,
error, or syncing. In versions prior to 2.28, syncing was
represented with status out_of_sync.
New in version 2.10
is_public (Optional)
body
boolean
The level of visibility for the share. Set to true to make
share public. Set to false to make it private. Default value
is false.
New in version 2.8
share_group_id
body
string
The UUID of the share group.
New in version 2.31
task_state
body
string
For the share migration, the migration task state. A valid
value is null, migration_starting, migration_error,
migration_success, migration_completing, or migrating.
The task_state is null unless the share is migrated from
one back-end to another. For details, see os-migrate_share
extension request.
New in version 2.5
snapshot_support
body
boolean
An extra specification that filters back ends by whether
they do or do not support share snapshots.
New in version 2.2
name
body
string
The user defined name of the resource.
has_replicas
body
boolean
Indicates whether a share has replicas or not.
New in version 2.11
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, CephFS,
MAPRFS, CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
{"share":{"links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264","rel":"bookmark"}],"availability_zone":"nova","share_network_id":"713df749-aac0-4a54-af52-10f6c991e80c","export_locations":[],"share_server_id":"e268f4aa-d571-43dd-9ab3-f49ad06ffaef","share_group_id":null,"snapshot_id":null,"id":"011d21e2-fbc3-4e4a-9993-9ea223f73264","size":1,"share_type":"25747776-08e5-494f-ab40-a64b9d20d8f7","share_type_name":"default","export_location":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","metadata":{"project":"my_app","aim":"doc"},"status":"error","description":"Changing the share description.","host":"manila2@generic1#GENERIC1","task_state":null,"is_public":true,"snapshot_support":true,"name":"share_London","created_at":"2015-09-18T10:25:24.000000","share_proto":"NFS","volume_type":"default"}}
DELETE
/v2/{project_id}/shares/{share_id}
Delete share
Deletes a share.
Preconditions
Share status must be available, error or inactive
You cannot already have a snapshot of the share.
You cannot already have a group snapshot of the share.
Set of APIs used for viewing export locations of shares.
These APIs allow retrieval of export locations belonging to non-active share
replicas until API version 2.46. In and beyond API version 2.47, export
locations of non-active share replicas can only be retrieved using the
Share Replica Export Locations APIs.
The UUID of the share instance that this
export location belongs to. This parameter is only available to users
with an “administrator” role, and cannot be controlled via policy.json.
path
body
string
The export location path that should be used for mount operation.
is_admin_only
body
boolean
Defines purpose of an export location. If set to
true, then it is expected to be used for service needs and by
administrators only. If it is set to false, then this export
location can be used by end users. This parameter is only available to
users with an “administrator” role, and cannot be controlled via policy
.json.
preferred
body
boolean
Drivers may use this field to identify which export locations
are most efficient and should be used preferentially by clients.
By default it is set to false value.
The UUID of the share instance that this
export location belongs to. This parameter is only available to users
with an “administrator” role, and cannot be controlled via policy.json.
path
body
string
The export location path that should be used for mount operation.
is_admin_only
body
boolean
Defines purpose of an export location. If set to
true, then it is expected to be used for service needs and by
administrators only. If it is set to false, then this export
location can be used by end users. This parameter is only available to
users with an “administrator” role, and cannot be controlled via policy
.json.
preferred
body
boolean
Drivers may use this field to identify which export locations
are most efficient and should be used preferentially by clients.
By default it is set to false value.
New in version 2.14
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
Retrieves a specific metadata item from a share’s metadata by its key. If
the specified key does not represent a valid metadata item, the API will
respond with HTTP 404.
The project ID of the user or service making the API request.
share_id
path
string
The UUID of the share.
key
body
object
The key of a metadata item. For example, if the metadata on an existing
share or access rule is as follows: "project":"my_test","aim":"testing", the keys are “project” and “aim”.
Allows adding new metadata items as key-value pairs. This API will not delete
pre-existing metadata items. If the request object contains metadata items
that already exist, they will be updated with new values as specified in the
request object.
The project ID of the user or service making the API request.
share_id
path
string
The UUID of the share.
metadata
body
object
One or more metadata key-value pairs, as a
dictionary of strings. For example, "project":"my_test","aim":"testing". The share server does not respect case-sensitive key
names. For example, "key":"v1" and "KEY":"V1" are
equivalent. If you specify both key-value pairs, the server sets
and returns only the "KEY":"V1" key-value pair.
Replaces the metadata for a given share with the metadata (specified as
key-value pairs) in the request object. All pre-existing metadata of the
share will be deleted and replaced with the new metadata supplied.
The project ID of the user or service making the API request.
share_id
path
string
The UUID of the share.
metadata
body
object
One or more metadata key-value pairs, as a
dictionary of strings. For example, "project":"my_test","aim":"testing". The share server does not respect case-sensitive key
names. For example, "key":"v1" and "KEY":"V1" are
equivalent. If you specify both key-value pairs, the server sets
and returns only the "KEY":"V1" key-value pair.
Deletes a single metadata item on a share, idetified by its key. If
the specified key does not represent a valid metadata item, the API will
respond with HTTP 404.
The project ID of the user or service making the API request.
share_id
path
string
The UUID of the share.
key
body
object
The key of a metadata item. For example, if the metadata on an existing
share or access rule is as follows: "project":"my_test","aim":"testing", the keys are “project” and “aim”.
Share actions include granting or revoking share access, listing the
available access rules for a share, explicitly updating the state of a
share, resizing a share and un-managing a share.
As administrator, you can reset the state of a share and force-
delete a share in any state. Use the policy.json file to grant
permissions for this action to other roles.
You can set the state of a share to one of these supported states:
available
error
creating
deleting
error_deleting
If API version 1.0-2.6 is used then all share actions, defined
below, should include prefix os- in top element of request
JSON’s body.
For example: {“access_list”: null} is valid for v2.7+. And {“os-
access_list”: null} is valid for v1.0-2.6
POST
/v2/{project_id}/shares/{share_id}/action
Grant access
All manila shares begin with no access. Clients must be provided with
explicit access via this API.
To grant access, specify one of these supported share access levels:
rw. Read and write (RW) access.
ro. Read-only (RO) access.
You must also specify one of these supported authentication
methods:
ip. Authenticates an instance through its IP address.
The value specified should be a valid IPv4 or an IPv6 address,
or a subnet in CIDR notation.
A valid format is X:X:X:X:X:X:X:X, X:X:X:X:X:X:X:X/XX,
XX.XX.XX.XX, or XX.XX.XX.XX/XX, etc. For
example 0.0.0.0/0 or ::/0.
Important
IPv6 based access is only supported with API version 2.38 and beyond.
cert. Authenticates an instance through a TLS certificate.
Specify the TLS identity as the IDENTKEY. A valid value is any
string up to 64 characters long in the common name (CN) of the
certificate. The meaning of a string depends on its
interpretation.
user. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 255 characters long.
The project ID of the user or service making the API request.
share_id
path
string
The UUID of the share.
allow_access
body
object
The object of grant access.
access_level
body
string
The access level to the share. To grant or deny
access to a share, you specify one of the following share access
levels: - rw. Read and write (RW) access. - ro. Read-
only (RO) access.
access_type
body
string
The access rule type. A valid value for the
share access rule type is one of the following values: - ip.
Authenticates an instance through its IP address. A valid format
is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example
0.0.0.0/0. - cert. Authenticates an instance through a
TLS certificate. Specify the TLS identity as the IDENTKEY. A
valid value is any string up to 64 characters long in the common
name (CN) of the certificate. The meaning of a string depends on
its interpretation. - user. Authenticates by a user or
group name. A valid value is an alphanumeric string that can
contain some special characters and is from 4 to 32 characters
long.
access_to
body
string
The value that defines the access. The back end
grants or denies the access to it. A valid value is one of these
values: - ip. Authenticates an instance through its IP
address. A valid format is XX.XX.XX.XX or
XX.XX.XX.XX/XX. For example 0.0.0.0/0. - cert.
Authenticates an instance through a TLS certificate. Specify the
TLS identity as the IDENTKEY. A valid value is any string up to
64 characters long in the common name (CN) of the certificate.
The meaning of a string depends on its interpretation. -
user. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 32 characters long.
access_metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2016-12-31T13:14:15-05:00.
access_type
body
string
The access rule type. A valid value for the
share access rule type is one of the following values: - ip.
Authenticates an instance through its IP address. A valid format
is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example
0.0.0.0/0. - cert. Authenticates an instance through a
TLS certificate. Specify the TLS identity as the IDENTKEY. A
valid value is any string up to 64 characters long in the common
name (CN) of the certificate. The meaning of a string depends on
its interpretation. - user. Authenticates by a user or
group name. A valid value is an alphanumeric string that can
contain some special characters and is from 4 to 32 characters
long.
access_to
body
string
The value that defines the access. The back end
grants or denies the access to it. A valid value is one of these
values: - ip. Authenticates an instance through its IP
address. A valid format is XX.XX.XX.XX or
XX.XX.XX.XX/XX. For example 0.0.0.0/0. - cert.
Authenticates an instance through a TLS certificate. Specify the
TLS identity as the IDENTKEY. A valid value is any string up to
64 characters long in the common name (CN) of the certificate.
The meaning of a string depends on its interpretation. -
user. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 32 characters long.
access_key
body
string
The access credential of the entity granted share access.
New in version 2.21
access
body
object
The access object.
access_level
body
string
The access level to the share. To grant or deny
access to a share, you specify one of the following share access
levels: - rw. Read and write (RW) access. - ro. Read-
only (RO) access.
id
body
string
The access rule ID.
access_metadata
body
object
One or more access rule metadata key and value pairs as a
dictionary of strings.
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.
This API is deprecated starting with microversion 2.45 and requests to
this API will fail with a 404 starting from microversion 2.45. Use
List share access rules API
instead of this API from version 2.45.
Lists access rules for a share. The Access ID returned is necessary to deny
access.
The access rule type. A valid value for the
share access rule type is one of the following values: - ip.
Authenticates an instance through its IP address. A valid format
is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example
0.0.0.0/0. - cert. Authenticates an instance through a
TLS certificate. Specify the TLS identity as the IDENTKEY. A
valid value is any string up to 64 characters long in the common
name (CN) of the certificate. The meaning of a string depends on
its interpretation. - user. Authenticates by a user or
group name. A valid value is an alphanumeric string that can
contain some special characters and is from 4 to 32 characters
long.
access_key
body
string
The access credential of the entity granted share access.
New in version 2.21
access_to
body
string
The value that defines the access. The back end
grants or denies the access to it. A valid value is one of these
values: - ip. Authenticates an instance through its IP
address. A valid format is XX.XX.XX.XX or
XX.XX.XX.XX/XX. For example 0.0.0.0/0. - cert.
Authenticates an instance through a TLS certificate. Specify the
TLS identity as the IDENTKEY. A valid value is any string up to
64 characters long in the common name (CN) of the certificate.
The meaning of a string depends on its interpretation. -
user. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 32 characters long.
access_level
body
string
The access level to the share. To grant or deny
access to a share, you specify one of the following share access
levels: - rw. Read and write (RW) access. - ro. Read-
only (RO) access.
state
body
string
Prior to versions 2.28, the state of all access rules of a given share
is the same at all times. This could be new, active or
error. Since 2.28, the state of each access rule of a share is
independent of the others and can be queued_to_apply,
applying, active, error, queued_to_deny or denying.
A new rule starts out in queued_to_apply state and is successfully
applied if it transitions to active state.
access_list
body
string
The object of the access rule. To list access
rules, set this value to null.
id
body
string
The access rule ID.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The project ID of the user or service making the API request.
share_id
path
string
The UUID of the share.
force_delete
body
string
To force-delete a share or share group, set this value to
null. The force-delete action, unlike the delete action,
ignores the share or share group status.
Use the Shared File Systems service to make snapshots of shares. A share
snapshot is a point-in-time, read-only copy of the data that is
contained in a share. The APIs below allow controlling share snapshots. They
are represented by a “snapshot” resource in the Shared File Systems service,
and they can have user-defined metadata such as a name and description.
You can create, manage, update, and delete
share snapshots. After you create or manage a share snapshot, you
can create a share from it. You can also revert a share to its most
recent snapshot.
You can update a share snapshot to rename it, change its
description, or update its state to one of these supported states:
available
error
creating
deleting
error_deleting
manage_starting
manage_error
unmanage_starting
unmanage_error
restoring
As administrator, you can also reset the state of a snapshot and
force-delete a share snapshot in any state. Use the policy.json
file to grant permissions for these actions to other roles.
The project ID of the user or service making the API request.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list the requested resources for
all projects. Set to 1 to list resources for all projects.
Set to 0 to list resources only for the current project. Examples
of resources include shares, snapshots, share networks, security services
and share groups.
name~ (Optional)
query
string
The name pattern that can be used to filter shares,
share snapshots, share networks or share groups.
New in version 2.36
description~ (Optional)
query
string
The description pattern that can be used to filter shares,
share snapshots, share networks or share groups.
The project ID of the user or service making the API request.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list the requested resources for
all projects. Set to 1 to list resources for all projects.
Set to 0 to list resources only for the current project. Examples
of resources include shares, snapshots, share networks, security services
and share groups.
name~ (Optional)
query
string
The name pattern that can be used to filter shares,
share snapshots, share networks or share groups.
New in version 2.36
description~ (Optional)
query
string
The description pattern that can be used to filter shares,
share snapshots, share networks or share groups.
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
share_id
body
string
The UUID of the source share that was used to
create the snapshot.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The file system protocol of a share snapshot. A
valid value is NFS, CIFS, GlusterFS, HDFS,
CephFS or MAPRFS. CephFS is supported starting
with API v2.13.
{"snapshots":[{"status":"creating","share_id":"d94a8548-2079-4be0-b21c-0a887acd31ca","user_id":"5c7bdb6eb0504d54a619acf8375c08ce","name":"snapshot_My_share","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/086a1aa6-c425-4ecd-9612-391a3b1b9375","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/086a1aa6-c425-4ecd-9612-391a3b1b9375","rel":"bookmark"}],"created_at":"2015-09-07T11:55:09.000000","description":"Here is a snapshot of share My_share","share_proto":"NFS","share_size":1,"id":"086a1aa6-c425-4ecd-9612-391a3b1b9375","project_id":"cadd7139bc3148b8973df097c0911016","size":1},{"status":"available","share_id":"406ea93b-32e9-4907-a117-148b3945749f","user_id":"5c7bdb6eb0504d54a619acf8375c08ce","name":"snapshot_share1","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"bookmark"}],"created_at":"2015-09-07T11:50:39.000000","description":"Here is a snapshot of share Share1","share_proto":"NFS","share_size":1,"id":"6d221c1d-0200-461e-8d20-24b4776b9ddb","project_id":"cadd7139bc3148b8973df097c0911016","size":1}]}
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
share_id
body
string
The UUID of the source share that was used to
create the snapshot.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The file system protocol of a share snapshot. A
valid value is NFS, CIFS, GlusterFS, HDFS,
CephFS or MAPRFS. CephFS is supported starting
with API v2.13.
{"snapshot":{"status":"available","share_id":"406ea93b-32e9-4907-a117-148b3945749f","user_id":"5c7bdb6eb0504d54a619acf8375c08ce","name":"snapshot_share1","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"bookmark"}],"created_at":"2015-09-07T11:50:39.000000","description":"Here is a snapshot of share Share1","share_proto":"NFS","share_size":1,"id":"6d221c1d-0200-461e-8d20-24b4776b9ddb","project_id":"cadd7139bc3148b8973df097c0911016","size":1}}
The project ID of the user or service making the API request.
share_id
body
string
The UUID of the share from which to create a
snapshot.
force (Optional)
body
boolean
Indicates whether snapshot creation must be attempted
when a share’s status is not available. Set to true to force
snapshot creation when the share is busy performing other operations.
Default is false.
name (Optional)
body
string
The user defined name of the resource. The value of this field is
limited to 255 characters.
description (Optional)
body
string
The user defined description of the resource. The value of this field is
limited to 255 characters.
display_name (Optional)
body
string
The user defined name of the resource. This field sets the name
parameter.
display_description (Optional)
body
string
The user defined description of the resource. This field sets the
description parameter.
{"snapshot":{"share_id":"406ea93b-32e9-4907-a117-148b3945749f","force":"True","name":"snapshot_share1","description":"Here is a snapshot of share Share1"}}
The UUID of the source share that was used to
create the snapshot.
status
body
string
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The file system protocol of a share snapshot. A
valid value is NFS, CIFS, GlusterFS, HDFS,
CephFS or MAPRFS. CephFS is supported starting
with API v2.13.
{"snapshot":{"status":"creating","share_id":"406ea93b-32e9-4907-a117-148b3945749f","user_id":"5c7bdb6eb0504d54a619acf8375c08ce","name":"snapshot_share1","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"bookmark"}],"created_at":"2015-09-07T11:50:39.756808","description":"Here is a snapshot of share Share1","share_proto":"NFS","share_size":1,"id":"6d221c1d-0200-461e-8d20-24b4776b9ddb","project_id":"cadd7139bc3148b8973df097c0911016","size":1}}
POST
/v2/{project_id}/snapshots/manage
Manage share snapshot (since API v2.12)
New in version 2.12.
Configures Shared File Systems to manage a share snapshot.
Note
Managing snapshots of shares that are created on top of share servers
(i.e. created with share networks) is not supported prior to API version
2.49.
The project ID of the user or service making the API request.
share_id
body
string
The UUID of the share that has snapshot which
should be managed.
provider_location
body
string
Provider location of the snapshot on the backend.
name (Optional)
body
string
The user defined name of the resource. The value of this field is
limited to 255 characters.
display_name (Optional)
body
string
The user defined name of the resource. This field sets the name
parameter.
description (Optional)
body
string
The user defined description of the resource. The value of this field is
limited to 255 characters.
display_description (Optional)
body
string
The user defined description of the resource. This field sets the
description parameter.
driver_options (Optional)
body
object
A set of one or more key and value pairs, as a
dictionary of strings, that describe driver options. Details for
driver options should be taken from appropriate share driver
documentation.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The file system protocol of a share snapshot. A
valid value is NFS, CIFS, GlusterFS, HDFS,
CephFS or MAPRFS. CephFS is supported starting
with API v2.13.
The project ID of the user or service making the API request.
snapshot_id
path
string
The UUID of the snapshot.
status (Optional)
body
string
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
The project ID of the user or service making the API request.
snapshot_id
path
string
The UUID of the snapshot.
force_delete
body
string
To force-delete a snapshot, include this param and set its value to
null. The force-delete action, unlike the delete action,
ignores the snapshot status.
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
share_id
body
string
The UUID of the source share that was used to
create the snapshot.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The file system protocol of a share snapshot. A
valid value is NFS, CIFS, GlusterFS, HDFS,
CephFS or MAPRFS. CephFS is supported starting
with API v2.13.
{"snapshot":{"status":"available","share_id":"406ea93b-32e9-4907-a117-148b3945749f","name":"snapshot_Share1","user_id":"5c7bdb6eb0504d54a619acf8375c08ce","project_id":"cadd7139bc3148b8973df097c0911016","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"bookmark"}],"created_at":"2015-09-07T11:50:39.000000","description":"I am changing a description also. Here is a snapshot of share Share1","share_proto":"NFS","share_size":1,"id":"6d221c1d-0200-461e-8d20-24b4776b9ddb","size":1}}
A share snapshot instance is an internal representation for a snapshot
of a share. A single snapshot can have multiple snapshot instances if
the parent share has multiple instances. When a share is replicated
or is in the process of being migrated, it can live in multiple places
and each individual location is called an “instance”, internally within
the Shared File Systems service.
By default administrators can list, show information for and explicitly
set the state of share snapshot instances. Use the policy.json file
to grant permissions for these actions to other roles.
The snapshot instance status. A valid value is
available, error, creating, deleting, and
error_deleting, restoring, unmanage_starting,
unmanage_error, manage_starting, manage_error.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2016-12-31T13:14:15-05:00.
status
body
string
The snapshot instance status. A valid value is
available, error, creating, deleting, and
error_deleting, restoring, unmanage_starting,
unmanage_error, manage_starting, manage_error.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2016-12-31T13:14:15-05:00.
status
body
string
The snapshot instance status. A valid value is
available, error, creating, deleting, and
error_deleting, restoring, unmanage_starting,
unmanage_error, manage_starting, manage_error.
The project ID of the user or service making the API request.
snapshot_instance_id
path
string
The UUID of the share snapshot instance.
status
body
string
The snapshot instance status. A valid value is
available, error, creating, deleting, and
error_deleting, restoring, unmanage_starting,
unmanage_error, manage_starting, manage_error.
A share network resource stores network information to create and manage
share servers. Shares created with share networks are exported on these
networks with the help of share servers.
You can create, update, view, and delete a share network.
When you create a share network, you may optionally specify an associated
neutron network and subnetwork.
For more information about supported plug-ins for share networks,
see Manila Network Plugins.
A share network resource has these attributes:
The IP block in Classless Inter-Domain Routing (CIDR) notation
from which to allocate the network.
The IP version of the network.
The network type, which is vlan, vxlan, gre, or
flat.
If the network uses segmentation, a segmentation identifier. For
example, VLAN, VXLAN, and GRE networks use segmentation.
A share network resource can also have a user defined name and description.
The project ID of the user or service making the API request.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list the requested resources for
all projects. Set to 1 to list resources for all projects.
Set to 0 to list resources only for the current project. Examples
of resources include shares, snapshots, share networks, security services
and share groups.
name~ (Optional)
query
string
The name pattern that can be used to filter shares,
share snapshots, share networks or share groups.
New in version 2.36
description~ (Optional)
query
string
The description pattern that can be used to filter shares,
share snapshots, share networks or share groups.
The project ID of the user or service making the API request.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list the requested resources for
all projects. Set to 1 to list resources for all projects.
Set to 0 to list resources only for the current project. Examples
of resources include shares, snapshots, share networks, security services
and share groups.
name~ (Optional)
query
string
The name pattern that can be used to filter shares,
share snapshots, share networks or share groups.
New in version 2.36
description~ (Optional)
query
string
The description pattern that can be used to filter shares,
share snapshots, share networks or share groups.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The project ID of the user or service making the API request.
neutron_net_id (Optional)
body
string
The UUID of a neutron network when setting up or updating a share
network with neutron. Specify both a neutron network and a neutron
subnet that belongs to that neutron network.
neutron_subnet_id (Optional)
body
string
The UUID of the neutron subnet when setting up or updating a share
network with neutron. Specify both a neutron network and a neutron
subnet that belongs to that neutron network.
name (Optional)
body
string
The user defined name of the resource. The value of this field is
limited to 255 characters.
description (Optional)
body
string
The user defined description of the resource. The value of this field is
limited to 255 characters.
{"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"}}
The network type. A valid value is VLAN,
VXLAN, GRE, or flat. This parameter is automatically
set to a value determined by the network provider.
segmentation_id
body
integer
The segmentation ID. This parameter is
automatically set to a value determined by the network provider.
For VLAN, this value is an integer from 1 to 4094. For VXLAN,
this value is an integer from 1 to 16777215. For GRE, this value
is an integer from 1 to 4294967295.
cidr
body
string
The IP block from which to allocate the network,
in CIDR notation. For example, 172.16.0.0/24 or
2001:DB8::/64. This parameter is automatically set to a value
determined by the network provider.
ip_version
body
integer
The IP version of the network. A valid value is
4 or 6. This parameter is automatically set to a value
determined by the network provider.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
{"share_network":{"name":"my_network","segmentation_id":null,"created_at":"2015-09-07T14:37:00.583656","neutron_subnet_id":"53482b62-2c84-4a53-b6ab-30d9d9800d06","updated_at":null,"id":"77eb3421-4549-4789-ac39-0d5185d68c29","neutron_net_id":"998b42ee-2cee-4d36-8b95-67b5ca1f2109","ip_version":null,"cidr":null,"project_id":"e10a683c20da41248cfd5e1ab3d88c62","network_type":null,"description":"This is my share network","gateway":null,"mtu":null}}
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The project ID of the user or service making the API request.
share_network_id
path
string
The UUID of the share network.
name (Optional)
body
string
The user defined name of the resource. The value of this field is
limited to 255 characters.
description (Optional)
body
string
The user defined description of the resource. The value of this field is
limited to 255 characters.
neutron_net_id (Optional)
body
string
The UUID of a neutron network when setting up or updating a share
network with neutron. Specify both a neutron network and a neutron
subnet that belongs to that neutron network.
neutron_subnet_id (Optional)
body
string
The UUID of the neutron subnet when setting up or updating a share
network with neutron. Specify both a neutron network and a neutron
subnet that belongs to that neutron network.
{"share_network":{"neutron_net_id":"998b42ee-2cee-4d36-8b95-67b5ca1f2109","neutron_subnet_id":"53482b62-2c84-4a53-b6ab-30d9d9800d06","name":"update my network","description":"i'm adding a description"}}
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
{"share_network":{"name":"net_my","segmentation_id":null,"created_at":"2015-09-04T14:54:25.000000","neutron_subnet_id":"53482b62-2c84-4a53-b6ab-30d9d9800d06","updated_at":"2015-09-07T08:02:53.512184","id":"713df749-aac0-4a54-af52-10f6c991e80c","neutron_net_id":"998b42ee-2cee-4d36-8b95-67b5ca1f2109","ip_version":"4","cidr":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","network_type":null,"description":"i'm adding a description","gateway":null,"mtu":null}}
You can create, update, view, and delete security services. A
security service resource represents configuration information for clients for
authentication and authorization (AuthN/AuthZ). For example, a
share server will be the client for an existing security service such as
LDAP, Kerberos, or Microsoft Active Directory.
The Shared File Systems service supports three security service types:
ldap. LDAP.
kerberos. Kerberos.
active_directory. Microsoft Active Directory.
You can configure a security service with these options:
A DNS IP address. Some drivers may allow a comma separated list of multiple
addresses, e.g. NetApp ONTAP.
An IP address or host name.
A domain.
An ou, the organizational unit. (available starting with API version 2.44)
A user or group name.
The password for the user, if you specify a user name.
A security service resource can also be given a user defined name and
description.
The project ID of the user or service making the API request.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list the requested resources for
all projects. Set to 1 to list resources for all projects.
Set to 0 to list resources only for the current project. Examples
of resources include shares, snapshots, share networks, security services
and share groups.
The project ID of the user or service making the API request.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list the requested resources for
all projects. Set to 1 to list resources for all projects.
Set to 0 to list resources only for the current project. Examples
of resources include shares, snapshots, share networks, security services
and share groups.
The security service type. A valid value is
ldap, kerberos, or active_directory.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
dns_ip
body
string
The DNS IP address that is used inside the project network.
user
body
string
The security service user or group name that is used by the project.
password
body
string
The user password, if you specify a user.
domain
body
string
The security service domain.
ou
body
string
The security service ou.
New in version 2.44
server
body
string
The security service host name or IP address.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
{"security_services":[{"status":"new","domain":null,"ou":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ1","created_at":"2015-09-07T12:19:10.000000","description":"Creating my first Security Service","updated_at":null,"server":null,"dns_ip":"10.0.0.0/24","user":"demo","password":"supersecret","type":"kerberos","id":"3c829734-0679-4c17-9637-801da48c0d5f","share_networks":[]},{"status":"new","domain":null,"ou":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ2","created_at":"2015-09-07T12:25:03.000000","description":"Creating my second Security Service","updated_at":null,"server":null,"dns_ip":"10.0.0.0/24","user":null,"password":null,"type":"ldap","id":"5a1d3a12-34a7-4087-8983-50e9ed03509a","share_networks":[]}]}
The security service type. A valid value is
ldap, kerberos, or active_directory.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
dns_ip
body
string
The DNS IP address that is used inside the project network.
user
body
string
The security service user or group name that is used by the project.
password
body
string
The user password, if you specify a user.
domain
body
string
The security service domain.
ou
body
string
The security service ou.
New in version 2.44
server
body
string
The security service host name or IP address.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
{"security_service":{"status":"new","domain":null,"ou":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ1","created_at":"2015-09-07T12:19:10.000000","updated_at":null,"server":null,"dns_ip":"10.0.0.0/24","user":"demo","password":"supersecret","type":"kerberos","id":"3c829734-0679-4c17-9637-801da48c0d5f","description":"Creating my first Security Service"}}
{"security_service":{"description":"Creating my first Security Service","dns_ip":"10.0.0.0/24","user":"demo","password":"***","type":"kerberos","name":"SecServ1"}}
The security service type. A valid value is
ldap, kerberos, or active_directory.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
dns_ip
body
string
The DNS IP address that is used inside the project network.
user
body
string
The security service user or group name that is used by the project.
password
body
string
The user password, if you specify a user.
domain
body
string
The security service domain.
ou
body
string
The security service ou.
New in version 2.44
server
body
string
The security service host name or IP address.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
{"security_service":{"status":"new","domain":null,"ou":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ1","created_at":"2015-09-07T12:19:10.695211","updated_at":null,"server":null,"dns_ip":"10.0.0.0/24","user":"demo","password":"supersecret","type":"kerberos","id":"3c829734-0679-4c17-9637-801da48c0d5f","description":"Creating my first Security Service"}}
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.
The security service type. A valid value is
ldap, kerberos, or active_directory.
name
body
string
The user defined name of the resource.
description
body
string
The user defined description of the resource.
dns_ip
body
string
The DNS IP address that is used inside the project network.
user
body
string
The security service user or group name that is used by the project.
password
body
string
The user password, if you specify a user.
domain
body
string
The security service domain.
ou
body
string
The security service ou.
New in version 2.44
server
body
string
The security service host name or IP address.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
{"security_service":{"status":"new","domain":"my_domain","ou":"CN=Computers","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ1","created_at":"2015-09-07T12:19:10.000000","updated_at":"2015-09-07T12:47:21.858737","server":null,"dns_ip":"10.0.0.0/24","user":"new_user","password":"pass","type":"kerberos","id":"3c829734-0679-4c17-9637-801da48c0d5f","description":"Adding a description"}}
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.
The share server status, which is active,
error, creating, or deleting.
share_network_id
body
string
The share network ID.
share_network_name
body
string
The name of a share network that is associated
with the share server.
host
body
string
The share server host name or IP address.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The share server status, which is active,
error, creating, or deleting.
backend_details
body
object
The back-end details for a server. Each back end
can store any key- value information that it requires. For
example, the generic back- end driver might store the router ID.
share_network_id
body
string
The UUID of a share network that is associated
with the share server.
share_network_name
body
string
The name of a share network that is associated
with the share server.
host
body
string
The share server host name or IP address.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2016-12-31T13:14:15-05:00.
identifier
body
string
The identifier of the share server in the back-end storage system.
New in version 2.49
is_auto_deletable
body
boolean
Defines if a share server can be deleted automatically by the service.
Share server deletion can be automated with configuration. However, Share
servers that have ever had a share removed from service management cannot
be automatically deleted by the service.
Response parameters can differ based on the back end used.
Each back end can store any key-value information that it requires.
For example, the generic back end driver might store the router ID.
The project ID of the user or service making the API request.
host
body
string
The host of the destination back end, in this format: host@backend.
- host. The host name for the destination back end.
- backend. The name of the destination back end.
identifier
body
string
The identifier of the share server in the back-end storage system.
share_network
body
string
The share network ID.
driver_options (Optional)
body
object
A set of one or more key and value pairs, as a
dictionary of strings, that describe driver options. Details for
driver options should be taken from appropriate share driver
documentation.
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2016-12-31T13:14:15-05:00.
status
body
string
The share server status, which can be active,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
host
body
string
The host of the destination back end, in this format: host@backend.
- host. The host name for the destination back end.
- backend. The name of the destination back end.
share_network_name
body
string
The name of a share network that is associated
with the share server.
share_network_id
body
string
The share network ID.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
backend_details
body
object
The back-end details for a server. Each back end
can store any key- value information that it requires. For
example, the generic back- end driver might store the router ID.
is_auto_deletable
body
boolean
Defines if a share server can be deleted automatically by the service.
Share server deletion can be automated with configuration. However, Share
servers that have ever had a share removed from service management cannot
be automatically deleted by the service.
identifier
body
string
The identifier of the share server in the back-end storage system.
An administrator can remove a share server from the Shared File System
service’s management if there are no associated shares that the service is
aware of. The share server will not be torn down in the back end.
Preconditions
Share server status must be either error, manage_error, active or
unmanage_error.
The project ID of the user or service making the API request.
share_server_id
body
string
The UUID of the share server.
force (Optional)
body
boolean
Indicates whether to permit or deny the force-
update of a quota that is already used and the requested value
exceeds the configured quota. Set to True to permit the
force-update of the quota. Set to False to deny the force-
update of the quota.
unmanage
body
object
To unmanage a share server, either set this value to null or {}.
Optionally, the force attribute can be included in this object.
The project ID of the user or service making the API request.
share_server_id
body
string
The UUID of the share server.
status
body
string
The share server status, which can be active,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
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.
The share instance status. A valid value is
available, error, creating, deleting,
creating_from_snapshot, or 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.
progress
body
string
The progress of the share creation.
New in version 2.54
availability_zone
body
string
The availability zone.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Available until version 2.8
cast_rules_to_readonly
body
string
If the share instance has its cast_rules_to_readonly attribute set to
True, all existing access rules will be cast to read/only.
The share instance status. A valid value is
available, error, creating, deleting,
creating_from_snapshot, or 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.
progress
body
string
The progress of the share creation.
New in version 2.54
availability_zone
body
string
The availability zone.
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Available until version 2.8
cast_rules_to_readonly
body
string
If the share instance has its cast_rules_to_readonly attribute set to
True, all existing access rules will be cast to read/only.
The UUID of the share instance that this
export location belongs to. This parameter is only available to users
with an “administrator” role, and cannot be controlled via policy.json.
path
body
string
The export location path that should be used for mount operation.
is_admin_only
body
boolean
Defines purpose of an export location. If set to
true, then it is expected to be used for service needs and by
administrators only. If it is set to false, then this export
location can be used by end users. This parameter is only available to
users with an “administrator” role, and cannot be controlled via policy
.json.
preferred
body
boolean
Drivers may use this field to identify which export locations
are most efficient and should be used preferentially by clients.
By default it is set to false value.
The UUID of the share instance that this
export location belongs to. This parameter is only available to users
with an “administrator” role, and cannot be controlled via policy.json.
path
body
string
The export location path that should be used for mount operation.
is_admin_only
body
boolean
Defines purpose of an export location. If set to
true, then it is expected to be used for service needs and by
administrators only. If it is set to false, then this export
location can be used by end users. This parameter is only available to
users with an “administrator” role, and cannot be controlled via policy
.json.
preferred
body
boolean
Drivers may use this field to identify which export locations
are most efficient and should be used preferentially by clients.
By default it is set to false value.
New in version 2.14
created_at
body
string
The date and time stamp when the resource was created within the service’s
database.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
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.
The project ID of the user or service making the API request.
extra_specs (Optional)
query
string
The extra specifications as a set of one or more
key-value pairs. In each pair, the key is the name of the extra
specification and the value is the share type that was used to
filter search share type list.
The required extra specifications for the share
type.
extra_specs
body
object
The extra specifications for the share type.
driver_handles_share_servers
body
boolean
An extra specification that defines the driver
mode for share server, or storage, life cycle management. The
Shared File Systems service creates a share server for the export
of shares. This value is true when the share driver manages,
or handles, the share server life cycle. This value is false
when an administrator rather than a share driver manages the
storage life cycle.
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
snapshot_support (Optional)
body
boolean
An extra specification that filters back ends by
whether they do or do not support share snapshots.
mount_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends
by their capability to mount share snapshots.
New in version 2.32
revert_to_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by their
capability to revert shares to snapshots.
New in version 2.27
share_type_access:is_public (Optional)
body
boolean
Indicates whether a share type is publicly
accessible. Default is true, or publicly accessible.
New in version 2.7
create_share_from_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by
their capability to create shares from snapshots.
New in version 2.24
description
body
string
The description of the share type.
New in version 2.41
is_default
body
boolean
Defines the share type created is default or not. If the returning
value is true, then it is the default share type, otherwise, it is
not default.
{"volume_types":[{"required_extra_specs":{"driver_handles_share_servers":"True"},"share_type_access:is_public":true,"extra_specs":{"driver_handles_share_servers":"True"},"id":"420e6a31-3f3d-4ed7-9d11-59450372182a","name":"default","is_default":true,"description":"share type description"},{"required_extra_specs":{"driver_handles_share_servers":"True"},"share_type_access:is_public":true,"extra_specs":{"replication_type":"readable","driver_handles_share_servers":"True","mount_snapshot_support":"False","revert_to_snapshot_support":"False","create_share_from_snapshot_support":"True","snapshot_support":"True"},"id":"7fa1342b-de9d-4d89-bdc8-af67795c0e52","name":"testing","is_default":false,"description":"share type description"}],"share_types":[{"required_extra_specs":{"driver_handles_share_servers":"True"},"share_type_access:is_public":true,"extra_specs":{"driver_handles_share_servers":"True"},"id":"420e6a31-3f3d-4ed7-9d11-59450372182a","name":"default","is_default":true,"description":"share type description"},{"required_extra_specs":{"driver_handles_share_servers":"True"},"share_type_access:is_public":true,"extra_specs":{"replication_type":"readable","driver_handles_share_servers":"True","mount_snapshot_support":"False","revert_to_snapshot_support":"False","create_share_from_snapshot_support":"True","snapshot_support":"True"},"id":"7fa1342b-de9d-4d89-bdc8-af67795c0e52","name":"testing","is_default":false,"description":"share type description"}]}
The required extra specifications for the share
type.
extra_specs
body
object
The extra specifications for the share type.
driver_handles_share_servers
body
boolean
An extra specification that defines the driver
mode for share server, or storage, life cycle management. The
Shared File Systems service creates a share server for the export
of shares. This value is true when the share driver manages,
or handles, the share server life cycle. This value is false
when an administrator rather than a share driver manages the
storage life cycle.
snapshot_support (Optional)
body
boolean
An extra specification that filters back ends by
whether they do or do not support share snapshots.
share_type_access:is_public (Optional)
body
boolean
Indicates whether a share type is publicly
accessible. Default is true, or publicly accessible.
New in version 2.7
name
body
string
Name of the share type.
description
body
string
The description of the share type.
New in version 2.41
is_default
body
boolean
Defines the share type created is default or not. If the returning
value is true, then it is the default share type, otherwise, it is
not default.
{"share_type":{"required_extra_specs":{"driver_handles_share_servers":"True"},"share_type_access:is_public":true,"extra_specs":{"driver_handles_share_servers":"True"},"id":"420e6a31-3f3d-4ed7-9d11-59450372182a","name":"default","is_default":true,"description":"share type description"},"volume_type":{"required_extra_specs":{"driver_handles_share_servers":"True"},"share_type_access:is_public":true,"extra_specs":{"driver_handles_share_servers":"True"},"id":"420e6a31-3f3d-4ed7-9d11-59450372182a","name":"default","is_default":true,"description":"share type description"}}
The required extra specifications for the share
type.
extra_specs
body
object
The extra specifications for the share type.
driver_handles_share_servers
body
boolean
An extra specification that defines the driver
mode for share server, or storage, life cycle management. The
Shared File Systems service creates a share server for the export
of shares. This value is true when the share driver manages,
or handles, the share server life cycle. This value is false
when an administrator rather than a share driver manages the
storage life cycle.
snapshot_support (Optional)
body
boolean
An extra specification that filters back ends by
whether they do or do not support share snapshots.
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
mount_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends
by their capability to mount share snapshots.
New in version 2.32
revert_to_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by their
capability to revert shares to snapshots.
New in version 2.27
create_share_from_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by
their capability to create shares from snapshots.
New in version 2.24
share_type_access:is_public (Optional)
body
boolean
Indicates whether a share type is publicly
accessible. Default is true, or publicly accessible.
New in version 2.7
name
body
string
Name of the share type.
description
body
string
The description of the share type.
New in version 2.41
is_default
body
boolean
Defines the share type created is default or not. If the returning
value is true, then it is the default share type, otherwise, it is
not default.
An extra specification that defines the driver
mode for share server, or storage, life cycle management. The
Shared File Systems service creates a share server for the export
of shares. This value is true when the share driver manages,
or handles, the share server life cycle. This value is false
when an administrator rather than a share driver manages the
storage life cycle.
snapshot_support (Optional)
body
boolean
An extra specification that filters back ends by
whether they do or do not support share snapshots.
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
mount_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends
by their capability to mount share snapshots.
New in version 2.32
revert_to_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by their
capability to revert shares to snapshots.
New in version 2.27
create_share_from_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by
their capability to create shares from snapshots.
The project ID of the user or service making the API request.
extra_specs
body
object
The extra specifications for the share type.
driver_handles_share_servers
body
boolean
An extra specification that defines the driver
mode for share server, or storage, life cycle management. The
Shared File Systems service creates a share server for the export
of shares. This value is true when the share driver manages,
or handles, the share server life cycle. This value is false
when an administrator rather than a share driver manages the
storage life cycle.
snapshot_support (Optional)
body
boolean
An extra specification that filters back ends by
whether they do or do not support share snapshots.
os-share-type-access:is_public (Optional)
body
boolean
Indicates whether a share type is publicly
accessible. Default is true, or publicly accessible.
Available until version 2.6
name (Optional)
body
string
Name of the share type. The value of this field is limited to 255
characters.
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
mount_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends
by their capability to mount share snapshots.
New in version 2.32
revert_to_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by their
capability to revert shares to snapshots.
New in version 2.27
create_share_from_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by
their capability to create shares from snapshots.
New in version 2.24
description (Optional)
body
string
The description of the share type. The value of this field is limited to
255 characters.
{"share_type":{"extra_specs":{"replication_type":"readable","driver_handles_share_servers":true,"mount_snapshot_support":false,"revert_to_snapshot_support":false,"create_share_from_snapshot_support":true,"snapshot_support":true},"share_type_access:is_public":true,"name":"testing","description":"share type description"}}
The required extra specifications for the share
type.
extra_specs
body
object
The extra specifications for the share type.
driver_handles_share_servers
body
boolean
An extra specification that defines the driver
mode for share server, or storage, life cycle management. The
Shared File Systems service creates a share server for the export
of shares. This value is true when the share driver manages,
or handles, the share server life cycle. This value is false
when an administrator rather than a share driver manages the
storage life cycle.
snapshot_support (Optional)
body
boolean
An extra specification that filters back ends by
whether they do or do not support share snapshots.
os-share-type-access:is_public (Optional)
body
boolean
Indicates whether a share type is publicly
accessible. Default is true, or publicly accessible.
Available until version 2.6
share_type_access:is_public (Optional)
body
boolean
Indicates whether a share type is publicly
accessible. Default is true, or publicly accessible.
New in version 2.7
name
body
string
Name of the share type.
replication_type (Optional)
body
string
The share replication type.
New in version 2.11
mount_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends
by their capability to mount share snapshots.
New in version 2.32
revert_to_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by their
capability to revert shares to snapshots.
New in version 2.27
create_share_from_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by
their capability to create shares from snapshots.
New in version 2.24
description
body
string
The description of the share type.
New in version 2.41
is_default
body
boolean
Defines the share type created is default or not. If the returning
value is true, then it is the default share type, otherwise, it is
not default.
{"share_type":{"required_extra_specs":{"driver_handles_share_servers":true},"share_type_access:is_public":true,"extra_specs":{"replication_type":"readable","driver_handles_share_servers":"True","mount_snapshot_support":"False","revert_to_snapshot_support":"False","create_share_from_snapshot_support":"True","snapshot_support":"True"},"id":"7fa1342b-de9d-4d89-bdc8-af67795c0e52","name":"testing","is_default":false,"description":"share type description"},"volume_type":{"required_extra_specs":{"driver_handles_share_servers":true},"share_type_access:is_public":true,"extra_specs":{"replication_type":"readable","driver_handles_share_servers":"True","mount_snapshot_support":"False","revert_to_snapshot_support":"False","create_share_from_snapshot_support":"True","snapshot_support":"True"},"id":"7fa1342b-de9d-4d89-bdc8-af67795c0e52","name":"testing","is_default":false,"description":"share type description"}}
Each driver implementation determines which extra specification
keys it uses. For details, see Capabilities and Extra-Specs and documentation for your driver.
The project ID of the user or service making the API request.
share_type_id
path
string
The UUID of the share type.
name (Optional)
body
string
Name of the share type. The value of this field is limited to 255
characters.
share_type_access:is_public (Optional)
body
boolean
Indicates whether the share type should be accessible by all projects
(tenants) in the cloud. If not specified, the visibility of the share
type is not altered.
The required extra specifications for the share
type.
extra_specs
body
object
The extra specifications for the share type.
driver_handles_share_servers
body
boolean
An extra specification that defines the driver
mode for share server, or storage, life cycle management. The
Shared File Systems service creates a share server for the export
of shares. This value is true when the share driver manages,
or handles, the share server life cycle. This value is false
when an administrator rather than a share driver manages the
storage life cycle.
snapshot_support (Optional)
body
boolean
An extra specification that filters back ends by
whether they do or do not support share snapshots.
share_type_access:is_public
body
boolean
Indicates whether a share type is accessible by all projects (tenants)
in the cloud.
name
body
string
Name of the share type.
replication_type (Optional)
body
string
The share replication type.
mount_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends
by their capability to mount share snapshots.
revert_to_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by their
capability to revert shares to snapshots.
create_share_from_snapshot_support (Optional)
body
boolean
Boolean extra spec used for filtering of back ends by
their capability to create shares from snapshots.
description
body
string
The description of the share type.
is_default
body
boolean
Defines the share type created is default or not. If the returning
value is true, then it is the default share type, otherwise, it is
not default.
{"share_type":{"required_extra_specs":{"driver_handles_share_servers":true},"share_type_access:is_public":true,"extra_specs":{"replication_type":"readable","driver_handles_share_servers":"True","mount_snapshot_support":"False","revert_to_snapshot_support":"False","create_share_from_snapshot_support":"True","snapshot_support":"True"},"id":"7fa1342b-de9d-4d89-bdc8-af67795c0e52","name":"testing","is_default":false,"description":"share type description"},"volume_type":{"required_extra_specs":{"driver_handles_share_servers":true},"share_type_access:is_public":true,"extra_specs":{"replication_type":"readable","driver_handles_share_servers":"True","mount_snapshot_support":"False","revert_to_snapshot_support":"False","create_share_from_snapshot_support":"True","snapshot_support":"True"},"id":"7fa1342b-de9d-4d89-bdc8-af67795c0e52","name":"testing","is_default":false,"description":"share type description"}}
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.
The pools for the back end. This value is either
null or a string value that indicates the capabilities for
each pool. For example, pool_name, total_capacity_gb,
qos, and so on.
name
body
string
The name of the back end in this format:
host@backend#POOL. - host. The host name for the back
end. - backend. The name of the back end. - POOL. The
pool name for the back end.
backend
body
string
The name of the back end.
pool
body
string
The pool name for the back end.
host
body
string
The host name for the back end.
capabilities
body
object
The back end capabilities which include qos, total_capacity_gb,
etc.
qos
body
boolean
The quality of service (QoS) support.
timestamp
body
string
The date and time stamp when the API request was issued.
The ±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.
The service binary name. Default is the base name
of the executable.
zone
body
string
The service availability zone.
host
body
string
The service host name.
state
body
string
The current state of the service. A valid value
is up or down.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
Allows bringing shared file systems under service management.
POST
/v2/{project_id}/os-share-manage
Manage share (DEPRECATED)
Warning
This API is deprecated starting with microversion 2.7 and requests to
this API will fail with a 404 starting from microversion 2.7. Use
Share Manage API instead of this API
from version 2.7.
Use this API to bring a share under the management of the Shared File
Systems service. In the service, the share will be represented as a resource
in the database. It can have a user defined name and description.
Administrator only. Use the policy.json file to grant permissions for this
action to other roles.
The project ID of the user or service making the API request.
share
body
object
A share object.
protocol
body
string
The Shared File Systems protocol of the share to
manage. A valid value is NFS, CIFS, GlusterFS,
CEPHFS, HDFS or MAPRFS.
name (Optional)
body
string
The user defined name of the resource. The value of this field is
limited to 255 characters.
display_name (Optional)
body
string
The user defined name of the resource. This field sets the name
parameter.
share_type (Optional)
body
string
The share type name.
driver_options (Optional)
body
object
A set of one or more key and value pairs, as a
dictionary of strings, that describe driver options. Details for
driver options should be taken from appropriate share driver
documentation.
export_path
body
string
The share export path in the format appropriate
for the protocol: - NFS protocol. 10.0.0.1:/foo_path. For
example, 10.254.0.5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5. - CIFS protocol.
\\10.0.0.1\foo_name_of_cifs_share.
service_host
body
string
The manage-share service host in this format:
host@backend#POOL. - host. The host name for the back
end. - backend. The name of the back end. - POOL. The
pool name for the back end.
is_public (Optional)
body
boolean
The level of visibility for the share. Set to true to make
share public. Set to false to make it private. Default value
is false.
New in version 2.8
description (Optional)
body
string
The user defined description of the resource. The value of this field is
limited to 255 characters.
display_description (Optional)
body
string
The user defined description of the resource. This field sets the
description parameter.
{"share":{"protocol":"nfs","name":"accounting_p8787","share_type":"gold","driver_options":{"opt1":"opt1","opt2":"opt2"},"export_path":"192.162.10.6:/shares/share-accounting_p8787","service_host":"manila2@openstackstor01#accountingpool","is_public":true,"description":"Common storage for spreadsheets and presentations. Please contact John Accessman to be added to the users of this drive.","share_server_id":"00137b40-ca06-4ae8-83a3-2c5989eebcce"}}
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Available until version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id
body
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
The UUID of the share type. In minor versions, this parameter is
a share type name, as a string.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, CephFS,
MAPRFS, CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
This API is deprecated starting with microversion 2.7 and requests to
this API will fail with a 404 starting from microversion 2.7. Use
Share Unmanage API instead of this
API from version 2.7.
Use this API to remove a share from the management of the Shared File
Systems service without deleting the share.
Administrator only. Use the policy.json file to grant permissions for this
action to other roles.
Preconditions:
This API does not support unmanaging shares that are created on top
of share servers (i.e. created with share networks).
You should remove any snapshots and share replicas before attempting to
unmanage a share.
The project ID of the user or service making the API request.
project_id
path
string
The ID of the project whose quotas must be acted upon by the API.
This ID can be different from the first project ID in the URI.
For example, in a multi-tenant cloud, the first ID in the URI is
typically the project ID of a privileged user (such as a cloud
administrator) that can create, query or delete quotas of other projects
in the cloud.
If you specify the optional user_id query parameter, you get
the quotas for this user in the project. If you omit this parameter,
you get the quotas for the project.
The project ID of the user or service making the API request.
project_id
path
string
The ID of the project whose quotas must be acted upon by the API.
This ID can be different from the first project ID in the URI.
For example, in a multi-tenant cloud, the first ID in the URI is
typically the project ID of a privileged user (such as a cloud
administrator) that can create, query or delete quotas of other projects
in the cloud.
user_id (Optional)
query
string
The ID of the user. If you specify this query parameter, you update the
quotas for this user in the project. If you omit this parameter, you
update the quotas for the whole project.
share_type (Optional)
path
string
The name or UUID of the share type. If you specify this
parameter in the URI, you show, update, or delete quotas
for this share type.
If you specify the optional user_id query parameter, you get
the quotas for this user in the project. If you omit this parameter,
you get the quotas for the project.
The project ID of the user or service making the API request.
project_id
path
string
The ID of the project whose quotas must be acted upon by the API.
This ID can be different from the first project ID in the URI.
For example, in a multi-tenant cloud, the first ID in the URI is
typically the project ID of a privileged user (such as a cloud
administrator) that can create, query or delete quotas of other projects
in the cloud.
user_id (Optional)
query
string
The ID of the user. If you specify this query parameter, you update the
quotas for this user in the project. If you omit this parameter, you
update the quotas for the whole project.
share_type (Optional)
path
string
The name or UUID of the share type. If you specify this
parameter in the URI, you show, update, or delete quotas
for this share type.
If you specify the optional user_id query parameter, you update
the quotas for this user in the project. If you omit this parameter,
you update the quotas for the project.
The project ID of the user or service making the API request.
project_id
path
string
The ID of the project whose quotas must be acted upon by the API.
This ID can be different from the first project ID in the URI.
For example, in a multi-tenant cloud, the first ID in the URI is
typically the project ID of a privileged user (such as a cloud
administrator) that can create, query or delete quotas of other projects
in the cloud.
user_id (Optional)
query
string
The ID of the user. If you specify this query parameter, you update the
quotas for this user in the project. If you omit this parameter, you
update the quotas for the whole project.
quota_set
body
object
The quota_set object.
force (Optional)
body
boolean
Indicates whether to permit or deny the force-
update of a quota that is already used and the requested value
exceeds the configured quota. Set to True to permit the
force-update of the quota. Set to False to deny the force-
update of the quota.
gigabytes (Optional)
body
integer
The number of gigabytes for the project.
snapshots (Optional)
body
integer
The number of snapshots for the project.
snapshot_gigabytes (Optional)
body
integer
The number of gigabytes for the snapshots for the
project.
shares (Optional)
body
integer
The number of shares for the project.
share_networks (Optional)
body
integer
The number of share networks for the project.
share_groups (Optional)
body
integer
The number of share groups allowed for each project or user.
New in version 2.40
share_group_snapshots (Optional)
body
integer
The number of share group snapshots allowed for each project or user.
New in version 2.40
share_type (Optional)
path
string
The name or UUID of the share type. If you specify this
parameter in the URI, you show, update, or delete quotas
for this share type.
New in version 2.39
share_replicas (Optional)
body
integer
The number of share replicas allowed for each project or user.
New in version 2.53
replica_gigabytes (Optional)
body
integer
The number of gigabytes for share replicas for the project.
Deletes quotas for a project. The quota reverts to the default quota.
If you specify the optional user_id query parameter, you delete
the quotas for this user in the project. If you omit this parameter,
you delete the quotas for the project.
The project ID of the user or service making the API request.
project_id
path
string
The ID of the project whose quotas must be acted upon by the API.
This ID can be different from the first project ID in the URI.
For example, in a multi-tenant cloud, the first ID in the URI is
typically the project ID of a privileged user (such as a cloud
administrator) that can create, query or delete quotas of other projects
in the cloud.
user_id (Optional)
query
string
The ID of the user. If you specify this query parameter, you update the
quotas for this user in the project. If you omit this parameter, you
update the quotas for the whole project.
share_type (Optional)
path
string
The name or UUID of the share type. If you specify this
parameter in the URI, you show, update, or delete quotas
for this share type.
The total maximum number of share gigabytes that
are allowed in a project. You cannot request a share that exceeds
the allowed gigabytes quota.
share_group_snapshots
body
integer
The maximum number of share group snapshots.
New in version 2.40
snapshots
body
integer
The total maximum number of share snapshots that
are allowed in a project.
snapshot_gigabytes
body
integer
The total maximum number of snapshot gigabytes
that are allowed in a project.
shares
body
integer
The total maximum number of shares that are
allowed in a project.
id
body
string
A quota_class_set id.
share_networks
body
integer
The total maximum number of share-networks that
are allowed in a project.
share_replicas
body
integer
The maximum number of share replicas that is allowed.
New in version 2.53
replica_gigabytes
body
integer
The maximum number of replica gigabytes that are allowed in a project.
You cannot create a share, share replica, manage a share or extend a
share if it is going to exceed the allowed replica gigabytes quota.
The project ID of the user or service making the API request.
quota_class_name
path
string
The name of the quota class for which to set quotas.
shares (Optional)
body
integer
The total maximum number of shares that are
allowed in a project.
snapshots (Optional)
body
integer
The total maximum number of share snapshots that
are allowed in a project.
gigabytes (Optional)
body
integer
The total maximum number of share gigabytes that
are allowed in a project. You cannot request a share that exceeds
the allowed gigabytes quota.
snapshot-gigabytes (Optional)
body
integer
The total maximum number of snapshot gigabytes
that are allowed in a project.
share-networks (Optional)
body
integer
The total maximum number of share-networks that
are allowed in a project.
share-replicas (Optional)
body
integer
The maximum number of share replicas that is allowed.
New in version 2.53
replica-gigabytes (Optional)
body
integer
The maximum number of replica gigabytes that are allowed in a project.
You cannot create a share, share replica, manage a share or extend a
share if it is going to exceed the allowed replica gigabytes quota.
The total maximum number of share gigabytes that
are allowed in a project. You cannot request a share that exceeds
the allowed gigabytes quota.
share_group_snapshots
body
integer
The maximum number of share group snapshots.
New in version 2.40
snapshots
body
integer
The total maximum number of share snapshots that
are allowed in a project.
snapshot_gigabytes
body
integer
The total maximum number of snapshot gigabytes
that are allowed in a project.
shares
body
integer
The total maximum number of shares that are
allowed in a project.
share_networks
body
integer
The total maximum number of share-networks that
are allowed in a project.
share_replicas
body
integer
The maximum number of share replicas that is allowed.
New in version 2.53
replica_gigabytes
body
integer
The maximum number of replica gigabytes that are allowed in a project.
You cannot create a share, share replica, manage a share or extend a
share if it is going to exceed the allowed replica gigabytes quota.
User messages are automatically created when an asynchronous action fails on a
resource. In such situations an error is logged in the appropriate log file but
end users may not have access to the log files. User messages can be used by
users to get error details for failed actions. This is handy for example when
creating shares - if a share creation fails because a scheduling filter doesn’t
find suitable back-end host for the share, this share will end up in error
state, but from user messages API users can get details about the last
executed filter which helps them identify the issue and perhaps re-attempt the
creation request with different parameters.
The project ID of the user or service making the API request.
limit (Optional)
query
integer
The maximum number of shares to return.
offset (Optional)
query
integer
The offset to define start point of share or share group
listing.
sort_key (Optional)
query
string
The key to sort a list of messages. A valid value
is id, project_id, request_id, resource_type,
action_id, detail_id, resource_id, message_level,
expires_at, created_at.
sort_dir (Optional)
query
string
The direction to sort a list of shares. A valid
value is asc, or desc.
action_id (Optional)
query
string
The ID of the action during which the message was created.
detail_id (Optional)
query
string
The ID of the message detail.
message_level (Optional)
query
string
The message level.
project_id (Optional)
query
string
The ID of the project for which the message was created.
request_id (Optional)
query
string
The ID of the request during which the message was created.
resource_id (Optional)
query
string
The UUID of the resource for which the message was created.
resource_type (Optional)
query
string
The type of the resource for which the message was created.
{"messages":[{"links":[{"href":"http://192.168.122.180:8786/v2/2e3de76b49b444fd9dc7ca9f7048ce6b/messages/4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5","rel":"self"},{"href":"http://192.168.122.180:8786/2e3de76b49b444fd9dc7ca9f7048ce6b/messages/4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5","rel":"bookmark"}],"id":"4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5","resource_id":"351cc796-2d79-4a08-b878-a8ed933b6b68","message_level":"ERROR","user_message":"allocate host: No storage could be allocated for this share request. Trying again with a different size or share type may succeed.","expires_at":"2017-07-10T10:27:43.000000","created_at":"2017-07-10T10:26:43.000000","detail_id":"002","request_id":"req-24e7ccb6-a7d5-4ddd-a8e4-d8f72a4509c8","project_id":"2e3de76b49b444fd9dc7ca9f7048ce6b","resource_type":"SHARE","action_id":"001"}]}
{"message":{"links":[{"href":"http://192.168.122.180:8786/v2/2e3de76b49b444fd9dc7ca9f7048ce6b/messages/4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5","rel":"self"},{"href":"http://192.168.122.180:8786/2e3de76b49b444fd9dc7ca9f7048ce6b/messages/4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5","rel":"bookmark"}],"resource_id":"351cc796-2d79-4a08-b878-a8ed933b6b68","message_level":"ERROR","user_message":"allocate host: No storage could be allocated for this share request. Trying again with a different size or share type may succeed.","expires_at":"2017-07-10T10:27:43.000000","id":"4b319d29-d5b7-4b6e-8e7c-8d6e53f3c3d5","created_at":"2017-07-10T10:26:43.000000","detail_id":"002","request_id":"req-24e7ccb6-a7d5-4ddd-a8e4-d8f72a4509c8","project_id":"2e3de76b49b444fd9dc7ca9f7048ce6b","resource_type":"SHARE","action_id":"001"}}
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2019-03-27T09:49:58-05:00.
updated_at
body
string
The date and time stamp when the resource was last updated within the
service’s database. If a resource was never updated after it was
created, the value of this parameter is set to null.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2016-12-31T13:14:15-05:00.
access_type
body
string
The access rule type. A valid value for the
share access rule type is one of the following values: - ip.
Authenticates an instance through its IP address. A valid format
is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example
0.0.0.0/0. - cert. Authenticates an instance through a
TLS certificate. Specify the TLS identity as the IDENTKEY. A
valid value is any string up to 64 characters long in the common
name (CN) of the certificate. The meaning of a string depends on
its interpretation. - user. Authenticates by a user or
group name. A valid value is an alphanumeric string that can
contain some special characters and is from 4 to 32 characters
long.
access_to
body
string
The value that defines the access. The back end
grants or denies the access to it. A valid value is one of these
values: - ip. Authenticates an instance through its IP
address. A valid format is XX.XX.XX.XX or
XX.XX.XX.XX/XX. For example 0.0.0.0/0. - cert.
Authenticates an instance through a TLS certificate. Specify the
TLS identity as the IDENTKEY. A valid value is any string up to
64 characters long in the common name (CN) of the certificate.
The meaning of a string depends on its interpretation. -
user. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 32 characters long.
access_key
body
string
The access credential of the entity granted share access.
New in version 2.21
state
body
string
Prior to versions 2.28, the state of all access rules of a given share
is the same at all times. This could be new, active or
error. Since 2.28, the state of each access rule of a share is
independent of the others and can be queued_to_apply,
applying, active, error, queued_to_deny or denying.
A new rule starts out in queued_to_apply state and is successfully
applied if it transitions to active state.
access_level
body
string
The access level to the share. To grant or deny
access to a share, you specify one of the following share access
levels: - rw. Read and write (RW) access. - ro. Read-
only (RO) access.
id
body
string
The access rule ID.
access_metadata
body
object
One or more access rule metadata key and value pairs as a
dictionary of strings.