cli_templates: modify existing CLI templates, cli_templates_info: new module (#54)

ppiwowa-csco · web-flow · commit c4bbcdb055fd · 2025-07-21T13:55:30.000+02:00
diff --git a/plugins/modules/cli_templates.py b/plugins/modules/cli_templates.py
@@ -37,6 +37,16 @@
     required: false
     type: str
     aliases: ["running_config_file_path"]
+  force:
+    description:
+      - Update already existing templates. When template is attached to devices, reattach new version.
+    required: false
+    type: bool
+    default: false
+  timeout_seconds:
+    description:
+      - The timeout in seconds for attaching the template. Default is 300.
+    type: int
 author:
   - Arkadiusz Cichon (acichon@cisco.com)
 extends_documentation_fragment:
@@ -81,20 +91,31 @@
   sample: "abc123"
 """
 
-from typing import Literal, Optional, get_args
+from typing import List, Literal, Optional, get_args
 
 from catalystwan.api.template_api import CLITemplate
+from catalystwan.api.templates.device_template.device_template import DeviceTemplateConfigAttached
+from catalystwan.dataclasses import Device
 from catalystwan.models.common import DeviceModel
 from catalystwan.models.templates import DeviceTemplateInformation
 from catalystwan.session import ManagerHTTPError
 from catalystwan.typed_list import DataSequence
+from ciscoconfparse import CiscoConfParse  # type: ignore
+from pydantic import BaseModel, Field
 
 from ..module_utils.result import ModuleResult
 from ..module_utils.vmanage_module import AnsibleCatalystwanModule
 
 State = Literal["present", "absent"]
 
 
+class ExtendedManagerResponse(BaseModel):
+    process_id: Optional[str] = Field(default=None, validation_alias="processId", serialization_alias="processId")
+    attached_configs: Optional[List[DeviceTemplateConfigAttached]] = Field(
+        default=None, validation_alias="attachedDevices", serialization_alias="attachedDevices"
+    )
+
+
 def run_module():
     module_args = dict(
         state=dict(
@@ -106,6 +127,8 @@ def run_module():
         template_description=dict(type="str", default=None),
         device_model=dict(type="str", aliases=["device_type"], choices=list(get_args(DeviceModel)), default=None),
         config_file=dict(type="str", aliases=["running_config_file_path"]),
+        force=dict(type="bool", default=False),
+        timeout_seconds=dict(type="int", default=300),
     )
     result = ModuleResult()
 
@@ -138,11 +161,57 @@ def run_module():
 
     if module.params.get("state") == "present":
         # Code for checking if template name exists already
-        if target_template:
+        if target_template and not module.params.get("force"):
             module.logger.debug(f"Detected existing template:\n{target_template}\n")
             result.msg = (
                 f"Template with name {template_name} already present on vManage, skipping create template operation."
             )
+        elif target_template:
+            current_template = module.get_response_safely(
+                module.session.api.templates.get_device_template, template_id=target_template[0].id
+            )
+            current_template_configuration = CiscoConfParse(current_template.template_configuration.splitlines())
+
+            new_template = CLITemplate(
+                template_name=template_name,
+                template_description=module.params.get("template_description"),
+                device_model=module.params.get("device_model"),
+            )
+            new_template_configuration = new_template.load_from_file(file=module.params.get("config_file"))
+
+            template_configuration_diff = CLITemplate.compare_template(
+                current_template_configuration, new_template_configuration
+            )
+            if template_configuration_diff:
+                module.logger.debug(f"Detected changes:\n{template_configuration_diff}\nTemplate will be updated")
+                response = module.get_response_safely(module.session.api.templates.edit, template=new_template)
+                template_config_attached = response.dataseq(ExtendedManagerResponse)[0].attached_configs
+                all_devices: DataSequence[Device] = module.get_response_safely(module.session.api.devices.get)
+                for attached_config in template_config_attached:
+                    module.logger.debug(
+                        f"Template is attached to device: {attached_config.uuid}\nReattaching new version"
+                    )
+                    device = all_devices.filter(uuid=attached_config.uuid)[0]
+                    module.get_response_safely(
+                        module.session.api.templates.edit_before_push, name=template_name, device=device
+                    )
+                    response = module.session.api.templates.attach(
+                        name=template_name,
+                        device=device,
+                        timeout_seconds=module.params.get("timeout_seconds"),
+                        is_edited=True,
+                    )
+                result.changed = True
+                result.msg = (
+                    f"Template with name {template_name} already present on vManage is different than provided."
+                    " Updating and reattaching."
+                )
+            else:
+                module.logger.debug(f"Detected existing template:\n{target_template}\n")
+                result.msg = (
+                    f"Template with name {template_name} already present on vManage and is the same as provided."
+                    " Skipping template update."
+                )
         else:
             cli_template = CLITemplate(
                 template_name=template_name,
diff --git a/plugins/modules/cli_templates_info.py b/plugins/modules/cli_templates_info.py
@@ -0,0 +1,183 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright 2025 Cisco Systems, Inc. and its affiliates
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+DOCUMENTATION = r"""
+---
+module: cli_templates_info
+short_description: Get information about CLI Templates on vManage.
+version_added: "0.3.5"
+description:
+  - This module allows you to get CLI Templates Info from vManage.
+options:
+  filters:
+    description:
+      - A dictionary of filters used to select CLI Templates info.
+    type: dict
+    required: false
+    suboptions:
+      device_type:
+        description:
+          - The device type of the template
+        required: false
+        default: null
+        type: list
+        elements: str
+      name:
+        description:
+          - The name of the CLI Template.
+        required: false
+        default: null
+        type: str
+      description:
+        description:
+          - Description of the CLI Template.
+        required: false
+        default: null
+        type: str
+      version:
+        description:
+          - Version of the CLI Template.
+        required: false
+        default: null
+        type: str
+      factory_default:
+        description:
+          - If template is Factory Default template.
+        required: false
+        default: null
+        type: bool
+      draft_mode:
+        description:
+          - The draft mode of template.
+        required: false
+        default: null
+        type: str
+      device_role:
+        description:
+          - The device role.
+        required: false
+        default: null
+        type: str
+      id:
+        description:
+          - CLI Template ID.
+        required: false
+        default: null
+        type: str
+      last_updated_on:
+        description:
+          - Last Updated on value.
+        required: false
+        default: null
+        type: int
+      last_updated_by:
+        description:
+          - Last Updated by value.
+        required: false
+        default: null
+        type: str
+      resource_group:
+        description:
+          - Resource Group value.
+        required: false
+        default: null
+        type: str
+  gather_configuration:
+    description:
+      - Retrieve a templates_configuration list, including detailed configurations for each device in the result.
+    type: bool
+    default: False
+extends_documentation_fragment:
+  - cisco.catalystwan.manager_authentication
+notes:
+  - Ensure that the provided credentials have sufficient permissions to manage templates and devices in vManage.
+"""
+
+EXAMPLES = r"""
+- name: Get all vmanage CLI Templates available
+  cisco.catalystwan.cli_templates:
+    filters:
+      device_type: vmanage
+    manager_credentials: ...
+"""
+
+RETURN = r"""
+msg:
+  description: A message describing the result of the operation.
+  returned: always
+  type: str
+  sample: "Succesfully got all requested CLI Templates Info from vManage"
+changed:
+  description: A boolean flag indicating if any changes were made.
+  returned: always
+  type: bool
+  sample: true
+templates_info:
+  description: List of CLI templates filtered by arguments provided to module.
+  returned: always
+  type: list
+templates_configuration:
+  description: List of CLI templates detailed configuration filtered by arguments provided to module.
+  returned: when gather_configuration is set
+  type: list
+"""
+
+from typing import Literal
+
+from catalystwan.api.template_api import CLITemplate
+from catalystwan.api.templates.device_template.device_template import DeviceTemplate
+from catalystwan.models.templates import DeviceTemplateInformation
+from catalystwan.typed_list import DataSequence
+
+from ..module_utils.result import ModuleResult
+from ..module_utils.vmanage_module import AnsibleCatalystwanModule
+
+
+def run_module():
+    module_args = dict(
+        filters=dict(type="dict", default=None, required=False),
+        gather_configuration=dict(type="bool", default=False),
+    )
+    result = ModuleResult()
+
+    module = AnsibleCatalystwanModule(argument_spec=module_args)
+
+    filters = module.params.get("filters")
+
+    all_templates: DataSequence[DeviceTemplateInformation] = module.get_response_safely(
+        module.session.api.templates.get, template=CLITemplate
+    )
+
+    if module.params.get("filters"):
+        result.templates_info = [template for template in all_templates.filter(**filters)]
+    else:
+        result.templates_info = [template for template in all_templates]
+
+    if module.params.get("gather_configuration"):
+        result.templates_configuration = []
+        for template in result.templates_info:
+            detailed_template: DeviceTemplate = module.get_response_safely(
+                module.session.api.templates.get_device_template, template_id=template.id
+            )
+            result.templates_configuration.append(detailed_template)
+
+    if result.templates_info:
+        module.logger.info(f"All CLI Templates filtered with filters: {filters}:\n{result.templates_info}")
+        result.msg = "Succesfully got all requested CLI Templates Info from vManage"
+    else:
+        module.logger.warning(msg=f"CLI templates filtered with `{filters}` not present.")
+        result.msg = f"CLI templates filtered with `{filters}` not present on vManage."
+
+    module.exit_json(**result.model_dump(mode="json"))
+
+
+def main():
+    run_module()
+
+
+if __name__ == "__main__":
+    main()
