Storage deletion & backup deletion policies.

Author: Antti Myyrä

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Server deletion now support deleting attached storages in CloudManager.
+- Backup deletion policies can be given when deleting servers and storages.
+
+----
+
 ## [2.0.0] - 2021-05-05
 
 Python 2 is no longer supported. This is a maintenance release without
@@ -90,7 +96,7 @@ Template updates.
 
 ----
 
-## [0.4.2] - 22 Feb 2018
+## [0.4.2] - 22 Feb 2018
 
 - Added missing zones and missing templates.
 - Also removed old template windows 2008, which is not supported any more.
@@ -248,7 +254,7 @@ Major update with new features related to UpCloud's API v1.2
 Move to X.Y.Z versioning and bump version from 0.1(.0) to 0.1.1
 
 - minor enchancement: Storage OS param can now take a UUID of a OS template. Useful if using custom OS templates.
-- bugfix: add cloud_manager to Server object during create_server. 
+- bugfix: add cloud_manager to Server object during create_server.
 - added MANIFEST.in, tox.in, setup.cfg and removed docs/html from git (built by mkdocs from md sources)
 - sublime project file and some readme.md improvements
 

README.md

@@ -145,6 +145,21 @@ server.stop_and_destroy()
 server.ensure_started()
 ```
 
+CloudManager offers mode fine-grained deletion options for servers as you can choose to delete storages and
+choose what happens to their backups when deleting the server. By default the storage and their backups are
+always preserved.
+
+Following example would delete all storages attached to a server, but would keep the latest backup
+of each storage if backups exist.
+
+```python
+
+from upcloud_api.storage import BackupDeletionPolicy
+
+manager.delete_server(uuid, delete_storages=True, backups=BackupDeletionPolicy.KEEP_LATEST)
+
+```
+
 ### Upgrade a Server
 
 ```python

docs/Server.md

@@ -114,7 +114,7 @@ server.remove_ip(IP)
 
 ```
 
-## Destroy
+## Delete
 
 Destroys the Server instance and its IP addresses. However, it does not destroy the Storages.
 
@@ -123,3 +123,21 @@ Destroys the Server instance and its IP addresses. However, it does not destroy
 server.destroy()
 
 ```
+
+## Delete with storages
+
+Storages attached to the server and storage backups can also be deleted when deleting the server through CloudManager.
+Backups can be deleted only when attached storages are also deleted. Default policy for backup deletions is
+`KEEP`, but `KEEP_LATEST` and `DELETE` are also supported. Options are configured through BackupDeletionPolicy enum
+under storage. Default behaviour for backups and storages is always to keep them.
+
+Following example deletes the storages, but keeps the latest existing backup(s). If no backup exists for the storage(s),
+nothing is left behind.
+
+```python
+
+from upcloud_api.storage import BackupDeletionPolicy
+
+manager.delete_server(uuid, delete_storages=True, backups=BackupDeletionPolicy.KEEP_LATEST)
+
+```

docs/Storage.md

@@ -71,7 +71,7 @@ storage.update(size=100, title="new title")
 
 ```
 
-## Destroy
+## Delete
 
 Warning: data loss is permanent.
 
@@ -81,6 +81,23 @@ storage.destroy()
 
 ```
 
+## Delete with backups
+
+Backup deletion policy can be specified when deleting a storage through CloudManager. Default policy is
+`KEEP`, so no backups are deleted, but `KEEP_LATEST` and `DELETE` are also supported. Options are configured
+through BackupDeletionPolicy enum under storage. Default behaviour for backups is always to keep them.
+
+Following example deletes the storage, but keeps the latest existing backup. If no backup exists for the storage,
+nothing is left behind.
+
+```python
+
+from upcloud_api.storage import BackupDeletionPolicy
+
+manager.delete_storage(uuid, backups=BackupDeletionPolicy.KEEP_LATEST)
+
+```
+
 ## Import
 
 Storages can be imported either by passing a URL or by uploading the file. Currently .iso, .raw and .img formats

docs/storage-mixin.md

@@ -12,6 +12,9 @@ manager = CloudManager("api-username", "password")
 manager.method()
 ```
 
+`BackupDeletionPolicy` describes wanted action on backups when deleting a storage or a server with its storages.
+Available policies are `KEEP`, `KEEP_LATEST` and `DELETE`.
+
 ## Methods
 
 ```python

upcloud_api/cloud_manager/server_mixin.py

@@ -1,12 +1,12 @@
 from upcloud_api.api import API
 from upcloud_api.ip_address import IPAddress
 from upcloud_api.server import Server
