Merge pull request #4 from merizrizal/3-implement-idempotency-in-the-vm-and-network-modules

3 implement idempotency in the vm and network modules

Author: merizrizal

README.md

@@ -22,6 +22,63 @@ target:
 
 Then write the playbook.yml file.
 
+Example of using the Network module.
+```
+---
+- name: ID Cloud Host Setup
+  hosts: idch
+  tasks:
+    - name: Create network VPC resource
+      merizrizal.idcloudhost.network:
+        api_key: "{{ your_api_key }}"
+        name: "{{ your_desired_network_name }}"
+        location: jkt02
+        # Since the default value of state is set to present, we may exclude it
+        state: present
+
+    - name: Delete network VPC resource
+      merizrizal.idcloudhost.network:
+        api_key: "{{ your_api_key }}"
+        name: "{{ your_desired_network_name }}"
+        location: jkt02
+        state: absent
+```
+To see the module documentation, run `ansible-doc merizrizal.idcloudhost.network`
+
+Example of using the VM module.
+```
+---
+- name: ID Cloud Host Setup
+  hosts: idch
+  tasks:
+    - name: Create VM resource
+      merizrizal.idcloudhost.vm:
+        api_key: "{{ your_api_key }}"
+        location: jkt02
+        network_name: "{{ your_desired_network_name }}"
+        name: "{{ your_desired_vm_name }}"
+        os_name: ubuntu
+        os_version: 24.04-lts
+        disks: 20
+        vcpu: 2
+        ram: 2048
+        username: admin
+        password: My4adminpass
+        # Since the default value of state is set to present, we may exclude it
+        state: present
+
+    - name: Delete VM resource
+      merizrizal.idcloudhost.vm:
+        api_key: "{{ your_api_key }}"
+        location: jkt02
+        name: "{{ your_desired_vm_name }}"
+        remove_public_ipv4: false
+        state: absent
+```
+To see the module documentation, run `ansible-doc merizrizal.idcloudhost.vm`
+
+### _The initial modules below will be removed later_
+
 Example for creating network resource.
 ```
 ---
@@ -34,7 +91,7 @@ Example for creating network resource.
         name: "{{ your_desired_network_name }}"
         location: jkt02
 ```
-To see the module documention, run `ansible-doc merizrizal.idcloudhost.create_network`
+To see the module documentation, run `ansible-doc merizrizal.idcloudhost.create_network`
 
 Example for creating a new VM and get its publid IP address.
 ```
@@ -75,7 +132,7 @@ Example for creating a new VM and get its publid IP address.
         location: jkt02
         vm_uuid: "{{ create_vm_result.uuid }}
 ```
-To see the module documention, run:
+To see the module documentation, run:
 - `ansible-doc merizrizal.idcloudhost.get_network`
 - `ansible-doc merizrizal.idcloudhost.create_vm`
 - `ansible-doc merizrizal.idcloudhost.get_public_ip`

merizrizal/idcloudhost/plugins/module_utils/base.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2025, Mei Rizal (@merizrizal) <meriz.rizal@gmail.com>
+# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
+from ansible.module_utils.basic import AnsibleModule
+
+requests = None
+
+
+class Base(object):
+    def __init__(self):
+        self._base_url = 'https://api.idcloudhost.com/v1'
+        self._endpoint_url = ''
+        self._api_key = ''
+        self._name = ''
+        self._location = ''
+        self._state = 'present'
+
+        self._module: AnsibleModule = None
+
+    def _ensure_requests(self):
+        try:
+            import requests
+            HAS_REQUESTS = True
+        except ImportError:
+            HAS_REQUESTS = False
+
+        if HAS_REQUESTS:
+            return requests
+
+        if self._module:
+            self._module.fail_json(
+                msg='Could not import the requests Python module',
+                results=[]
+            )
+
+    def _get_existing_network(self, name) -> dict:
+        url = f'{self._base_url}/{self._location}/network/networks'
+        url_headers = dict(
+            apikey=self._api_key
+        )
+
+        global requests
+        requests = self._ensure_requests()
+        response = requests.request('GET', url, headers=url_headers, timeout=360)
+        data = response.json()
+
+        if isinstance(data, list) and len(data) > 0:
+            for value in data:
+                if value['name'] == name:
+                    network = dict(
+                        uuid=value['uuid'],
+                        name=value['name'],
+                        subnet=value['subnet'],
+                        is_default=value['is_default']
+                    )
+
+                    return network
+
+        return dict()
+
+    def _get_public_ipv4(self, vm_uuid=None, private_ipv4=None) -> dict:
+        url = f'{self._base_url}/{self._location}/network/ip_addresses'
+        url_headers = dict(
+            apikey=self._api_key
+        )
+
+        global requests
+        requests = self._ensure_requests()
+        response = requests.request('GET', url, headers=url_headers, timeout=360)
+        data = response.json()
+
+        if isinstance(data, list) and len(data) > 0:
+            for value in data:
+                is_found = value['assigned_to_private_ip'] == private_ipv4
+                is_found = is_found or value['assigned_to'] == vm_uuid
+
+                if is_found:
+                    result = dict(
+                        uuid=value['uuid'],
+                        public_ipv4=value['address'],
+                        enabled=value['enabled']
+                    )
+
+                    return result
+
+            return dict()

