Add cli_restore plugin (ansible-collections#618)

* add cli_restore plugin * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * update extra * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * make it minimal * update format * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix sanity * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix restore * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add path * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix and remove force * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * documentation updated * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * update doc * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Rohit Thakur <[email protected]> Co-authored-by: Ruchi Pakhle <[email protected]>
rohitthakur2590 · Apr 11, 2024 · ecad124 · ecad124
1 parent 9934eec
commit ecad124
Show file tree

Hide file tree

Showing 4 changed files with 253 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -72,6 +72,7 @@ Name | Description
 [ansible.netcommon.cli_backup](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.cli_backup_module.rst)|Back up device configuration from network devices over network_cli
 [ansible.netcommon.cli_command](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.cli_command_module.rst)|Run a cli command on cli-based network devices
 [ansible.netcommon.cli_config](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.cli_config_module.rst)|Push text based configuration to network devices over network_cli
+[ansible.netcommon.cli_restore](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.cli_restore_module.rst)|Restore device configuration to network devices over network_cli
 [ansible.netcommon.grpc_config](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.grpc_config_module.rst)|Fetch configuration/state data from gRPC enabled target hosts.
 [ansible.netcommon.grpc_get](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.grpc_get_module.rst)|Fetch configuration/state data from gRPC enabled target hosts.
 [ansible.netcommon.net_get](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.net_get_module.rst)|Copy a file from a network device to Ansible Controller

diff --git a/changelogs/fragments/add_cli_restore.yaml b/changelogs/fragments/add_cli_restore.yaml
@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - Add new module cli_restore that exclusively handles restoring of backup configuration to target applaince.
diff --git a/docs/ansible.netcommon.cli_restore_module.rst b/docs/ansible.netcommon.cli_restore_module.rst
@@ -0,0 +1,128 @@
+.. _ansible.netcommon.cli_restore_module:
+
+
+*****************************
+ansible.netcommon.cli_restore
+*****************************
+
+**Restore device configuration to network devices over network_cli**
+
+
+Version added: 6.1.0
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- This module provides platform agnostic way of restore text based configuration to network devices over network_cli connection plugin.
+- The module uses the platforms `config replace` commands to restore backup configuration that is already copied over to the appliance.
+
+
+
+
+Parameters
+----------
+
+.. raw:: html
+
+    <table  border=0 cellpadding=0 class="documentation-table">
+        <tr>
+            <th colspan="1">Parameter</th>
+            <th>Choices/<font color="blue">Defaults</font></th>
+            <th width="100%">Comments</th>
+        </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>filename</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                <td>
+                        <div>Filename of the backup file, present in the appliance where the restore operation is to be performed. Check appliance for the configuration backup file name.</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>path</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                <td>
+                        <div>The location in the target appliance where the file containing the backup exists. The path and the filename together create the input to the config replace command,</div>
+                        <div>For an IOSXE appliance the path pattern is flash://&lt;filename&gt;</div>
+                </td>
+            </tr>
+    </table>
+    <br/>
+
+
+Notes
+-----
+
+.. note::
+   - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options <platform_options>` for details.
+
+
+
+Examples
+--------
+
+.. code-block:: yaml
+
+    - name: Restore IOS-XE configuration
+      ansible.netcommon.cli_restore:
+        filename: backupDday.cfg
+        path: flash://
+
+    # Command fired
+    # -------------
+    # config replace flash://backupDday.cfg force
+
+    # Task Output
+    # -----------
+    #
+    # ok: [BATMON] => changed=false
+    #   __restore__: |-
+    #     The rollback configlet from the last pass is listed below:
+    #     ********
+    #     !List of Rollback Commands:
+    #     Building configuration...
+    #     Current configuration : 3781 bytes
+    #     end
+    #     ********
+    #
+    #
+    #     Rollback aborted after 5 passes
+    #     The following commands are failed to apply to the IOS image.
+    #     ********
+    #     Building configuration...
+    #     Current configuration : 3781 bytes
+    #     ********
+    #   invocation:
+    #     module_args:
+    #       filename: backupDday.cfg
+
+
+
+
+Status
+------
+
+
+Authors
+~~~~~~~
+
+- Sagar Paul (@KB-perByte)
diff --git a/plugins/modules/cli_restore.py b/plugins/modules/cli_restore.py
@@ -0,0 +1,121 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2024, Ansible by Red Hat, inc
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+
+DOCUMENTATION = """
+module: cli_restore
+author: Sagar Paul (@KB-perByte)
+short_description: Restore device configuration to network devices over network_cli
+description:
+- This module provides platform agnostic way of restore text based configuration to
+  network devices over network_cli connection plugin.
+- The module uses the platforms `config replace` commands to restore
+  backup configuration that is already copied over to the appliance.
+version_added: 6.1.0
+extends_documentation_fragment:
+- ansible.netcommon.network_agnostic
+options:
+  filename:
+    description:
+    - Filename of the backup file, present in the appliance where the restore operation
+      is to be performed. Check appliance for the configuration backup file name.
+    type: str
+  path:
+    description:
+    - The location in the target appliance where the file containing the backup exists.
+      The path and the filename together create the input to the config replace command,
+    - For an IOSXE appliance the path pattern is flash://<filename>
+    type: str
+"""
+
+EXAMPLES = """
+- name: Restore IOS-XE configuration
+  ansible.netcommon.cli_restore:
+    filename: backupDday.cfg
+    path: flash://
+
+# Command fired
+# -------------
+# config replace flash://backupDday.cfg force
+
+# Task Output
+# -----------
+#
+# ok: [BATMON] => changed=false
+#   __restore__: |-
+#     The rollback configlet from the last pass is listed below:
+#     ********
+#     !List of Rollback Commands:
+#     Building configuration...
+#     Current configuration : 3781 bytes
+#     end
+#     ********
+#
+#
+#     Rollback aborted after 5 passes
+#     The following commands are failed to apply to the IOS image.
+#     ********
+#     Building configuration...
+#     Current configuration : 3781 bytes
+#     ********
+#   invocation:
+#     module_args:
+#       filename: backupDday.cfg
+"""
+
+RETURN = """
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.connection import Connection
+
+
+def validate_args(module, device_operations):
+    """validate param if it is supported on the platform"""
+    feature_list = []
+
+    for feature in feature_list:
+        if module.params[feature]:
+            supports_feature = device_operations.get(f"supports_{feature}")
+            if supports_feature is None:
+                module.fail_json(
+                    msg=f"This platform does not specify whether {feature} is supported or not. "
+                    "Please report an issue against this platform's cliconf plugin."
+                )
+            elif not supports_feature:
+                module.fail_json(msg=f"Option {feature} is not supported on this platform")
+
+
+def main():
+    """main entry point for execution"""
+    argument_spec = dict(
+        filename=dict(type="str"),
+        path=dict(type="str"),
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+    )
+
+    result = {"changed": False}
+    connection = Connection(module._socket_path)
+    running = connection.restore(
+        filename=module.params["filename"],
+        path=module.params["path"],
+    )
+    result["__restore__"] = running
+
+    module.exit_json(**result)
+
+
+if __name__ == "__main__":
+    main()