-from upcloud_api.storage import Storage
+from upcloud_api.storage import BackupDeletionPolicy, Storage
 
 
 class ServerManager:
     """
-    Functions for managing IP-addresses. Intended to be used as a mixin for CloudManager.
+    Functions for managing servers. Intended to be used as a mixin for CloudManager.
     """
 
     api: API
@@ -32,13 +32,13 @@ def get_servers(self, populate=False, tags_has_one=None, tags_has_all=None):
         request = '/server'
         if tags_has_all:
             tags_has_all = [str(tag) for tag in tags_has_all]
-            taglist = ':'.join(tags_has_all)
-            request = f'/server/tag/{taglist}'
+            tag_list = ':'.join(tags_has_all)
+            request = f'/server/tag/{tag_list}'
 
         if tags_has_one:
             tags_has_one = [str(tag) for tag in tags_has_one]
-            taglist = ','.join(tags_has_one)
-            request = f'/server/tag/{taglist}'
+            tag_list = ','.join(tags_has_one)
+            request = f'/server/tag/{tag_list}'
 
         servers = self.api.get_request(request)['servers']['server']
 
@@ -52,21 +52,21 @@ def get_servers(self, populate=False, tags_has_one=None, tags_has_all=None):
 
         return server_list
 
-    def get_server(self, UUID: str) -> Server:
+    def get_server(self, uuid: str) -> Server:
         """
         Return a (populated) Server instance.
         """
-        server, IPAddresses, storages = self.get_server_data(UUID)
+        server, ip_addresses, storages = self.get_server_data(uuid)
 
         return Server(
             server,
-            ip_addresses=IPAddresses,
+            ip_addresses=ip_addresses,
             storage_devices=storages,
             populated=True,
             cloud_manager=self,
         )
 
-    def get_server_by_ip(self, ip_address):
+    def get_server_by_ip(self, ip_address: str):
         """
         Return a (populated) Server instance by its IP.
 
@@ -152,23 +152,34 @@ def modify_server(self, uuid: str, **kwargs) -> Server:
             cloud_manager=self,
         )
 
-    def delete_server(self, uuid):
+    def delete_server(
+        self,
+        uuid: str,
+        delete_storages: bool = False,
+        backups: BackupDeletionPolicy = BackupDeletionPolicy.KEEP,
+    ):
         """
         DELETE '/server/UUID'. Permanently destroys the virtual machine.
 
-        DOES NOT remove the storage disks.
+        Does remove storage disks if delete_storages is defined as True.
+
+        Does remove backups of the attached storages if
 
         Returns an empty object.
         """
-        return self.api.delete_request(f'/server/{uuid}')
+        storages = '1' if delete_storages else '0'
+
+        return self.api.delete_request(
+            f'/server/{uuid}?storages={storages}&backups={backups.value}'
+        )
 
-    def get_server_data(self, UUID):
+    def get_server_data(self, uuid: str):
         """
         Return '/server/uuid' data in Python dict.
 
         Creates object representations of any IP-address and Storage.
         """
-        data = self.api.get_request(f'/server/{UUID}')
+        data = self.api.get_request(f'/server/{uuid}')
         server = data['server']
 
         # Populate subobjects

upcloud_api/cloud_manager/storage_mixin.py

@@ -2,7 +2,7 @@
 from typing import BinaryIO, Optional, Union
 
 from upcloud_api.api import API
-from upcloud_api.storage import Storage
+from upcloud_api.storage import BackupDeletionPolicy, Storage
 from upcloud_api.storage_import import StorageImport
 
 
@@ -84,11 +84,11 @@ def modify_storage(
         res = self._modify_storage(str(storage), size, title, backup_rule)
         return Storage(cloud_manager=self, **res['storage'])
 
-    def delete_storage(self, UUID):
+    def delete_storage(self, uuid: str, backups: BackupDeletionPolicy = BackupDeletionPolicy.KEEP):
         """
-        Destroy a Storage object.
+        Destroy a Storage object, and possibly some or all of its backups.
         """
-        return self.api.delete_request('/storage/' + UUID)
+        return self.api.delete_request(f'/storage/{uuid}?backups={backups.value}')
 
     def clone_storage(
         self, storage: Union[Storage, str], title: str, zone: str, tier=None

upcloud_api/storage.py

@@ -1,6 +1,18 @@
+from enum import Enum
+
 from upcloud_api.upcloud_resource import UpCloudResource
 
 
+class BackupDeletionPolicy(Enum):
+    """
+    Class representation of backup deletion policies used on storage deletions.
+    """
+
+    KEEP = 'keep'
+    KEEP_LATEST = 'keep_latest'
+    DELETE = 'delete'
+
+
 class Storage(UpCloudResource):
     """
     Class representation of UpCloud Storage instance.