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