diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index f853694ced..59a7177444 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -14,6 +14,7 @@ Shared File Systems API .. include:: share-metadata.inc .. include:: share-actions.inc .. include:: snapshots.inc +.. include:: snapshot-instances.inc .. include:: share-networks.inc .. include:: security-services.inc .. include:: share-servers.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index e5099bd81f..fac550a16d 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -119,6 +119,12 @@ snapshot_id_path: in: path required: true type: string +snapshot_instance_id_path: + description: | + The UUID of the share snapshot instance. + in: path + required: true + type: string tenant_id: description: | The UUID for the tenant for which you want to @@ -447,6 +453,12 @@ share_type_query: in: query required: false type: string +snapshot_id_query: + description: | + The UUID of the share's base snapshot to filter the request based on. + in: query + required: false + type: string snapshot_id_share_response: description: | The UUID of the snapshot that was used to create @@ -2150,6 +2162,12 @@ preferred: required: true type: boolean min_version: 2.14 +progress: + description: | + The progress of the snapshot creation. + in: body + required: true + type: string project: description: | The UUID of the project to which access to the @@ -2825,8 +2843,7 @@ share_id_4: type: string share_instance_id_1: description: | - The UUID of the share instance that owns this - export location. + The UUID of the share instance. in: body required: true type: string @@ -3152,7 +3169,8 @@ size_2: type: integer snapshot_created_at: description: | - The date and time stamp when the snapshot was created. + The date and time stamp when the snapshot or snapshot instance was + created. The date and time stamp format is `ISO 8601 `_: @@ -3211,18 +3229,52 @@ snapshot_id: in: body required: true type: string -snapshot_id_query: - description: | - The UUID of the share's base snapshot to filter the request based on. - in: body - required: false - type: string snapshot_id_request: description: | The UUID of the share's base snapshot. in: body required: false type: string +snapshot_instance_id: + description: | + The UUID of the share snapshot instance. + in: body + required: false + type: string +snapshot_instance_id_response: + description: | + The UUID of the share snapshot instance. + in: body + required: true + type: string +snapshot_instance_status: + description: | + The snapshot instance status. A valid value is + ``available``, ``error``, ``creating``, ``deleting``, and + ``error_deleting``, ``restoring``, ``unmanage_starting``, + ``unmanage_error``, ``manage_starting``, ``manage_error``. + in: body + required: true + type: string +snapshot_instance_updated_at: + description: | + The date and time stamp when the snapshot instance was + updated. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + The ``±hh:mm`` value, if included, returns the time zone as an + offset from UTC. + + For example, ``2016-12-31T13:14:15-05:00``. + in: body + required: true + type: string snapshot_manage_share_id: description: | The UUID of the share that has snapshot which diff --git a/api-ref/source/samples/snapshot-instance-actions-reset-state-request.json b/api-ref/source/samples/snapshot-instance-actions-reset-state-request.json new file mode 100644 index 0000000000..f602ff8da0 --- /dev/null +++ b/api-ref/source/samples/snapshot-instance-actions-reset-state-request.json @@ -0,0 +1,5 @@ +{ + "reset_status": { + "status": "available" + } +} diff --git a/api-ref/source/samples/snapshot-instance-show-response.json b/api-ref/source/samples/snapshot-instance-show-response.json new file mode 100644 index 0000000000..c7d33c95f9 --- /dev/null +++ b/api-ref/source/samples/snapshot-instance-show-response.json @@ -0,0 +1,14 @@ +{ + "snapshot_instance": + { + "status": "available", + "share_id": "618599ab-09a1-432d-973a-c102564c7fec", + "share_instance_id": "8edff0cb-e5ce-4bab-aa99-afe02ed6a76a", + "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924", + "progress": "100%", + "created_at": "2017-08-04T00:44:52.000000", + "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd", + "provider_location": "/path/to/fake/snapshot/snapshot_d447de19_a6d3_40b3_ae9f_895c86798924_275516e8_c998_4e78_a41e_7dd3a03e71cd", + "updated_at": "2017-08-04T00:44:54.000000" + } +} diff --git a/api-ref/source/samples/snapshot-instances-list-response.json b/api-ref/source/samples/snapshot-instances-list-response.json new file mode 100644 index 0000000000..363e451b99 --- /dev/null +++ b/api-ref/source/samples/snapshot-instances-list-response.json @@ -0,0 +1,9 @@ +{ + "snapshot_instances": [ + { + "status": "available", + "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924", + "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd", + } + ] +} diff --git a/api-ref/source/samples/snapshot-instances-list-with-detail-response.json b/api-ref/source/samples/snapshot-instances-list-with-detail-response.json new file mode 100644 index 0000000000..0ead1e2c7e --- /dev/null +++ b/api-ref/source/samples/snapshot-instances-list-with-detail-response.json @@ -0,0 +1,15 @@ +{ + "snapshot_instances": [ + { + "status": "available", + "share_id": "618599ab-09a1-432d-973a-c102564c7fec", + "share_instance_id": "8edff0cb-e5ce-4bab-aa99-afe02ed6a76a", + "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924", + "progress": "100%", + "created_at": "2017-08-04T00:44:52.000000", + "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd", + "provider_location": "/path/to/fake/snapshot/snapshot_d447de19_a6d3_40b3_ae9f_895c86798924_275516e8_c998_4e78_a41e_7dd3a03e71cd", + "updated_at": "2017-08-04T00:44:54.000000" + } + ] +} diff --git a/api-ref/source/snapshot-instances.inc b/api-ref/source/snapshot-instances.inc new file mode 100644 index 0000000000..ca98787714 --- /dev/null +++ b/api-ref/source/snapshot-instances.inc @@ -0,0 +1,162 @@ +.. -*- rst -*- + +========================================== +Share snapshot instances (since API v2.19) +========================================== + +A share snapshot instance is an internal representation for a snapshot +of a share. A single snapshot can have multiple snapshot instances if +the parent share has multiple ``instances``. When a share is replicated +or is in the process of being migrated, it can live in multiple places +and each individual location is called an "instance", internally within +the Shared File Systems service. + +By default administrators can list, show information for and explicitly +set the state of share snapshot instances. Use the ``policy.json`` file +to grant permissions for these actions to other roles. + + +List share snapshot instances +============================= + +.. rest_method:: GET /v2/{tenant_id}/snapshot-instances + +Lists all share snapshot instances. + +Normal response codes: 200 +Error response codes: badRequest(400), unauthorized(401), forbidden(403) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - snapshot_id: snapshot_id_query + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: snapshot_instance_id_response + - snapshot_id: snapshot_id + - status: snapshot_instance_status + +Response example +---------------- + +.. literalinclude:: samples/snapshot-instances-list-response.json + :language: javascript + + +List share snapshot instances with details +========================================== + +.. rest_method:: GET /v2/{tenant_id}/snapshot-instances/detail + +Lists all share snapshot instances with details. + +Normal response codes: 200 +Error response codes: badRequest(400), unauthorized(401), forbidden(403) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - snapshot_id: snapshot_id_query + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: snapshot_instance_id_response + - snapshot_id: snapshot_id + - created_at: snapshot_created_at + - updated_at: snapshot_instance_updated_at + - status: snapshot_instance_status + - share_id: share_id + - share_instance_id: share_instance_id_1 + - progress: progress + - provider_location: snapshot_provider_location + +Response example +---------------- + +.. literalinclude:: samples/snapshot-instances-list-with-detail-response.json + :language: javascript + + +Show share snapshot instance details +==================================== + +.. rest_method:: GET /v2/{tenant_id}/snapshot-instances/{snapshot_instance_id} + +Shows details for a share snapshot instance. + +Normal response codes: 200 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - snapshot_instance_id: snapshot_instance_id_path + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: snapshot_instance_id_response + - snapshot_id: snapshot_id + - created_at: snapshot_created_at + - updated_at: snapshot_instance_updated_at + - status: snapshot_instance_status + - share_id: share_id + - share_instance_id: share_instance_id_1 + - progress: progress + - provider_location: snapshot_provider_location + +Response example +---------------- + +.. literalinclude:: samples/snapshot-instance-show-response.json + :language: javascript + + +Reset share snapshot instance state +=================================== + +.. rest_method:: POST /v2/{tenant_id}/snapshot-instances/{snapshot_instance_id}/action + +Administrator only. Explicitly updates the state of a share snapshot instance. + +Use the ``policy.json`` file to grant permissions for this action +to other roles. + +Normal response codes: 202 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404) + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - snapshot_instance_id: snapshot_instance_id_path + - status: snapshot_instance_status + +Request example +--------------- + +.. literalinclude:: samples/snapshot-instance-actions-reset-state-request.json + :language: javascript