[ignore] Updated the ND rest, backup and restore module logic and documentation

Author: sajagana

plugins/httpapi/nd.py

@@ -352,7 +352,7 @@ def send_file_request(self, method, path, file=None, data=None, remote_path=None
 
             mp_encoder = MultipartEncoder(fields=fields)
             multiheader = {"Content-Type": mp_encoder.content_type, "Accept": "*/*", "Accept-Encoding": "gzip, deflate, br"}
-            self.connection.queue_message("info", "send_file_request() - connection.send({0}, {1}, {2}, {3})".format(path, method, fields, multiheader))
+            self.connection.queue_message("debug", "send_file_request() - connection.send({0}, {1}, {2}, {3})".format(path, method, fields, multiheader))
             response, rdata = self.connection.send(path, mp_encoder.to_string(), method=method, headers=multiheader)
         except Exception as e:
             self.error = dict(code=self.status, message="ND HTTPAPI MultipartEncoder Exception: {0} - {1} ".format(e, traceback.format_exc()))

plugins/module_utils/nd.py

@@ -224,21 +224,20 @@ def __init__(self, module):
         self.url = None
         self.httpapi_logs = list()
         self.connection = None
-        self.version = None
+        self._version = None
 
         # Set Connection plugin
         self.set_connection()
 
-        # Set ND version
-        self.set_version()
-
         if self.module._debug:
             self.module.warn("Enable debug output because ANSIBLE_DEBUG was set.")
             self.params["output_level"] = "debug"
 
-    def set_version(self):
-        if self.version is None and self.connection:
-            self.version = self.connection.get_version("nd")
+    @property
+    def version(self):
+        if self._version is None and self.connection:
+            self._version = self.connection.get_version("nd")
+        return self._version
 
     def set_connection(self):
         if self.connection is None:

plugins/modules/nd_backup.py

@@ -35,8 +35,7 @@
   file_location:
     description:
     - The download path and file name for a backup.
-    - When O(file_location) is specified, the backup will be created and automatically downloaded to the local machine at the designated path.
-    - Automatic download is not supported for the ND versions 3.2.1 and later. Use a following task with O(state=download) to download the backup.
+    - When O(file_location) is specified, the backup will be created and automatically downloaded to the designated path.
     aliases: [ local_path, path ]
     type: str
   backup_key:
@@ -58,18 +57,18 @@
   remote_location:
     description:
     - The name of the remote storage location.
-    - Use O(remote_location="") to create local backup.
+    - Use O(remote_location="") to create ND local backup.
     - This parameter is only supported on ND v3.2.1 and later.
     default: ""
     type: str
   state:
     description:
-    - Use O(state=backup) for creating and downloading a backup of the cluster config for the ND versions less than 3.2.1.
-    - Use O(state=backup) to create a cluster configuration backup. Automatic download is not supported for the ND versions 3.2.1 and later.
-    - After creation, use O(state=download) to download the backup file.
-    - Use O(state=download) downloading a backup to the local machine, the O(state=download) is only supported on ND v3.2.1 and later.
     - Use O(state=query) for listing all the backed up files.
     - Use O(state=absent) for deleting a backup job.
+    - For ND versions earlier than v3.2.1, use O(state=backup) for creating and automatically downloading a backup of the cluster config.
+    - For ND versions later than v3.2.1, use O(state=backup) for creating a cluster configuration backup,
+      use O(state=download) for downloading a backup to the designated path.
+    - O(state=download) is only supported on ND v3.2.1 and later.
     type: str
     choices: [ backup, download, query, absent ]
     default: backup
@@ -79,7 +78,7 @@
 """
 
 EXAMPLES = r"""
-- name: Create a backup for ND versions < 3.2.1
+- name: Create a backup and automatically download it to file_location for ND versions < 3.2.1
   cisco.nd.nd_backup:
     name: nexus
     encryption_key: testtest
@@ -93,20 +92,20 @@
     remote_location: remote_machine
     state: backup
 
-- name: Create a local backup for ND versions >= 3.2.1
+- name: Create a ND local backup for ND versions >= 3.2.1
   cisco.nd.nd_backup:
     name: nexus
     encryption_key: testtest1
     state: backup
 
-- name: Create a backup and download it to the local machine for ND versions >= 3.2.1
+- name: Create a backup and download it to the designated path for ND versions >= 3.2.1
   cisco.nd.nd_backup:
     name: nexus
     file_location: ./nexus.tgz
     encryption_key: testtest1
     state: backup
 
-- name: Download a local/remote backup for ND versions >= 3.2.1
+- name: Download an existing backup for ND versions >= 3.2.1
   cisco.nd.nd_backup:
     name: nexus
     state: download
@@ -174,8 +173,8 @@ def main():
     backups = nd.query_obj("/api/config/class/exports") if nd.version < "3.2.1" else nd.query_obj(path)
 
     if nd.version < "3.2.1":
-        if not file_location and state in ["backup", "download"]:
-            nd.fail_json("Parameter 'file_location' is required when state is 'backup|download' for ND versions < 3.2.1.")
+        if not file_location and state in ["backup"]:
+            nd.fail_json("Parameter 'file_location' is required when state is 'backup' for ND versions < 3.2.1.")
 
         if encryption_key is not None and len(encryption_key) < 8:
             nd.fail_json("Please provide a minimum of 8 characters for the encryption key.")
@@ -255,6 +254,8 @@ def main():
         if not module.check_mode:
             response = nd.request("{0}/{1}?action=download".format(path, name), method="GET", data=None, output_format="raw")
             write_file(module, file_location, to_bytes(response))
+    elif state == "download" and nd.version < "3.2.1":
+        nd.fail_json("The O(state=download) is only supported on ND v3.2.1 and later.")
 
     nd.exit_json()
 

plugins/modules/nd_backup_restore.py

@@ -175,7 +175,13 @@ def main():
 
     if state == "absent":
         if not module.check_mode:
-            nd.request("{0}/{1}".format(import_path, restore_key) if nd.version < "3.2.1" else import_path, method="DELETE")
+            if nd.version < "3.2.1":
+                if restore_key is None and name is None:
+                    nd.fail_json("Please provide a valid O(restore_key) or O(name) to delete a restored job.")
+                nd.request("{0}/{1}".format(import_path, restore_key), method="DELETE")
+            else:
+                nd.request(import_path, method="DELETE")
+
         nd.existing = {}
 
     elif state == "restore":

plugins/modules/nd_rest.py

@@ -48,11 +48,16 @@
     - The file path containing the body of the HTTP request.
     type: path
     aliases: [ config_file ]
-  ignore_previous_state:
+  suppress_previous:
     description:
+    - If enabled, a GET call to check previous object state will not be sent before a PUT, PATCH and DELETE update to ND.
+    - This causes the previous return value to be empty.
+    - The previous state of the object will not be checked and PUT, PATCH and DELETE update calls to ND will contain all properties specified in the task.
     - Certain ND API endpoints do not support the GET method for querying the current status of an object before updating or deleting it.
-    - Use O(ignore_previous_state=true) to avoid making unsupported GET requests to such ND API endpoints.
+    - Use O(suppress_previous=true) to avoid making unsupported GET requests to such ND API endpoints.
     type: bool
+    aliases: [ no_previous, ignore_previous ]
+
 extends_documentation_fragment:
 - cisco.nd.modules
 - cisco.nd.check_mode
@@ -217,7 +222,7 @@ def main():
         ),
         content=dict(type="raw", aliases=["payload"]),
         file_path=dict(type="path", aliases=["config_file"]),
