Add support for snapshot_id field (#23334)

The DigitalOcean API v2 supports creating a block storage volume from
a previously-saved snapshot using a snapshot_id string. This module now
likewise supports creating a block storage volume using a valid
snapshot_id string.

When creating a block storage volume from a snapshot_id using the
DigitalOcean API, the region and size_gigabytes parameters are ignored.
Therefore, these parameters are likewise ignored when using this module.
However, as of this commit, they are still required fields. It may be
necessary to find some way to eliminate these requirements if the
snapshot_id parameter is included.

The DigitalOcean API v2 allows for creating a block storage volume from
a previously-saved snapshot using the snapshot_id parameter. If this
parameter is used, the region and size_gigabytes parameters are
disregarded. In order to avoid confusion, when the snapshot_id parameter
is included when creating a block storage volume using this module, the
region and block_size fields are overridden and changed to null values.
This should make it clear that these values are NOT being used if a
snapshot_id is present.

This module will still fail as before if neither the region/block_size
or snapshot_id is not present when creating a block storage volume.

Documentation has been updated to reflect these changes.

lib/ansible/modules/cloud/digital_ocean/digital_ocean_block_storage.py

@@ -37,7 +37,7 @@ options:
     required: true
   block_size:
     description:
-    - The size of the Block Storage volume in gigabytes. Required when command=create and state=present.
+    - The size of the Block Storage volume in gigabytes. Required when command=create and state=present. If snapshot_id is included, this will be ignored.
   volume_name:
     description:
     - The name of the Block Storage volume.
@@ -47,8 +47,12 @@ options:
     - Description of the Block Storage volume.
   region:
     description:
-    - The slug of the region where your Block Storage volume should be located in.
+    - The slug of the region where your Block Storage volume should be located in. If snapshot_id is included, this will be ignored.
     required: true
+  snapshot_id:
+    version_added: "2.5"
+    description:
+    - The snapshot id you would like the Block Storage volume created with. If included, region and block_size will be ignored and changed to null.
   droplet_id:
     description:
     - The droplet id you want to operate on. Required when command=attach.
@@ -60,6 +64,7 @@ options:
 notes:
   - Two environment variables can be used, DO_API_KEY and DO_API_TOKEN.
     They both refer to the v2 token.
+  - If snapshot_id is used, region and block_size will be ignored and changed to null.
 
 author:
     - "Harnek Sidhu (github: @harneksidhu)"
@@ -179,15 +184,23 @@ class DOBlockStorage(object):
             raise DOBlockStorageException(json['message'])
 
     def create_block_storage(self):
-        block_size = self.get_key_or_fail('block_size')
         volume_name = self.get_key_or_fail('volume_name')
-        region = self.get_key_or_fail('region')
+        snapshot_id = self.module.params['snapshot_id']
+        if snapshot_id:
+            self.module.params['block_size'] = None
+            self.module.params['region'] = None
+            block_size = None
+            region = None
+        else:
+            block_size = self.get_key_or_fail('block_size')
+            region = self.get_key_or_fail('region')
         description = self.module.params['description']
         data = {
             'size_gigabytes': block_size,
             'name': volume_name,
             'description': description,
-            'region': region
+            'region': region,
+            'snapshot_id': snapshot_id,
         }
         response = self.rest.post("volumes", data=data)
         status = response.status_code
@@ -259,10 +272,11 @@ def main():
             state=dict(choices=['present', 'absent'], required=True),
             command=dict(choices=['create', 'attach'], required=True),
             api_token=dict(aliases=['API_TOKEN'], no_log=True),
-            block_size=dict(type='int'),
+            block_size=dict(type='int', required=False),
             volume_name=dict(type='str', required=True),
             description=dict(type='str'),
-            region=dict(type='str', required=True),
+            region=dict(type='str', required=False),
+            snapshot_id=dict(type='str', required=False),
             droplet_id=dict(type='int'),
             timeout=dict(type='int', default=10),
         ),