merizrizal/idcloudhost/plugins/modules/create_network.py

@@ -22,15 +22,15 @@
         description: API of idcloudhost.com uses tokens to allow access to the API.
         required: true
         type: str
-    name:
-        description: Name of network that will be created.
-        required: true
-        type: str
     location:
         description: The location name of the network to which this network will be assigned.
         required: true
         type: str
         choices: [ jkt01, jkt02, jkt03, sgp01 ]
+    name:
+        description: Name of network that will be created.
+        required: true
+        type: str
 
 author:
     - Mei Rizal (@merizrizal) <meriz.rizal@gmail.com>
@@ -40,8 +40,8 @@
 - name: Create new VPC network
   merizrizal.idcloudhost.create_network:
     api_key: 2bnQkD6yOb7OkSwVCBXJSg1AHpfd99oY
-    name: my_vpc_network_01
     location: jkt01
+    name: my_vpc_network_01
 '''
 
 RETURN = r'''
@@ -109,7 +109,7 @@ def main(self):
                 error=data
             )
 
-            module.fail_json(msg='Create network fail', **result)
+            module.fail_json(msg='Failed to create the VPC network.', **result)
         else:
             result = dict(
                 uuid=data['uuid'],

merizrizal/idcloudhost/plugins/modules/create_vm.py

@@ -91,7 +91,7 @@
 
 EXAMPLES = r'''
 - name: Create new VM
-  merizrizal.idcloudhost.create_network:
+  merizrizal.idcloudhost.create_vm:
     api_key: 2bnQkD6yOb7OkSwVCBXJSg1AHpfd99oY
     location: jkt01
     network_uuid: "{{ get_from_get_network.uuid }}"
@@ -115,7 +115,7 @@
     type: str
     returned: success
 private_ipv4:
-    description: Private IPv4 of the created VM.
+    description: Private IPv4 address of the created VM.
     type: str
     returned: success
 billing_account:
@@ -131,7 +131,7 @@
 requests = None
 
 
-class CreateVM():
+class CreateVm():
     def __init__(self):
         self.base_url = 'https://api.idcloudhost.com/v1'
         self.endpoint_url = 'user-resource/vm'
@@ -194,7 +194,7 @@ def main(self):
                 error=f'Selected os_name is {os_name} then os_version must be one of {os_version_choices[os_name]}, got {os_version}'
             )
 
-            module.fail_json(msg='Create VM fail', **result)
+            module.fail_json(msg='Failed to create the VM.', **result)
 
         url = f'{self.base_url}/{self.location}/{self.endpoint_url}'
         url_headers = {
@@ -222,7 +222,7 @@ def main(self):
                 error=data
             )
 
-            module.fail_json(msg='Create VM fail', **data)
+            module.fail_json(msg='Failed to create the VM.', **data)
         else:
             result = dict(
                 uuid=data['uuid'],
@@ -235,4 +235,4 @@ def main(self):
 
 
 if __name__ == '__main__':
-    CreateVM().main()
+    CreateVm().main()

merizrizal/idcloudhost/plugins/modules/get_network.py

@@ -97,7 +97,7 @@ def main(self):
                 error=data
             )
 
-            module.fail_json(msg='Get network fail', **result)
+            module.fail_json(msg='Failed to get the VPC network.', **result)
         else:
             for value in data:
                 if value['is_default']:

merizrizal/idcloudhost/plugins/modules/get_public_ip.py

@@ -72,7 +72,7 @@
     type: bool
     returned: success, when private_ipv4 is selected
 assigned_to_private_ip:
-    description: On which private Ipv4 this public IPv4 is assigned.
+    description: On which private IPv4 address this public IPv4 address is assigned.
     type: bool
     returned: success, when vm_uuid is selected
 '''
@@ -132,7 +132,7 @@ def main(self):
                 error=data
             )
 
-            module.fail_json(msg='Get public IPv4 fail', **result)
+            module.fail_json(msg='Failed to get the public IPv4 address.', **result)
         else:
             result = dict(
                 error='Public IPv4 address is not found'
@@ -156,7 +156,7 @@ def main(self):
 
                     module.exit_json(**result)
 
-            module.fail_json(msg='Get public IPv4 fail', **result)
+            module.fail_json(msg='Failed to get the public IPv4 address', **result)
 
 
 if __name__ == '__main__':