From d5b7f5228cc7002ebe5df4a03cd88f7798e1a73e Mon Sep 17 00:00:00 2001 From: hamistao Date: Tue, 11 Jun 2024 18:41:49 -0300 Subject: [PATCH] doc/source: Add documentation for added features Signed-off-by: hamistao --- doc/source/storage-pools.rst | 53 ++++++++++++++++++++++++++++++++---- 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/doc/source/storage-pools.rst b/doc/source/storage-pools.rst index 02f61b8c..520f719e 100644 --- a/doc/source/storage-pools.rst +++ b/doc/source/storage-pools.rst @@ -13,18 +13,22 @@ Storage Pool objects object that is returned from `GET /1.0/storage-pools/` and then the associated methods that are then available at the same endpoint. -There are also :py:class:`~pylxd.models.storage_pool.StorageResource` and -:py:class:`~pylxd.models.storage_pool.StorageVolume` objects that represent the -storage resources endpoint for a pool at `GET -/1.0/storage-pools//resources` and a storage volume on a pool at `GET -/1.0/storage-pools//volumes//`. Note that these should be -accessed from the storage pool object. For example: +There are also :py:class:`~pylxd.models.storage_pool.StorageResource`, +:py:class:`~pylxd.models.storage_pool.StorageVolume` and +:py:class:`~pylxd.models.storage_pool.StorageVolumeSnapshot` objects that +represent, respectively, the storage resources endpoint for a pool at +`GET /1.0/storage-pools//resources`,a storage volume on a pool at +`GET /1.0/storage-pools//volumes//` and a custom volume snapshot +at `GET /1.0/storage-pools//volumes///snapshots/`. +Note that these should be accessed from the storage pool object. For example: .. code:: python client = pylxd.Client() storage_pool = client.storage_pools.get('poolname') + resources = storage_pool.resources.get() storage_volume = storage_pool.volumes.get('custom', 'volumename') + snapshot = storage_volume.snapshots.get('snap0') .. note:: For more details of the LXD documentation concerning storage pools @@ -137,10 +141,47 @@ following methods are available: changes to the LXD server. - `delete` - delete a storage volume object. Note that the object is, therefore, stale after this action. + - `restore_from` - Restore the volume from a snapshot using the snapshot name. .. note:: `raw_put` and `raw_patch` are availble (but not documented) to allow putting and patching without syncing the object back. +Storage Volume Snapshots +------------------------ + +Storage Volume Snapshots are represented as `StorageVolumeSnapshot` objects and +stored in `StorageVolume` objects and represent snapshots of custom storage volumes. +On the `pylxd` API they are accessed from a storage volume object that, in turn, +is accessed from a storage pool object: + +.. code:: Python + + storage_pool = client.storage_pools.get('pool1') + volumes = storage_pool.volumes.all() + custom_volume = storage_pool.volumes.get('custom', 'vol1') + a_snapshot = custom_volume.snapshots.get('snap0') + +Methods available on `.snapshots` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following methods are accessed from the `snapshots` attribute on the `StorageVolume` object: + + - `all` - Get all the snapshots from the storage volume. + - `get` - Get a single snapshot using its name. + - `create` - Take a snapshot on the current stage of the storage volume. The new snapshot's + name and expiration date can be set, default name is in the format "snapX". + - `exists` - Returns True if a storage volume snapshot with the given name exists, returns False otherwise. + +Methods available on the storage snapshot object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once in possession of a `StorageVolumeSnapshot` object from the `pylxd` API via `volume.snapshots.get()`, +the following methods are available: + + - `restore` - Restore the volume from the snapshot. + - `delete` - Delete the snapshot. Note that the object is, therefore, stale after this action. + - `rename` - Renames the snapshot. The endpoints that reference this snapshot will change accordingly. + .. links .. _LXD Storage Pools: https://documentation.ubuntu.com/lxd/en/latest/storage/