-        ignore_previous_state=dict(type="bool"),
+        suppress_previous=dict(type="bool", aliases=["no_previous", "ignore_previous"]),
     )
 
     module = AnsibleModule(
@@ -228,7 +233,7 @@ def main():
     content = module.params.get("content")
     path = module.params.get("path")
     file_path = module.params.get("config_file")
-    ignore_previous_state = module.params.get("ignore_previous_state")
+    suppress_previous = module.params.get("suppress_previous")
 
     nd = NDModule(module)
 
@@ -257,11 +262,11 @@ def main():
     method = nd.params.get("method").upper()
 
     # Append previous state of the object
-    # Purpose of ignore_previous_state:
-    # The ignore_previous_state was introduced because querying existing objects via the GET method on the /api/config/routes endpoint is not supported.
-    # To avoid the /api/config/routes GET call ignore_previous_state was introduced.
+    # Purpose of suppress_previous:
+    # The suppress_previous was introduced because querying existing objects via the GET method on the /api/config/routes endpoint is not supported.
+    # To avoid the /api/config/routes GET call suppress_previous was introduced.
     # Additionally, POST and DELETE methods return None for the /api/config/routes.
-    if method in ("PUT", "DELETE", "PATCH") and not ignore_previous_state:
+    if method in ("PUT", "DELETE", "PATCH") and not suppress_previous:
         nd.existing = nd.previous = sanitize(nd.query_obj(path, ignore_not_found_error=True), ND_REST_KEYS_TO_SANITIZE)
     nd.result["previous"] = nd.previous
 

tests/integration/targets/nd_backup/tasks/main.yml

@@ -94,7 +94,7 @@
           - add_local_backup.current.name == "localbackup"
           - add_local_backup.current.path == "localbackup.tar.gz"
           - add_local_backup.current.schedule == ""
-          - add_local_backup.current.endTime == "0001-01-01T00:00:00Z"
+          - add_local_backup.current.endTime is defined
           - add_local_backup.current.startTime is defined
           - add_local_backup.current.status == "in-progress"
           - add_local_backup.current.type == "config-only"
@@ -563,6 +563,16 @@
       ignore_errors: true
       register: delete_wrong_key_nexus
 
+    - name: Negative test download backup with state=download
+      cisco.nd.nd_backup:
+        output_level: debug
+        name: nexus
+        encryption_key: Testtest123
+        file_location: "{{ role_path }}/backups/nexus2_{{ ansible_host }}.tgz"
+        state: download
+      ignore_errors: true
+      register: nt_download_backup
+
     - name: Verify all assertions
       ansible.builtin.assert:
         that:
@@ -590,7 +600,9 @@
           - query_duplicate_nexus.msg == delete_duplicate_nexus.msg == "Multiple backups with the name 'nexus' found. Please provide a backup key for the corresponding backup."
           - delete_wrong_key_nexus.msg == "Provided key for the backup 'nexus' not found. Please provide a valid backup key by querying all the backups and looking up the desired backup key."
           - add_nexus_without_file_location is not changed
-          - add_nexus_without_file_location.msg == "Parameter 'file_location' is required when state is 'backup|download' for ND versions < 3.2.1."
+          - add_nexus_without_file_location.msg == "Parameter 'file_location' is required when state is 'backup' for ND versions < 3.2.1."
+          - nt_download_backup is failed
+          - nt_download_backup.msg == "The O(state=download) is only supported on ND v3.2.1 and later."
 
     - name: Query all backups for deleting them
       cisco.nd.nd_backup:

tests/integration/targets/nd_backup_restore/tasks/main.yml

@@ -34,7 +34,7 @@
     - name: Delete all Data Routes
       cisco.nd.nd_rest:
         method: delete
-        ignore_previous_state: true
+        suppress_previous: true
         path: "/api/config/routes/{{ item.destination }}"
       loop: "{{ setup_query_all_routes.current | list }}"
 
@@ -83,7 +83,7 @@
 
     - name: Delete Data Route after ND local backup
       cisco.nd.nd_rest:
-        ignore_previous_state: true
+        suppress_previous: true
         method: delete
         output_level: debug
         path: /api/config/routes/12.23.45.68%2f32
@@ -147,7 +147,7 @@
     - name: Delete all Data Routes
       cisco.nd.nd_rest:
         method: delete
-        ignore_previous_state: true
+        suppress_previous: true
         path: "/api/config/routes/{{ item.destination }}"
       loop: "{{ query_all_routes.current | list }}"
 
@@ -202,7 +202,7 @@
     - name: Delete Data Route after ND remote backup
       cisco.nd.nd_rest:
         output_level: debug
-        ignore_previous_state: true
+        suppress_previous: true
         method: delete
         path: "{{ item }}"
       loop:
@@ -275,7 +275,7 @@
       cisco.nd.nd_rest:
         output_level: debug
         method: delete
-        ignore_previous_state: true
+        suppress_previous: true
         path: "/api/config/routes/{{ item.destination }}"
       loop: "{{ query_all_routes.current | list }}"
 
@@ -338,7 +338,7 @@
       cisco.nd.nd_rest:
         output_level: debug
         method: delete
-        ignore_previous_state: true
+        suppress_previous: true
         path: "{{ item }}"
       loop:
         - /api/config/routes/12.23.45.68%2f32
@@ -415,7 +415,7 @@
       cisco.nd.nd_rest:
         output_level: debug
         method: delete
-        ignore_previous_state: true
+        suppress_previous: true
         path: "/api/config/routes/{{ item.destination }}"
       loop: "{{ query_all_routes.current | list }}"
 
@@ -669,6 +669,13 @@
         query_all_routes_restored2: "{{ query_all_routes_after_second_import.current | map(attribute='spec') | list | sort(attribute='destination') }}"
         query_all_routes_restored3: "{{ query_all_routes_after_third_import.current | map(attribute='spec') | list | sort(attribute='destination') }}"
 
+    - name: Delete restored job without name and restore key
+      cisco.nd.nd_backup_restore:
+        output_level: debug
+        state: absent
+      ignore_errors: true
+      register: delete_restored_job_without_restore_key_and_name
+
     - name: Verify all assertions
       ansible.builtin.assert:
         that:
@@ -686,6 +693,8 @@
           - delete_nexus2.current == delete_nexus2_cm.current == delete_nexus2_again.current == {}
           - query_duplicate_nexus.msg == delete_duplicate_nexus.msg == "Multiple restore jobs with the name 'nexus' found. Please provide a restore key for the corresponding restored job."
           - delete_wrong_key_nexus.msg == "Provided key for the restore 'nexus' not found. Please provide a valid restore key by querying all the restored jobs and looking up the desired restore key."
+          - delete_restored_job_without_restore_key_and_name is failed
+          - delete_restored_job_without_restore_key_and_name.msg == "Please provide a valid O(restore_key) or O(name) to delete a restored job."
 
     - name: Query all restored jobs for deleting them
       cisco.nd.nd_backup_restore: