1.. -*- rst -*-
2
3Volume snapshots (snapshots)
4============================
5
6A snapshot is a point-in-time copy of the data that a volume
7contains.
8
9When you create, list, or delete snapshots, these status values are
10possible:
11
12**Snapshot statuses**
13
14+----------------+---------------------------------------------+
15| Status         | Description                                 |
16+----------------+---------------------------------------------+
17| creating       | The snapshot is being created.              |
18+----------------+---------------------------------------------+
19| available      | The snapshot is ready to use.               |
20+----------------+---------------------------------------------+
21| backing-up     | The snapshot is being backed up.            |
22+----------------+---------------------------------------------+
23| deleting       | The snapshot is being deleted.              |
24+----------------+---------------------------------------------+
25| error          | A snapshot creation error occurred.         |
26+----------------+---------------------------------------------+
27| deleted        | The snapshot has been deleted.              |
28+----------------+---------------------------------------------+
29| unmanaging     | The snapshot is being unmanaged.            |
30+----------------+---------------------------------------------+
31| restoring      | The snapshot is being restored to a volume. |
32+----------------+---------------------------------------------+
33| error_deleting | A snapshot deletion error occurred.         |
34+----------------+---------------------------------------------+
35
36
37List snapshots and details
38~~~~~~~~~~~~~~~~~~~~~~~~~~
39
40.. rest_method::  GET /v3/{project_id}/snapshots/detail
41
42Lists all Block Storage snapshots, with details, that the project can access,
43since v3.31 if non-admin users specify invalid filters in the url, API will
44return bad request.
45
46
47Normal response codes: 200
48
49Error response codes: badRequest(400)
50
51
52Request
53-------
54
55.. rest_parameters:: parameters.yaml
56
57   - project_id: project_id_path
58   - all_tenants: all-tenants
59   - sort: sort
60   - limit: limit
61   - offset: offset
62   - marker: marker
63   - with_count: with_count
64
65
66Response Parameters
67-------------------
68
69.. rest_parameters:: parameters.yaml
70
71   - status: status_2
72   - os-extended-snapshot-attributes:progress: os-extended-snapshot-attributes:progress
73   - description: description_8
74   - created_at: created_at
75   - name: name
76   - user_id: user_id_2
77   - volume_id: volume_id
78   - os-extended-snapshot-attributes:project_id: os-extended-snapshot-attributes:project_id
79   - size: size
80   - id: id
81   - metadata: metadata
82   - count: count
83
84Response Example
85----------------
86
87.. literalinclude:: ./samples/snapshots-list-detailed-response.json
88   :language: javascript
89
90
91Create a snapshot
92~~~~~~~~~~~~~~~~~
93
94.. rest_method::  POST /v3/{project_id}/snapshots
95
96Creates a volume snapshot, which is a point-in-time, complete copy of a volume.
97You can create a volume from a snapshot.
98
99Normal response codes: 202
100
101
102Request
103-------
104
105.. rest_parameters:: parameters.yaml
106
107   - project_id: project_id_path
108   - snapshot: snapshot_1
109   - volume_id: volume_id
110   - name: name_12
111   - description: description_4
112   - force: force
113   - metadata: metadata_7
114
115Request Example
116---------------
117
118.. literalinclude:: ./samples/snapshot-create-request.json
119   :language: javascript
120
121Response Parameters
122-------------------
123
124.. rest_parameters:: parameters.yaml
125
126   - status: status_2
127   - description: description_8
128   - created_at: created_at
129   - name: name_12
130   - snapshot: snapshot_1
131   - user_id: user_id_2
132   - volume_id: volume_id
133   - metadata: metadata
134   - id: id_4
135   - size: size
136   - updated_at: updated_at
137
138Response Example
139----------------
140
141.. literalinclude:: ./samples/snapshot-create-response.json
142   :language: javascript
143
144
145List accessible snapshots
146~~~~~~~~~~~~~~~~~~~~~~~~~
147
148.. rest_method::  GET /v3/{project_id}/snapshots
149
150Lists all Block Storage snapshots, with summary information,
151that the project can access, since v3.31 if non-admin users
152specify invalid filters in the url, API will return bad request.
153
154
155Normal response codes: 200
156
157Error response codes: badRequest(400)
158
159
160Request
161-------
162
163.. rest_parameters:: parameters.yaml
164
165   - project_id: project_id_path
166   - all_tenants: all-tenants
167   - sort: sort
168   - limit: limit
169   - offset: offset
170   - marker: marker
171   - with_count: with_count
172
173
174Response Parameters
175-------------------
176
177.. rest_parameters:: parameters.yaml
178
179   - status: status_2
180   - description: description_8
181   - created_at: created_at
182   - name: name
183   - user_id: user_id_2
184   - volume_id: volume_id
185   - metadata: metadata
186   - id: id
187   - size: size
188   - count: count
189
190Response Example
191----------------
192
193.. literalinclude:: ./samples/snapshots-list-response.json
194   :language: javascript
195
196
197Show a snapshot's metadata
198~~~~~~~~~~~~~~~~~~~~~~~~~~
199
200.. rest_method::  GET /v3/{project_id}/snapshots/{snapshot_id}/metadata
201
202Shows metadata for a snapshot.
203
204
205Normal response codes: 200
206
207
208Request
209-------
210
211.. rest_parameters:: parameters.yaml
212
213   - project_id: project_id_path
214   - snapshot_id: snapshot_id_path
215
216
217Response Parameters
218-------------------
219
220.. rest_parameters:: parameters.yaml
221
222   - status: status_2
223   - os-extended-snapshot-attributes:progress: os-extended-snapshot-attributes:progress
224   - description: description_8
225   - created_at: created_at
226   - name: name
227   - snapshot: snapshot_1
228   - volume_id: volume_id
229   - os-extended-snapshot-attributes:project_id: os-extended-snapshot-attributes:project_id
230   - size: size
231   - id: id
232   - metadata: metadata
233
234Response Example
235----------------
236
237.. literalinclude:: ./samples/snapshot-metadata-show-response.json
238   :language: javascript
239
240
241Create a snapshot's metadata
242~~~~~~~~~~~~~~~~~~~~~~~~~~~~
243
244.. rest_method::  POST /v3/{project_id}/snapshots/{snapshot_id}/metadata
245
246Updates metadata for a snapshot.
247
248Creates or replaces metadata items that match keys. Does not modify items that
249are not in the request.
250
251
252Normal response codes: 200
253
254
255Request
256-------
257
258.. rest_parameters:: parameters.yaml
259
260   - project_id: project_id_path
261   - snapshot_id: snapshot_id_path
262   - metadata: metadata
263
264Request Example
265---------------
266
267.. literalinclude:: ./samples/snapshot-metadata-create-request.json
268   :language: javascript
269
270Response Parameters
271-------------------
272
273.. rest_parameters:: parameters.yaml
274
275   - metadata: metadata
276
277Response Example
278----------------
279
280.. literalinclude:: ./samples/snapshot-metadata-create-response.json
281   :language: javascript
282
283Update a snapshot's metadata
284~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285
286.. rest_method::  PUT /v3/{project_id}/snapshots/{snapshot_id}/metadata
287
288Replaces all the snapshot's metadata with the key-value pairs in the request.
289
290
291Normal response codes: 200
292
293
294Request
295-------
296
297.. rest_parameters:: parameters.yaml
298
299   - project_id: project_id_path
300   - snapshot_id: snapshot_id_path
301   - metadata: metadata
302
303Request Example
304---------------
305
306.. literalinclude:: ./samples/snapshot-metadata-update-request.json
307   :language: javascript
308
309
310Response Parameters
311-------------------
312
313.. rest_parameters:: parameters.yaml
314
315   - metadata: metadata
316
317Response Example
318----------------
319
320.. literalinclude:: ./samples/snapshot-metadata-update-response.json
321   :language: javascript
322
323
324Show a snapshot's details
325~~~~~~~~~~~~~~~~~~~~~~~~~
326
327.. rest_method::  GET /v3/{project_id}/snapshots/{snapshot_id}
328
329Shows details for a snapshot.
330
331
332Normal response codes: 200
333
334
335Request
336-------
337
338.. rest_parameters:: parameters.yaml
339
340   - project_id: project_id_path
341   - snapshot_id: snapshot_id_path
342
343
344Response Parameters
345-------------------
346
347.. rest_parameters:: parameters.yaml
348
349   - status: status_2
350   - os-extended-snapshot-attributes:progress: os-extended-snapshot-attributes:progress
351   - description: description_8
352   - created_at: created_at
353   - name: name
354   - snapshot: snapshot_1
355   - user_id: user_id_2
356   - volume_id: volume_id
357   - os-extended-snapshot-attributes:project_id: os-extended-snapshot-attributes:project_id
358   - size: size
359   - id: id
360   - metadata: metadata
361
362Response Example
363----------------
364
365.. literalinclude:: ./samples/snapshot-show-response.json
366   :language: javascript
367
368
369Update a snapshot
370~~~~~~~~~~~~~~~~~
371
372.. rest_method::  PUT /v3/{project_id}/snapshots/{snapshot_id}
373
374Updates a snapshot.
375
376
377Normal response codes: 200
378
379
380Request
381-------
382
383.. rest_parameters:: parameters.yaml
384
385   - project_id: project_id_path
386   - snapshot_id: snapshot_id_path
387   - snapshot: snapshot_1
388   - description: description_4
389   - name: name
390
391Request Example
392---------------
393
394.. literalinclude:: ./samples/snapshot-update-request.json
395   :language: javascript
396
397
398
399Response Parameters
400-------------------
401
402.. rest_parameters:: parameters.yaml
403
404   - status: status_2
405   - description: description_8
406   - created_at: created_at
407   - name: name
408   - snapshot: snapshot_1
409   - id: id
410   - size: size
411   - volume_id: volume_id
412   - user_id: user_id_2
413   - metadata: metadata
414
415Response Example
416----------------
417
418.. literalinclude:: ./samples/snapshot-update-response.json
419   :language: javascript
420
421
422Delete a snapshot
423~~~~~~~~~~~~~~~~~
424
425.. rest_method::  DELETE /v3/{project_id}/snapshots/{snapshot_id}
426
427Deletes a snapshot.
428
429Normal response codes: 202
430
431
432Request
433-------
434
435.. rest_parameters:: parameters.yaml
436
437   - project_id: project_id_path
438   - snapshot_id: snapshot_id_path
439
440
441Show a snapshot's metadata for a specific key
442~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
443
444.. rest_method::  GET /v3/{project_id}/snapshot/{snapshot_id}/metadata/{key}
445
446Shows metadata for a snapshot for a specific key.
447
448Normal response codes: 200
449
450
451Request
452-------
453
454.. rest_parameters:: parameters.yaml
455
456   - project_id: project_id_path
457   - snapshot_id: snapshot_id_path
458   - key: key_2
459
460
461Response Parameters
462-------------------
463
464.. rest_parameters:: parameters.yaml
465
466   - meta: meta_1
467
468Response Example
469----------------
470
471.. literalinclude:: ./samples/snapshot-metadata-show-key-response.json
472   :language: javascript
473
474
475
476Delete a snapshot's metadata
477~~~~~~~~~~~~~~~~~~~~~~~~~~~~
478
479.. rest_method::  DELETE /v3/{project_id}/snapshots/{snapshot_id}/metadata/{key}
480
481Deletes metadata for a snapshot.
482
483Normal response codes: 200
484
485
486Request
487-------
488
489.. rest_parameters:: parameters.yaml
490
491   - project_id: project_id_path
492   - snapshot_id: snapshot_id_path
493   - key: key_1
494
495
496Update a snapshot's metadata for a specific key
497~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
498
499.. rest_method::  PUT /v3/{project_id}/snapshots/{snapshot_id}/metadata/{key}
500
501Update metadata for a snapshot for a specific key.
502
503Normal response codes: 200
504
505
506Request
507-------
508
509.. rest_parameters:: parameters.yaml
510
511   - project_id: project_id_path
512   - snapshot_id: snapshot_id_path
513   - key: key_3
514   - meta: meta_1
515
516Request Example
517---------------
518
519.. literalinclude:: ./samples/snapshot-metadata-update-key-request.json
520   :language: javascript
521
522Response Parameters
523-------------------
524
525.. rest_parameters:: parameters.yaml
526
527   - meta: meta_1
528
529Response Example
530----------------
531
532.. literalinclude:: ./samples/snapshot-metadata-update-key-response.json
533   :language: javascript
534