In order to bring new features to users over time, the Shared File Systems API
supports versioning. There are two kinds of versions in the Shared File
Systems API:
”major versions”, which have dedicated URLs
”microversions”, which can be requested through the use of the
X-OpenStack-Manila-API-Version header
Read more about microversion guidelines that the service adheres to here
GET
/
List All Major Versions
This fetches all the information about all known major API versions in
the deployment. Links to more specific information will be provided
for each API version, as well as information about supported min and
max microversions.
A list of version objects that describe the API versions available.
id
body
string
A common name for the version in question. Informative only, it has no real semantic meaning.
status
body
string
The status of this API version. This can be one of:
CURRENT: this is the preferred version of the API to use
SUPPORTED: this is an older, but still supported version of the API
DEPRECATED: a deprecated version of the API that is slated for removal
links
body
array
The share links
media-types (Optional)
query
object
Media types supported by the API.
version
body
string
If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.
min_version
body
string
If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.
Note
The updated and media-types parameters in the response are
vestigial and provide no useful information. They will probably be
deprecated and removed in the future.
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.
min_version
body
string
If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.
media-types (Optional)
query
object
Media types supported by the API.
Note
The updated and media-types parameters in the response are
vestigial and provide no useful information. They will probably be
deprecated and removed in the future.
{"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 GBs.
Number of share-networks.
Number of share-snapshots.
Number of shares.
Shares and total used memory, in GBs.
Snapshots and total used memory, in GBs.
Rate limits control the frequency at which users can issue specific
API requests. Administrators use rate limiting to configure limits
on the type and number of API calls that can be made in a specific
time interval. For example, a rate limit can control the number of
GET requests that can be processed during a one-minute period.
GET
/v2/{tenant_id}/limits
List share limits
Lists share limits.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The total maximum number of share gigabytes that
are allowed in a project. You cannot request a share that exceeds
the allowed gigabytes quota.
maxTotalSnapshotGigabytes
body
integer
The total maximum number of snapshot gigabytes
that are allowed in a project.
maxTotalShares
body
integer
The total maximum number of shares that are
allowed in a project.
maxTotalShareSnapshots
body
integer
The total maximum number of share snapshots that
are allowed in a project.
maxTotalShareNetworks
body
integer
The total maximum number of share-networks that
are allowed in a project.
totalSharesUsed
body
integer
The total number of created shares in a project.
totalShareSnapshotsUsed
body
integer
The total number of created share snapshots in a
project.
totalShareNetworksUsed
body
integer
The total number of created share-networks in a
project.
totalShareGigabytesUsed
body
integer
The total number of gigabytes used in a project
by shares.
totalSnapshotGigabytesUsed
body
integer
The total number of gigabytes used in a project
by snapshots.
uri (Optional)
body
string
A human-readable URI of a rate limit.
regex (Optional)
body
string
An API regular expression. For example,
^/shares for the /shares API URI or .* for any URI.
value (Optional)
body
integer
The number of API requests that are allowed
during a time interval. Used in conjunction with the unit
parameter, expressed as value per unit. For example, 120
requests are allowed per minute.
verb (Optional)
body
string
The HTTP method for the API request. For example,
GET, POST, DELETE, and so on.
remaining (Optional)
body
integer
The remaining number of allowed requests.
unit (Optional)
body
string
The time interval during which a number of API
requests are allowed. A valid value is SECOND, MINUTE,
HOUR, or DAY. Used in conjunction with the value
parameter, expressed as value per unit. For example, 120
requests are allowed per minute.
next-available (Optional)
body
string
The date and time stamp when next issues are available.
(Admin only). Defines whether to list shares for
all tenants. Set to 1 to list shares for all tenants. Set to
0 to list shares only for the current tenant.
name (Optional)
body
string
The share name.
status (Optional)
query
string
Filters by a share status. A valid value is
creating, error, available, deleting,
error_deleting, manage_starting, manage_error,
unmanage_starting, unmanage_error, unmanaged,
extending, extending_error, shrinking,
shrinking_error, or shrinking_possible_data_loss_error.
share_server_id
body
string
The UUID of the share server.
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
extra_specs
body
object
The extra specifications for the share type.
share_type_id
path
string
The UUID of the share type.
limit (Optional)
query
integer
The maximum number of shares to return.
offset (Optional)
query
integer
The offset to define start point of share
listing.
sort_key (Optional)
query
string
The key to sort a list of shares. A valid value
is id, status, size, host, share_proto,
export_location, availability_zone, user_id,
project_id, created_at, updated_at, display_name,
name, share_type_id, share_type, share_network_id,
share_network, snapshot_id, or snapshot.
sort_dir (Optional)
query
string
The direction to sort a list of shares. A valid
value is asc, or desc.
snapshot_id (Optional)
body
string
The UUID of the share’s base snapshot to filter the request based on.
host
body
string
The share host name.
share_network_id
body
string
The share network ID.
project_id (Optional)
query
string
The UUID of the project in which the share was
created. Useful with all_tenants parameter.
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
consistency_group_id
body
string
(Since API v2.4) The UUID of the consistency
group where the share was created.
(Admin only). Defines whether to list shares for
all tenants. Set to 1 to list shares for all tenants. Set to
0 to list shares only for the current tenant.
name (Optional)
body
string
The share name.
status (Optional)
query
string
Filters by a share status. A valid value is
creating, error, available, deleting,
error_deleting, manage_starting, manage_error,
unmanage_starting, unmanage_error, unmanaged,
extending, extending_error, shrinking,
shrinking_error, or shrinking_possible_data_loss_error.
share_server_id
body
string
The UUID of the share server.
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
extra_specs
body
object
The extra specifications for the share type.
share_type_id
path
string
The UUID of the share type.
limit (Optional)
query
integer
The maximum number of shares to return.
offset (Optional)
query
integer
The offset to define start point of share
listing.
sort_key (Optional)
query
string
The key to sort a list of shares. A valid value
is id, status, size, host, share_proto,
export_location, availability_zone, user_id,
project_id, created_at, updated_at, display_name,
name, share_type_id, share_type, share_network_id,
share_network, snapshot_id, or snapshot.
sort_dir (Optional)
query
string
The direction to sort a list of shares. A valid
value is asc, or desc.
snapshot_id (Optional)
body
string
The UUID of the share’s base snapshot to filter the request based on.
host
body
string
The share host name.
share_network_id
body
string
The share network ID.
project_id (Optional)
query
string
The UUID of the project in which the share was
created. Useful with all_tenants parameter.
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
consistency_group_id
body
string
(Since API v2.4) The UUID of the consistency
group where the share was created.
(Since API v2.6) The share type name. Minor
versions support only the share_type parameter where the share
type name is expected.
links
body
array
The share links
availability_zone (Optional)
body
string
(Since API v2.1) The availability zone.
share_network_id
body
string
The share network ID.
export_locations (Optional)
body
array
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Deprecated in version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id (Optional)
query
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
(Since API v2.6) The UUID of the share type. In
minor versions, this parameter is a share type name, as a string.
(Since API v2.4) The UUID of the consistency
group where the share was created. You can omit this parameter if
the share was created without a consistency group.
project_id
body
string
The UUID of the project in which the share was
created.
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
status
body
string
The consistency group snapshot status, which is
available, creating, error, deleting, or
error_deleting.
description (Optional)
body
string
The share description.
host
body
string
The share host name.
access_rules_status
body
string
The share instance access rules status. A valid value is active,
error, or syncing. In versions prior to 2.28, syncing was
represented with status out_of_sync.
New in version 2.10
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
task_state
body
string
(Since API v2.5) For the share migration, the
migration task state. A valid value is null,
migration_starting, migration_error,
migration_success, migration_completing, or migrating.
The task_state is null unless the share is migrated from
one back-end to another. For details, see os-migrate_share
extension request.
snapshot_support
body
boolean
(Since API v2.2) An extra specification that
filters back ends by whether they do or do not support share
snapshots.
name (Optional)
body
string
The share name.
has_replicas
body
boolean
(Since API v2.11) Indicates whether a share has
replicas or not.
replication_type (Optional)
body
string
(Since API v2.11) The share replication type.
created_at
body
string
The date and time stamp when the share was created.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2015-08-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, or CephFS.
CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
source_cgsnapshot_member_id
body
string
(Since API v2.4) If the share was created with
consistency_group_id attribute, the snapshot member ID. The
corresponding consistency group must be created from a snapshot
with the current share as a member. Consistency groups and
snapshots are the part of the Shared File Systems experimental
API. For details, see Consistency groups and Consistency group snapshots.
{"shares":[{"links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc","rel":"bookmark"}],"availability_zone":"nova","share_network_id":"f9b2e754-ac01-4466-86e1-5c569424754e","export_locations":[],"share_server_id":"87d8943a-f5da-47a4-b2f2-ddfa6794aa82","snapshot_id":null,"id":"f45cc5b2-d1bb-4a3e-ba5b-5c4125613adc","size":1,"share_type":"25747776-08e5-494f-ab40-a64b9d20d8f7","share_type_name":"default","export_location":null,"consistency_group_id":"9397c191-8427-4661-a2e8-b23820dc01d4","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","metadata":{},"status":"error","access_rules_status":"active","description":"There is a share description.","host":"manila2@generic1#GENERIC1","task_state":null,"is_public":true,"snapshot_support":true,"name":"my_share4","has_replicas":false,"replication_type":null,"created_at":"2015-09-16T18:19:50.000000","share_proto":"NFS","volume_type":"default","source_cgsnapshot_member_id":null},{"links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/c4a2ced4-2c9f-4ae1-adaa-6171833e64df","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/c4a2ced4-2c9f-4ae1-adaa-6171833e64df","rel":"bookmark"}],"availability_zone":"nova","share_network_id":"f9b2e754-ac01-4466-86e1-5c569424754e","export_locations":["10.254.0.5:/shares/share-50ad5e7b-f6f1-4b78-a651-0812cef2bb67"],"share_server_id":"87d8943a-f5da-47a4-b2f2-ddfa6794aa82","snapshot_id":null,"id":"c4a2ced4-2c9f-4ae1-adaa-6171833e64df","size":1,"share_type":"25747776-08e5-494f-ab40-a64b9d20d8f7","share_type_name":"default","export_location":"10.254.0.5:/shares/share-50ad5e7b-f6f1-4b78-a651-0812cef2bb67","consistency_group_id":"9397c191-8427-4661-a2e8-b23820dc01d4","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","metadata":{},"status":"available","access_rules_status":"active","description":"Changed description.","host":"manila2@generic1#GENERIC1","task_state":null,"is_public":true,"snapshot_support":true,"name":"my_share4","has_replicas":false,"replication_type":null,"created_at":"2015-09-16T17:26:28.000000","share_proto":"NFS","volume_type":"default","source_cgsnapshot_member_id":null}]}
(Since API v2.6) The share type name. Minor
versions support only the share_type parameter where the share
type name is expected.
links
body
array
The share links
availability_zone
body
string
The availability zone.
share_network_id
body
string
The share network ID.
export_locations (Optional)
body
array
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Deprecated in version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id (Optional)
query
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
(Since API v2.6) The UUID of the share type. In
minor versions, this parameter is a share type name, as a string.
(Since API v2.4) The UUID of the consistency
group where the share was created.
project_id
body
string
The UUID of the project in which the share was
created.
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
status
body
string
The share status, which is creating,
error, available, deleting, error_deleting,
manage_starting, manage_error, unmanage_starting,
unmanage_error, unmanaged, extend,
extending_error, shrinking, shrinking_error, or
shrinking_possible_data_loss_error.
description (Optional)
body
string
The share description.
host (Optional)
body
string
The share host name.
access_rules_status
body
string
The share instance access rules status. A valid value is active,
error, or syncing. In versions prior to 2.28, syncing was
represented with status out_of_sync.
New in version 2.10
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
task_state
body
string
(Since API v2.5) For the share migration, the
migration task state. A valid value is null,
migration_starting, migration_error,
migration_success, migration_completing, or migrating.
The task_state is null unless the share is migrated from
one back-end to another. For details, see os-migrate_share
extension request.
snapshot_support
body
boolean
(Since API v2.2) An extra specification that
filters back ends by whether they do or do not support share
snapshots.
name (Optional)
body
string
The share name.
has_replicas
body
boolean
(Since API v2.11) Indicates whether a share has
replicas or not.
replication_type (Optional)
body
string
(Since API v2.11) The share replication type.
created_at
body
string
The date and time stamp when the share was created.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2015-08-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, or CephFS.
CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
source_cgsnapshot_member_id
body
string
(Since API v2.4) If the share was created with
consistency_group_id attribute, the snapshot member ID. The
corresponding consistency group must be created from a snapshot
with the current share as a member. Consistency groups and
snapshots are the part of the Shared File Systems experimental
API. For details, see Consistency groups and Consistency group snapshots.
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, or CephFS.
CephFS supported is starting with API v2.13.
size
body
integer
The share size, in GBs. The requested share size
cannot be greater than the allowed GB quota. To view the allowed
quota, issue a get limits request.
name (Optional)
body
string
The share name.
description (Optional)
body
string
The share description.
display_name (Optional)
body
string
The share name. The Shared File Systems API
supports the use of both name and display_name attributes,
which are inherited attributes from the Block Storage API.
display_description (Optional)
body
string
The share description. The Shared File Systems
API supports the use of both description and
display_description parameters, which are inherited attributes
from the Block Storage API.
share_type (Optional)
body
string
The share type name. If you omit this parameter,
the default share type is used. To view the default share type set
by the administrator, issue a list default share types request.
You cannot specify both the share_type and volume_type
parameters.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
snapshot_id (Optional)
body
string
The UUID of the share’s base snapshot.
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
share_network_id (Optional)
body
string
The UUID of a share network where the share
server exists or will be created. If share_network_id is
None and you provide a snapshot_id, the
share_network_id value from the snapshot is used.
consistency_group_id (Optional)
body
string
(Since API v2.4) The UUID of the available
consistency group in which the share will be created. The
consistency group must support the share_type and
share_network_id. For details, see Consistency groups.
The share status. A valid value is: -
creating. The share is being created. - deleting. The
share is being deleted. - error. An error occurred during
share creation. - error_deleting. An error occurred during
share deletion. - available. The share is ready to use. -
manage_starting. Share manage started. - manage_error.
Share manage failed. - unmanage_starting. Share unmanage
started. - unmanage_error. Share cannot be unmanaged. -
unmanaged. Share was unmanaged. - extending. The extend,
or increase, share size request was issued successfully. -
extending_error. Extend share failed. - shrinking. Share
is being shrunk. - shrinking_error. Failed to update quota on
share shrinking. - shrinking_possible_data_loss_error. Shrink
share failed due to possible data loss.
links
body
array
The share links
project_id (Optional)
query
string
The UUID of the project in which the share was
created. Useful with all_tenants parameter.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, or CephFS.
CephFS supported is starting with API v2.13.
size
body
integer
The share size, in GBs. The requested share size
cannot be greater than the allowed GB quota. To view the allowed
quota, issue a get limits request.
name (Optional)
body
string
The share name.
description (Optional)
body
string
The share description.
display_name (Optional)
body
string
The share name. The Shared File Systems API
supports the use of both name and display_name attributes,
which are inherited attributes from the Block Storage API.
display_description (Optional)
body
string
The share description. The Shared File Systems
API supports the use of both description and
display_description parameters, which are inherited attributes
from the Block Storage API.
share_type
body
string
(Since API v2.6) The UUID of the share type. In
minor versions, this parameter is a share type name, as a string.
share_type_name
body
string
(Since API v2.6) The share type name. Minor
versions support only the share_type parameter where the share
type name is expected.
has_replicas
body
boolean
(Since API v2.11) Indicates whether a share has
replicas or not.
replication_type (Optional)
body
string
(Since API v2.11) The share replication type.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
snapshot_id (Optional)
query
string
The UUID of the snapshot that was used to create
the share.
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Deprecated in version 2.8
host
body
string
The share host name.
task_state
body
string
(Since API v2.5) For the share migration, the
migration task state. A valid value is null,
migration_starting, migration_error,
migration_success, migration_completing, or migrating.
The task_state is null unless the share is migrated from
one back-end to another. For details, see os-migrate_share
extension request.
share_server_id
body
string
The UUID of the share server.
consistency_group_id
body
string
(Since API v2.4) The UUID of the consistency
group where the share was created.
snapshot_support
body
boolean
(Since API v2.2) An extra specification that
filters back ends by whether they do or do not support share
snapshots.
source_cgsnapshot_member_id
body
string
(Since API v2.4) If the share was created with
consistency_group_id attribute, the snapshot member ID. The
corresponding consistency group must be created from a snapshot
with the current share as a member. Consistency groups and
snapshots are the part of the Shared File Systems experimental
API. For details, see Consistency groups and Consistency group snapshots.
created_at
body
string
The date and time stamp when the share was created.
The Shared File Systems protocol of the share to
manage. A valid value is NFS, CIFS, GlusterFS, or
HDFS.
name (Optional)
body
string
The share name.
share_type (Optional)
body
string
The share type name.
driver_options (Optional)
body
object
A set of one or more key and value pairs, as a
dictionary of strings, that describe driver options.
export_path
body
string
The share export path in the format appropriate
for the protocol: - NFS protocol. 10.0.0.1:/foo_path. For
example, 10.254.0.5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5. - CIFS protocol.
\\10.0.0.1\foo_name_of_cifs_share.
service_host
body
string
The manage-share service host in this format:
host@backend#POOL. - host. The host name for the back
end. - backend. The name of the back end. - POOL. The
pool name for the back end.
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
{"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."}}
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Deprecated in version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id (Optional)
query
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
(Since API v2.6) The UUID of the share type. In
minor versions, this parameter is a share type name, as a string.
share_type_name
body
string
(Since API v2.6) The share type name. Minor
versions support only the share_type parameter where the share
type name is expected.
has_replicas
body
boolean
(Since API v2.11) Indicates whether a share has
replicas or not.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2015-08-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, or CephFS.
CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
source_cgsnapshot_member_id
body
string
(Since API v2.4) If the share was created with
consistency_group_id attribute, the snapshot member ID. The
corresponding consistency group must be created from a snapshot
with the current share as a member. Consistency groups and
snapshots are the part of the Shared File Systems experimental
API. For details, see Consistency groups and Consistency group snapshots.
(Since API v2.6) The share type name. Minor
versions support only the share_type parameter where the share
type name is expected.
links
body
array
The share links
availability_zone
body
string
The availability zone.
share_network_id
body
string
The share network ID.
export_locations (Optional)
body
array
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Deprecated in version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id (Optional)
query
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
(Since API v2.6) The UUID of the share type. In
minor versions, this parameter is a share type name, as a string.
(Since API v2.4) The UUID of the consistency
group where the share was created.
project_id
body
string
The UUID of the project in which the share was
created.
metadata (Optional)
body
object
One or more metadata key and value pairs as a
dictionary of strings.
status
body
string
The share status, which is creating,
error, available, deleting, error_deleting,
manage_starting, manage_error, unmanage_starting,
unmanage_error, unmanaged, extend,
extending_error, shrinking, shrinking_error, or
shrinking_possible_data_loss_error.
description (Optional)
body
string
The share description.
host (Optional)
body
string
The share host name.
access_rules_status
body
string
The share instance access rules status. A valid value is active,
error, or syncing. In versions prior to 2.28, syncing was
represented with status out_of_sync.
New in version 2.10
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
task_state
body
string
(Since API v2.5) For the share migration, the
migration task state. A valid value is null,
migration_starting, migration_error,
migration_success, migration_completing, or migrating.
The task_state is null unless the share is migrated from
one back-end to another. For details, see os-migrate_share
extension request.
snapshot_support
body
boolean
(Since API v2.2) An extra specification that
filters back ends by whether they do or do not support share
snapshots.
name (Optional)
body
string
The share name.
has_replicas
body
boolean
(Since API v2.11) Indicates whether a share has
replicas or not.
replication_type (Optional)
body
string
(Since API v2.11) The share replication type.
created_at
body
string
The date and time stamp when the share was created.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2015-08-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, or CephFS.
CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
source_cgsnapshot_member_id
body
string
(Since API v2.4) If the share was created with
consistency_group_id attribute, the snapshot member ID. The
corresponding consistency group must be created from a snapshot
with the current share as a member. Consistency groups and
snapshots are the part of the Shared File Systems experimental
API. For details, see Consistency groups and Consistency group snapshots.
{"share":{"links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc3-4e4a-9993-9ea223f73264","rel":"bookmark"}],"availability_zone":"nova","share_network_id":"713df749-aac0-4a54-af52-10f6c991e80c","export_locations":[],"share_server_id":"e268f4aa-d571-43dd-9ab3-f49ad06ffaef","snapshot_id":null,"id":"011d21e2-fbc3-4e4a-9993-9ea223f73264","size":1,"share_type":"25747776-08e5-494f-ab40-a64b9d20d8f7","share_type_name":"default","export_location":null,"consistency_group_id":"9397c191-8427-4661-a2e8-b23820dc01d4","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","metadata":{"project":"my_app","aim":"doc"},"status":"error","description":"Changing the share description.","host":"manila2@generic1#GENERIC1","task_state":null,"is_public":true,"snapshot_support":true,"name":"share_London","created_at":"2015-09-18T10:25:24.000000","share_proto":"NFS","volume_type":"default","source_cgsnapshot_member_id":null}}
(Since API v2.4) The UUID of the consistency
group where the share was created. You can omit this parameter if
the share was created without a consistency group.
The UUID of the share instance that this
export location belongs to.
path
body
string
The export location path that should be used for
mount operation.
is_admin_only
body
boolean
Defines purpose of an export location. If set to
true, then it is expected to be used for service needs and by
administrators only. If it is set to false, then this export
location can be used by end users.
preferred
body
boolean
Drivers may use this field to identify which export locations
are most efficient and should be used preferentially by clients.
By default it is set to false value.
The UUID of the share instance that this
export location belongs to.
path
body
string
The export location path that should be used for
mount operation.
is_admin_only
body
boolean
Defines purpose of an export location. If set to
true, then it is expected to be used for service needs and by
administrators only. If it is set to false, then this export
location can be used by end users.
preferred
body
boolean
Drivers may use this field to identify which export locations
are most efficient and should be used preferentially by clients.
By default it is set to false value.
New in version 2.14
created_at
body
string
The date and time stamp when the share export location was
created.
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.
One or more metadata key-value pairs, as a
dictionary of strings. For example, "project":"my_test","aim":"testing". The share server does not respect case-sensitive key
names. For example, "key":"v1" and "KEY":"V1" are
equivalent. If you specify both key-value pairs, the server sets
and returns only the "KEY":"V1" key-value pair.
Share actions include granting or revoking share access, listing the
available access rules for a share, explicitly updating the state of a
share, resizing a share and un-managing a share.
As administrator, you can reset the state of a share and force-
delete a share in any state. Use the policy.json file to grant
permissions for this action to other roles.
You can set the state of a share to one of these supported states:
available
error
creating
deleting
error_deleting
If API version 1.0-2.6 is used then all share actions, defined
below, should include prefix os- in top element of request
JSON’s body.
For example: {“access_list”: null} is valid for v2.7+. And {“os-
access_list”: null} is valid for v1.0-2.6
POST
/v2/{tenant_id}/shares/{share_id}/action
Grant access
All manila shares begin with no access. Clients must be provided with
explicit access via this API.
To grant access, specify one of these supported share access levels:
rw. Read and write (RW) access.
ro. Read-only (RO) access.
You must also specify one of these supported authentication
methods:
ip. Authenticates an instance through its IP address. A valid
format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example
0.0.0.0/0.
cert. Authenticates an instance through a TLS certificate.
Specify the TLS identity as the IDENTKEY. A valid value is any
string up to 64 characters long in the common name (CN) of the
certificate. The meaning of a string depends on its
interpretation.
user. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 32 characters long.
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.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2015-08-27T09:49:58-05:00.
If the access rule was never updated, this value is null.
access_type
body
string
The access rule type. A valid value for the
share access rule type is one of the following values: - ip.
Authenticates an instance through its IP address. A valid format
is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example
0.0.0.0/0. - cert. Authenticates an instance through a
TLS certificate. Specify the TLS identity as the IDENTKEY. A
valid value is any string up to 64 characters long in the common
name (CN) of the certificate. The meaning of a string depends on
its interpretation. - user. Authenticates by a user or
group name. A valid value is an alphanumeric string that can
contain some special characters and is from 4 to 32 characters
long.
access_to
body
string
The value that defines the access. The back end
grants or denies the access to it. A valid value is one of these
values: - ip. Authenticates an instance through its IP
address. A valid format is XX.XX.XX.XX or
XX.XX.XX.XX/XX. For example 0.0.0.0/0. - cert.
Authenticates an instance through a TLS certificate. Specify the
TLS identity as the IDENTKEY. A valid value is any string up to
64 characters long in the common name (CN) of the certificate.
The meaning of a string depends on its interpretation. -
user. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 32 characters long.
access_key
body
string
The access credential of the entity granted share access.
New in version 2.21
access
body
object
The access object.
access_level
body
string
The access level to the share. To grant or deny
access to a share, you specify one of the following share access
levels: - rw. Read and write (RW) access. - ro. Read-
only (RO) access.
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.
The access rule type. A valid value for the
share access rule type is one of the following values: - ip.
Authenticates an instance through its IP address. A valid format
is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example
0.0.0.0/0. - cert. Authenticates an instance through a
TLS certificate. Specify the TLS identity as the IDENTKEY. A
valid value is any string up to 64 characters long in the common
name (CN) of the certificate. The meaning of a string depends on
its interpretation. - user. Authenticates by a user or
group name. A valid value is an alphanumeric string that can
contain some special characters and is from 4 to 32 characters
long.
access_key
body
string
The access credential of the entity granted share access.
New in version 2.21
access_to
body
string
The value that defines the access. The back end
grants or denies the access to it. A valid value is one of these
values: - ip. Authenticates an instance through its IP
address. A valid format is XX.XX.XX.XX or
XX.XX.XX.XX/XX. For example 0.0.0.0/0. - cert.
Authenticates an instance through a TLS certificate. Specify the
TLS identity as the IDENTKEY. A valid value is any string up to
64 characters long in the common name (CN) of the certificate.
The meaning of a string depends on its interpretation. -
user. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 32 characters long.
access_level
body
string
The access level to the share. To grant or deny
access to a share, you specify one of the following share access
levels: - rw. Read and write (RW) access. - ro. Read-
only (RO) access.
state
body
string
Prior to versions 2.28, the state of all access rules of a given share
is the same at all times. This could be new, active or
error. Since 2.28, the state of each access rule of a share is
independent of the others and can be queued_to_apply,
applying, active, error, queued_to_deny or denying.
A new rule starts out in queued_to_apply state and is successfully
applied if it transitions to active state.
access_list
body
string
The object of the access rule. To list access
rules, set this value to null.
id
body
string
The access rule ID.
created_at
body
string
The date and time stamp when the access rule was created.
Reverts a share to the specified snapshot, which must be the most recent one
known to manila. This API is available in versions later than or equal to 2.27.
Use the shared file service to make snapshots of shares. A share
snapshot is a point-in-time, read-only copy of the data that is
contained in a share. You can create, manage, update, and delete
share snapshots. After you create or manage a share snapshot, you
can create a share from it. You can also revert a share to its most
recent snapshot.
You can update a share snapshot to rename it, change its
description, or update its state to one of these supported states:
available
error
creating
deleting
error_deleting
manage_starting
manage_error
unmanage_starting
unmanage_error
restoring
As administrator, you can also reset the state of a snapshot and
force-delete a share snapshot in any state. Use the policy.json
file to grant permissions for these actions to other roles.
GET
/v2/{tenant_id}/snapshots
List share snapshots
Lists all share snapshots.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401)
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
share_id
body
string
The UUID of the source share that was used to
create the snapshot.
name
body
string
The snapshot name.
description
body
string
The snapshot description.
created_at
body
string
The date and time stamp when the snapshot was created.
{"snapshots":[{"status":"creating","share_id":"d94a8548-2079-4be0-b21c-0a887acd31ca","name":"snapshot_My_share","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/086a1aa6-c425-4ecd-9612-391a3b1b9375","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/086a1aa6-c425-4ecd-9612-391a3b1b9375","rel":"bookmark"}],"created_at":"2015-09-07T11:55:09.000000","description":"Here is a snapshot of share My_share","share_proto":"NFS","share_size":1,"id":"086a1aa6-c425-4ecd-9612-391a3b1b9375","size":1},{"status":"available","share_id":"406ea93b-32e9-4907-a117-148b3945749f","name":"snapshot_share1","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"bookmark"}],"created_at":"2015-09-07T11:50:39.000000","description":"Here is a snapshot of share Share1","share_proto":"NFS","share_size":1,"id":"6d221c1d-0200-461e-8d20-24b4776b9ddb","size":1}]}
GET
/v2/{tenant_id}/snapshots/{snapshot_id}
Show share snapshot details
Shows details for a share snapshot.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), itemNotFound(404)
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
share_id
body
string
The UUID of the source share that was used to
create the snapshot.
name
body
string
The snapshot name.
description
body
string
The snapshot description.
created_at
body
string
The date and time stamp when the snapshot was created.
{"snapshot":{"status":"available","share_id":"406ea93b-32e9-4907-a117-148b3945749f","name":"snapshot_share1","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"bookmark"}],"created_at":"2015-09-07T11:50:39.000000","description":"Here is a snapshot of share Share1","share_proto":"NFS","share_size":1,"id":"6d221c1d-0200-461e-8d20-24b4776b9ddb","size":1}}
The UUID of the share from which to create a
snapshot.
force (Optional)
body
boolean
Indicates whether snapshot creation must be attempted
when a share’s status is not available. Set to true to force
snapshot creation when the share is busy performing other operations.
Default is false.
name (Optional)
body
string
The snapshot name.
display_name (Optional)
body
string
The snapshot name. The Shared File Systems API
supports the use of both name and display_name attributes,
which are inherited attributes from the Block Storage API.
description (Optional)
body
string
The snapshot description.
display_description (Optional)
body
string
The snapshot description. The shared file
systems API supports the use of both name and display_name
attributes, which are inherited attributes from the block storage
API.
{"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 (Optional)
body
string
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
name
body
string
The snapshot name.
description
body
string
The snapshot description.
created_at
body
string
The date and time stamp when the snapshot was created.
{"snapshot":{"status":"creating","share_id":"406ea93b-32e9-4907-a117-148b3945749f","name":"snapshot_share1","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"bookmark"}],"created_at":"2015-09-07T11:50:39.756808","description":"Here is a snapshot of share Share1","share_proto":"NFS","share_size":1,"id":"6d221c1d-0200-461e-8d20-24b4776b9ddb","size":1}}
POST
/v2/{tenant_id}/snapshots/manage
Manage share snapshot
(Since API v2.12) Configures Shared File Systems to manage a share snapshot.
The UUID of the share that has snapshot which
should be managed.
provider_location
body
string
Provider location of the snapshot on the backend.
name (Optional)
body
string
The snapshot name.
display_name (Optional)
body
string
The snapshot name. The Shared File Systems API
supports the use of both name and display_name attributes,
which are inherited attributes from the Block Storage API.
description (Optional)
body
string
The snapshot description.
display_description (Optional)
body
string
The snapshot description. The shared file
systems API supports the use of both name and display_name
attributes, which are inherited attributes from the block storage
API.
driver_options (Optional)
body
object
A set of one or more key and value pairs, as a
dictionary of strings, that describe driver options.
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
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 name. The Shared File Systems API
supports the use of both name and display_name attributes,
which are inherited attributes from the Block Storage API.
display_description (Optional)
body
string
The snapshot description. The shared file
systems API supports the use of both name and display_name
attributes, which are inherited attributes from the block storage
API.
The snapshot status, which can be available,
error, creating, deleting, manage_starting,
manage_error, unmanage_starting, unmanage_error or
error_deleting.
share_id
body
string
The UUID of the source share that was used to
create the snapshot.
name
body
string
The snapshot name.
description
body
string
The snapshot description.
created_at
body
string
The date and time stamp when the snapshot was created.
{"snapshot":{"status":"available","share_id":"406ea93b-32e9-4907-a117-148b3945749f","name":"snapshot_Share1","links":[{"href":"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/snapshots/6d221c1d-0200-461e-8d20-24b4776b9ddb","rel":"bookmark"}],"created_at":"2015-09-07T11:50:39.000000","description":"I am changing a description also. Here is a snapshot of share Share1","share_proto":"NFS","share_size":1,"id":"6d221c1d-0200-461e-8d20-24b4776b9ddb","size":1}}
A share network stores network information that share servers can
use where shares are hosted. You can associate a share with a
single share network. When you create a share, you can optionally
specify the ID of a share network through which instances can
access the share.
You can create, update, view, and delete a share network.
When you create a share network, you may optionally specify an associated
neutron network and subnetwork:
Neutron network. Specify a network ID and subnet ID.
For more information about supported plug-ins for share networks,
see Manila Network Plugins.
A share network has these attributes:
The IP block in Classless Inter-Domain Routing (CIDR) notation
from which to allocate the network.
The IP version of the network.
The network type, which is vlan, vxlan, gre, or
flat.
If the network uses segmentation, a segmentation identifier. For
example, VLAN, VXLAN, and GRE networks use segmentation.
GET
/v2/{tenant_id}/share-networks
List share networks
Lists all share networks.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The UUID of a neutron network when setting up a share network
with neutron. Specify both a neutron network and a neutron
subnet that belongs to that neutron network.
neutron_subnet_id (Optional)
body
string
The UUID of the neutron subnet when setting up a share network
with neutron. Specify both a neutron network and a neutron
subnet that belongs to that neutron network.
{"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 UUID of the project where the share network
was created.
neutron_net_id
body
string
The neutron network ID.
neutron_subnet_id
body
string
The neutron subnet ID.
network_type
body
string
The network type. A valid value is VLAN,
VXLAN, GRE, or flat. This parameter is automatically
set to a value determined by the network provider.
segmentation_id
body
integer
The segmentation ID. This parameter is
automatically set to a value determined by the network provider.
For VLAN, this value is an integer from 1 to 4094. For VXLAN,
this value is an integer from 1 to 16777215. For GRE, this value
is an integer from 1 to 4294967295.
cidr
body
string
The IP block from which to allocate the network,
in CIDR notation. For example, 172.16.0.0/24 or
2001:DB8::/64. This parameter is automatically set to a value
determined by the network provider.
ip_version
body
integer
The IP version of the network. A valid value is
4 or 6. This parameter is automatically set to a value
determined by the network provider.
name
body
string
The name of a share network.
description
body
string
The share network description.
created_at
body
string
The date and time stamp when the share network was created.
{"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"}}
The UUID for the tenant for which you want to
show, update, or delete quotas. This ID is different from the
first tenant ID that you specify in the URI: That ID is for the
administrative tenant.
{"share_network":{"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"}}
You can create, update, view, and delete a security service. A
security service stores configuration information for clients for
authentication and authorization (AuthN/AuthZ). For example, a
share server will be the client for an existing service such as
LDAP, Kerberos, or Microsoft Active Directory.
You can associate a share with from one to three security service
types:
ldap. LDAP.
kerberos. Kerberos.
active_directory. Microsoft Active Directory.
You can configure a security service with these options:
A DNS IP address.
An IP address or host name.
A domain.
A user or group name.
The password for the user, if you specify a user name.
GET
/v2/{tenant_id}/security-services
List security services
Lists all security services.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
{"security_services":[{"status":"new","domain":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ1","created_at":"2015-09-07T12:19:10.000000","description":"Creating my first Security Service","updated_at":null,"server":null,"dns_ip":"10.0.0.0/24","user":"demo","password":"supersecret","type":"kerberos","id":"3c829734-0679-4c17-9637-801da48c0d5f","share_networks":[]},{"status":"new","domain":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ2","created_at":"2015-09-07T12:25:03.000000","description":"Creating my second Security Service","updated_at":null,"server":null,"dns_ip":"10.0.0.0/24","user":null,"password":null,"type":"ldap","id":"5a1d3a12-34a7-4087-8983-50e9ed03509a","share_networks":[]}]}
{"security_service":{"status":"new","domain":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ1","created_at":"2015-09-07T12:19:10.000000","updated_at":null,"server":null,"dns_ip":"10.0.0.0/24","user":"demo","password":"supersecret","type":"kerberos","id":"3c829734-0679-4c17-9637-801da48c0d5f","description":"Creating my first Security Service"}}
{"security_service":{"description":"Creating my first Security Service","dns_ip":"10.0.0.0/24","user":"demo","password":"***","type":"kerberos","name":"SecServ1"}}
{"security_service":{"status":"new","domain":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ1","created_at":"2015-09-07T12:19:10.695211","updated_at":null,"server":null,"dns_ip":"10.0.0.0/24","user":"demo","password":"supersecret","type":"kerberos","id":"3c829734-0679-4c17-9637-801da48c0d5f","description":"Creating my first Security Service"}}
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.
{"security_service":{"status":"new","domain":"my_domain","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","name":"SecServ1","created_at":"2015-09-07T12:19:10.000000","updated_at":"2015-09-07T12:47:21.858737","server":null,"dns_ip":"10.0.0.0/24","user":"new_user","password":"pass","type":"kerberos","id":"3c829734-0679-4c17-9637-801da48c0d5f","description":"Adding a description"}}
A share server is created by multi-tenant back-end drivers where
shares are hosted. For example, with the generic driver, shares
are hosted on Compute VMs.
Administrators can perform read and delete actions for share
servers. An administrator can delete an active share server only if
it contains no dependent shares. If an administrator deletes the
share server, the Shared File Systems service creates a share
server in response to a subsequent create share request.
An administrator can use the policy.json file to grant
permissions for share server actions to other roles.
The status of a share server indicates its current state. After you
successfully set up a share server, its status is active. If
errors occur during set up such as when server data is not valid,
its status is error.
The possible share servers statuses are:
Share server statuses
Status
Description
active
Share server was successfully set up.
error
The set up or deletion of the share server failed.
deleting
The share server has no dependent shares and is being deleted.
creating
The share server is being created on the back end with data from
the database.
GET
/v2/{tenant_id}/share-servers
List share servers
Lists all share servers.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The share server status, which is active,
error, creating, or deleting.
backend_details
body
string
The back-end details for a server. Each back end
can store any key- value information that it requires. For
example, the generic back- end driver might store the router ID.
share_network_id
body
string
The UUID of a share network that is associated
with the share server.
share_network_name
body
string
The name of a share network.
host
body
string
The share server host name or IP address.
created_at
body
string
The date and time stamp when the share server was created.
Administrators can list, show information for, explicitly set the
state of, and force-delete share instances. Use the policy.json
file to grant permissions for these actions to other roles.
GET
/v2/{tenant_id}/share_instances
List share instances
Lists all share instances.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The share instance status. A valid value is
available, error, creating, deleting, and
error_deleting.
access_rules_status
body
string
The share instance access rules status. A valid value is active,
error, or syncing. In versions prior to 2.28, syncing was
represented with status out_of_sync.
New in version 2.10
share_id
body
string
The UUID of the share from which the share
instance was created.
availability_zone
body
string
The availability zone.
created_at
body
string
The date and time stamp when the share instance export location was
created.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2016-12-31T13:14:15-05:00.
replica_state
body
string
(Since API v2.11) The share replica state. Has
set value only when replication is used. List of possible values:
active, in_sync, out_of_sync, and error.
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.
The share instance status. A valid value is
available, error, creating, deleting, and
error_deleting.
access_rules_status
body
string
The share instance access rules status. A valid value is active,
error, or syncing. In versions prior to 2.28, syncing was
represented with status out_of_sync.
New in version 2.10
share_id
body
string
The UUID of the share from which the share
instance was created.
availability_zone
body
string
The availability zone.
created_at
body
string
The date and time stamp when the share instance export location was
created.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2016-12-31T13:14:15-05:00.
replica_state
body
string
(Since API v2.11) The share replica state. Has
set value only when replication is used. List of possible values:
active, in_sync, out_of_sync, and error.
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.
The UUID of the share instance that this
export location belongs to.
path
body
string
The export location path that should be used for
mount operation.
is_admin_only
body
boolean
Defines purpose of an export location. If set to
true, then it is expected to be used for service needs and by
administrators only. If it is set to false, then this export
location can be used by end users.
preferred
body
boolean
Drivers may use this field to identify which export locations
are most efficient and should be used preferentially by clients.
By default it is set to false value.
The UUID of the share instance that this
export location belongs to.
path
body
string
The export location path that should be used for
mount operation.
is_admin_only
body
boolean
Defines purpose of an export location. If set to
true, then it is expected to be used for service needs and by
administrators only. If it is set to false, then this export
location can be used by end users.
preferred
body
boolean
Drivers may use this field to identify which export locations
are most efficient and should be used preferentially by clients.
By default it is set to false value.
New in version 2.14
created_at
body
string
The date and time stamp when the share export location was
created.
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 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.
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.
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.
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.
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.
Each driver implementation determines which extra specification
keys it uses. For details, see Capabilities and Extra-Specs and documentation for your driver.
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.
consistency_group_support
body
string
Specifies the level of support for scheduling shares within consistency
groups if the pool supports this feature. Valid values are host,
pool and false. If host, shares within a consistency group
can span multiple storage pools belonging to a host#backend combination.
If pool, shares created within a given consistency group can only be
scheduled within that pool. If false, the pool cannot accept
scheduling consistency groups, and hence any shares belonging to
consistency groups.
New in version 2.4
timestamp
body
string
The date and time stamp when the API request was issued.
The ±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 UUID for the tenant for which you want to
show, update, or delete quotas. This ID is different from the
first tenant ID that you specify in the URI: That ID is for the
administrative tenant.
The Shared File Systems protocol of the share to
manage. A valid value is NFS, CIFS, GlusterFS, or
HDFS.
name (Optional)
body
string
The share name.
display_name (Optional)
body
string
The share name. The Shared File Systems API
supports the use of both name and display_name attributes,
which are inherited attributes from the Block Storage API.
share_type (Optional)
body
string
The share type name.
driver_options (Optional)
body
object
A set of one or more key and value pairs, as a
dictionary of strings, that describe driver options.
export_path
body
string
The share export path in the format appropriate
for the protocol: - NFS protocol. 10.0.0.1:/foo_path. For
example, 10.254.0.5:/shares/share-42033c24-0261-424f-abda-4fef2f6dbfd5. - CIFS protocol.
\\10.0.0.1\foo_name_of_cifs_share.
service_host
body
string
The manage-share service host in this format:
host@backend#POOL. - host. The host name for the back
end. - backend. The name of the back end. - POOL. The
pool name for the back end.
is_public (Optional)
body
boolean
(Since API v2.8) The level of visibility for the
share. Set to true to make share public. Set to false to
make it private. Default value is false.
description (Optional)
body
string
The share description.
display_description (Optional)
body
string
The share description. The Shared File Systems
API supports the use of both description and
display_description parameters, which are inherited attributes
from the Block Storage API.
{"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."}}
A list of export locations. For example, when a share server
has more than one network interface, it can have multiple export
locations. For newer API versions it is available in separate APIs.
See sections Share export locations
and Share instance export locations.
Deprecated in version 2.8
share_server_id
body
string
The UUID of the share server.
snapshot_id (Optional)
query
string
The UUID of the snapshot that was used to create
the share.
id
body
string
The UUID of the share.
size
body
integer
The share size, in GBs.
share_type
body
string
(Since API v2.6) The UUID of the share type. In
minor versions, this parameter is a share type name, as a string.
share_type_name
body
string
(Since API v2.6) The share type name. Minor
versions support only the share_type parameter where the share
type name is expected.
has_replicas
body
boolean
(Since API v2.11) Indicates whether a share has
replicas or not.
The ±hh:mm value, if included, returns the time zone as an
offset from UTC.
For example, 2015-08-27T09:49:58-05:00.
share_proto
body
string
The Shared File Systems protocol. A valid value
is NFS, CIFS, GlusterFS, HDFS, or CephFS.
CephFS supported is starting with API v2.13.
volume_type (Optional)
body
string
The volume type. The use of the volume_type
object is deprecated but supported. It is recommended that you use
the share_type object when you create a share type. When you
issue a create a share type request, you can submit a request body
with either a share_type or volume_type object. No matter
which object type you include in the request, the API creates both
a volume_type object and a share_type object. Both objects
have the same ID. When you issue a list share types request, the
response shows both share_types and volume_types objects.
source_cgsnapshot_member_id
body
string
(Since API v2.4) If the share was created with
consistency_group_id attribute, the snapshot member ID. The
corresponding consistency group must be created from a snapshot
with the current share as a member. Consistency groups and
snapshots are the part of the Shared File Systems experimental
API. For details, see Consistency groups and Consistency group snapshots.
Minimum Supported API Version: 1.0, 2.0
Last supported API Version: 2.6
Use this API to remove a share from the management of the Shared File
Systems service.
Administrator only. Use the policy.json file to grant permissions for this
action to other roles.
Share unmanage operation is not supported for shares that are created on top
of share servers (created with share networks). You should remove any
snapshots and share replicas before attempting to unmanage a share.
This API was removed in API version 2.7; please see share actions for the
new version of the API to utilize this feature.
The UUID for the tenant for which you want to
show, update, or delete quotas. This ID is different from the
first tenant ID that you specify in the URI: That ID is for the
administrative tenant.
If you specify the optional user_id query parameter, you get
the quotas for this user in the tenant. If you omit this parameter,
you get the quotas for the project.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The UUID for the tenant for which you want to
show, update, or delete quotas. This ID is different from the
first tenant ID that you specify in the URI: That ID is for the
administrative tenant.
user_id (Optional)
query
string
The UUID of the user. If you specify this query parameter,
you update the quotas for this user in the tenant.
If you omit this parameter, you update the quotas for the project.
If you specify the optional user_id query parameter, you get
the quotas for this user in the tenant. If you omit this parameter,
you get the quotas for the project.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The UUID for the tenant for which you want to
show, update, or delete quotas. This ID is different from the
first tenant ID that you specify in the URI: That ID is for the
administrative tenant.
user_id (Optional)
query
string
The UUID of the user. If you specify this query parameter,
you update the quotas for this user in the tenant.
If you omit this parameter, you update the quotas for the project.
If you specify the optional user_id query parameter, you update
the quotas for this user in the tenant. If you omit this parameter,
you update the quotas for the project.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The UUID for the tenant for which you want to
show, update, or delete quotas. This ID is different from the
first tenant ID that you specify in the URI: That ID is for the
administrative tenant.
user_id (Optional)
query
string
The UUID of the user. If you specify this query parameter,
you update the quotas for this user in the tenant.
If you omit this parameter, you update the quotas for the project.
quota_set
body
object
The quota_set object.
force (Optional)
body
boolean
Indicates whether to permit or deny the force-
update of a quota that is already used and the requested value
exceeds the configured quota. Set to True to permit the
force-update of the quota. Set to False to deny the force-
update of the quota.
gigabytes (Optional)
body
integer
The number of gigabytes for the tenant.
snapshots (Optional)
body
integer
The number of snapshots for the tenant.
snapshot_gigabytes (Optional)
body
integer
The number of gigabytes for the snapshots for the
tenant.
Deletes quotas for a tenant. The quota reverts to the default quota.
If you specify the optional user_id query parameter, you delete
the quotas for this user in the tenant. If you omit this parameter,
you delete the quotas for the project.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The UUID for the tenant for which you want to
show, update, or delete quotas. This ID is different from the
first tenant ID that you specify in the URI: That ID is for the
administrative tenant.
user_id (Optional)
query
string
The UUID of the user. If you specify this query parameter,
you update the quotas for this user in the tenant.
If you omit this parameter, you update the quotas for the project.
As an administrator, you can migrate a share with its data from one
location to another in a manner that is transparent to users and workloads.
Possible use cases for data migration include:
Bring down a physical storage device for maintenance without disrupting
workloads.
Modify the properties of a share.
Free up space in a thinly-provisioned back end.
Note
Share Migration APIs are part an the experimental feature
introduced in version 2.5. The APIs may change or be removed in further
versions of the Shared File Systems API. The changes are
documented within each API below. All experimental APIs require the
X-OpenStack-Manila-API-Experimental:True header to be
sent in the requests.
POST
/v2/{tenant_id}/shares/{share_id}/action
Migrate share (versions 2.5 to 2.14)
Migrates a share from one back end to another.
You can migrate a share from one back end to another but both back
ends must set the driver_handles_share_servers parameter to
False. If a share driver handles one of the back ends, this
action is not supported. You can configure a back end in the
manila.conf file.
The host pool of the destination back end, in
this format: host@backend#POOL. - host. The host name for
the destination back end. - backend. The name of the
destination back end. - POOL. The pool name for the
destination back end.
force_host_copy
body
boolean
Enables or disables generic host-based forced
migrations, which bypasses driver optimizations. Default value is
false.
POST
/v2/{tenant_id}/shares/{share_id}/action
Start Migration (Since version 2.15)
Initiates share migration. This API will initiate the share data copy to the
new host. The copy operation is non-disruptive.
The host pool of the destination back end, in
this format: host@backend#POOL. - host. The host name for
the destination back end. - backend. The name of the
destination back end. - POOL. The pool name for the
destination back end.
notify
body
string
Enables or disables notification of data copying completed
force_host_copy
body
boolean
Enables or disables generic host-based forced
migrations, which bypasses driver optimizations. Default value is
false.
POST
/v2/{tenant_id}/shares/{share_id}/action
Complete Migration (Since version 2.15)
Completes share migration. This API will initiate the switch-over from the
source to destination share. This operation is disruptive.
The host pool of the destination back end, in
this format: host@backend#POOL. - host. The host name for
the destination back end. - backend. The name of the
destination back end. - POOL. The pool name for the
destination back end.
notify
body
string
Enables or disables notification of data copying completed
force_host_copy
body
boolean
Enables or disables generic host-based forced
migrations, which bypasses driver optimizations. Default value is
false.
Consistency groups enable you to create snapshots at the exact same
point in time from multiple file system shares. For example, a
database might place its tables, logs, and configuration on
separate shares. To restore this database from a previous point in
time, it makes sense to restore the logs, tables, and configuration
together from the exact same point in time.
As an administrator, you can also reset the state of a consistency
group and force-delete a consistency group in any state. Use the
policy.json file to grant permissions for these actions to
other roles.
Note
Consistency groups APIs are part of an experimental feature introduced
in version 2.4. The APIs may change or be removed in further versions
of the Shared File Systems API. All experimental APIs require the
X-OpenStack-Manila-API-Experimental:True header to be sent in the
requests.
GET
/v2/{tenant_id}/consistency-groups
List consistency groups
Lists all consistency groups.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
(Admin only). Defines whether to list consistency groups for
all tenants. Set to 1 to list consistency groups for all
tenants. Set to 0 to list consistency groups only for the
current tenant.
limit (Optional)
query
integer
The maximum number of consistency groups to return.
offset (Optional)
query
integer
The offset to define start point of consistency
group listing.
(Admin only). Defines whether to list consistency groups for
all tenants. Set to 1 to list consistency groups for all
tenants. Set to 0 to list consistency groups only for the
current tenant.
limit (Optional)
query
integer
The maximum number of consistency groups to return.
offset (Optional)
query
integer
The offset to define start point of consistency
group listing.
The consistency group status. A valid value is
creating, available, error, deleting, or
error_deleting.
links
body
array
The consistency group links.
name
body
string
The consistency group name.
description
body
string
The consistency group description.
source_cgsnapshot_id
body
string
The consistency group snapshot ID. A valid value
is null or the ID of the consistency group snapshot, if the
consistency group was created from a snapshot.
created_at
body
string
The date and time stamp when the consistency group was created.
The consistency group status. A valid value is
creating, available, error, deleting, or
error_deleting.
links
body
array
The consistency group links.
name
body
string
The consistency group name.
description
body
string
The consistency group description.
source_cgsnapshot_id
body
string
The consistency group snapshot ID. A valid value
is null or the ID of the consistency group snapshot, if the
consistency group was created from a snapshot.
created_at
body
string
The date and time stamp when the consistency group was created.
{"consistency_group":{"status":"available","description":"My first CG.","links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/9397c191-8427-4661-a2e8-b23820dc01d4","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/9397c191-8427-4661-a2e8-b23820dc01d4","rel":"bookmark"}],"source_cgsnapshot_id":null,"created_at":"2015-09-16T16:50:31.000000","share_network_id":"f9b2e754-ac01-4466-86e1-5c569424754e","share_server_id":null,"host":"manila2@generic1#GENERIC1","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","share_types":["be27425c-f807-4500-a056-d00721db45cf"],"id":"9397c191-8427-4661-a2e8-b23820dc01d4","name":"cg1"}}
The consistency group snapshot ID. A valid value
is null or the ID of the consistency group snapshot, if the
consistency group was created from a snapshot.
{"consistency_group":{"share_types":["d2ad4f9d-cae3-4660-b0b6-58c06b385203"],"name":"my-cg1","share_network_id":"d8ae6799-2567-4a89-aafb-fa4424350d2b","description":"my first consistency group"}}
The consistency group status. A valid value is
creating, available, error, deleting, or
error_deleting.
links
body
array
The consistency group links.
name
body
string
The consistency group name.
description
body
string
The consistency group description.
source_cgsnapshot_id
body
string
The consistency group snapshot ID. A valid value
is null or the ID of the consistency group snapshot, if the
consistency group was created from a snapshot.
created_at
body
string
The date and time stamp when the consistency group was created.
{"consistency_group":{"status":"creating","description":"my first consistency group","links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/6f519a48-3183-46cf-a32f-41815f813986","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/consistency_groups/6f519a48-3183-46cf-a32f-41815f813986","rel":"bookmark"}],"source_cgsnapshot_id":null,"created_at":"2015-09-16T09:28:52.880949","share_network_id":"d8ae6799-2567-4a89-aafb-fa4424350d2b","host":null,"project_id":"16e1ab15c35a457e9c2b2aa189f544e1","share_types":["d2ad4f9d-cae3-4660-b0b6-58c06b385203"],"id":"6f519a48-3183-46cf-a32f-41815f813986","name":"my-cg1"}}
The UUID for the tenant for which you want to
show, update, or delete quotas. This ID is different from the
first tenant ID that you specify in the URI: That ID is for the
administrative tenant.
The consistency group status. A valid value is
creating, available, error, deleting, or
error_deleting.
links
body
array
The consistency group links.
name
body
string
The consistency group name.
description
body
string
The consistency group description.
source_cgsnapshot_id
body
string
The consistency group snapshot ID. A valid value
is null or the ID of the consistency group snapshot, if the
consistency group was created from a snapshot.
created_at
body
string
The date and time stamp when the consistency group was created.
You can create snapshots of consistency groups. To create a
snapshot, you specify the ID of the consistency group that you want
to snapshot. After you create a consistency group snapshot, you can
create a consistency group from it.
A consistency group snapshot can have member shares. To add a
member share, include the consistency_group_id parameter in the
create share request. This ID must match the ID of the consistency
group from which the consistency group snapshot was created. Then,
when you use consistency group snapshots to restore data, you can
easily determine which shares belong to a consistency group.
As an administrator, you can also reset the state of a consistency
group snapshot and force-delete a consistency group snapshot in any
state. Use the policy.json file to grant permissions for these
actions to other roles.
Note
Consistency group snapshot APIs are part of an experimental feature
introduced in version 2.4. The APIs may change or be removed in further
versions of the Shared File Systems API. All experimental APIs
require the X-OpenStack-Manila-API-Experimental:True header to be
sent in the requests.
GET
/v2/{tenant_id}/cgsnapshots
List consistency group snapshots
Lists all consistency group snapshots.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
The maximum number of consistency groups snapshots
to return.
offset (Optional)
query
integer
The offset to define start point of consistency
group snapshot listing.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list consistency group snapshots
for all tenants. Set to 1 to list consistency groups for all
tenants. Set to 0 to list consistency groups only for the
current tenant.
The maximum number of consistency groups snapshots
to return.
offset (Optional)
query
integer
The offset to define start point of consistency
group snapshot listing.
all_tenants (Optional)
query
boolean
(Admin only). Defines whether to list consistency group snapshots
for all tenants. Set to 1 to list consistency groups for all
tenants. Set to 0 to list consistency groups only for the
current tenant.
{"cgsnapshots":[{"status":"available","name":"snapshot_CG2","links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6","rel":"bookmark"}],"created_at":"2015-09-16T17:37:40.000000","consistency_group_id":"2d5c2600-ae67-4dff-b13c-a1c20b335e8e","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","id":"7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6","description":"Snapshot of CG2"},{"status":"available","name":"snapshot_cg1","links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5","rel":"bookmark"}],"created_at":"2015-09-16T17:34:15.000000","consistency_group_id":"9397c191-8427-4661-a2e8-b23820dc01d4","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","id":"b44c894d-4bec-47aa-b389-cc8c6f0044a5","description":"Snapshot of cg1"}]}
{"cgsnapshot":{"status":"available","name":"snapshot_cg1","links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5","rel":"bookmark"}],"created_at":"2015-09-16T17:34:15.000000","consistency_group_id":"9397c191-8427-4661-a2e8-b23820dc01d4","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","id":"b44c894d-4bec-47aa-b389-cc8c6f0044a5","description":"Snapshot of cg1"}}
{"cgsnapshot":{"status":"creating","name":"snapshot_cg1","links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/b44c894d-4bec-47aa-b389-cc8c6f0044a5","rel":"bookmark"}],"created_at":"2015-09-16T17:34:06.031997","consistency_group_id":"9397c191-8427-4661-a2e8-b23820dc01d4","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","id":"b44c894d-4bec-47aa-b389-cc8c6f0044a5","description":"Snapshot of cg1"}}
{"cgsnapshot":{"status":"available","name":"snapshot_CG2","links":[{"href":"http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6","rel":"self"},{"href":"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/cgsnapshot/7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6","rel":"bookmark"}],"created_at":"2015-09-16T17:37:40.000000","consistency_group_id":"2d5c2600-ae67-4dff-b13c-a1c20b335e8e","project_id":"16e1ab15c35a457e9c2b2aa189f544e1","id":"7e5c3ca7-d54b-438d-9a9c-c65ece6bc6c6","description":"Changed description: there is a snapshot of CG2"}}
