lldp_global module

3 files changed, 140 insertions, 26 deletions

diff --git a/docs/vyos.rest.vyos_lldp_global_module.rst b/docs/vyos.rest.vyos_lldp_global_module.rst
index 0f24668..9016792 100644
--- a/docs/vyos.rest.vyos_lldp_global_module.rst
+++ b/docs/vyos.rest.vyos_lldp_global_module.rst
@@ -18,6 +18,7 @@ Version added: 1.0.0
 Synopsis
 --------
 - Manage LLDP global configuration on VyOS via REST API.
+- Uses ``ansible_connection=ansible.netcommon.httpapi``.
 
 
 
@@ -45,6 +46,7 @@ Parameters
                 <td>
                 </td>
                 <td>
+                        <div>LLDP global configuration.</div>
                 </td>
             </tr>
                                 <tr>
@@ -61,6 +63,7 @@ Parameters
                 <td>
                 </td>
                 <td>
+                        <div>List of management addresses to advertise.</div>
                 </td>
             </tr>
             <tr>
@@ -80,6 +83,7 @@ Parameters
                         </ul>
                 </td>
                 <td>
+                        <div>Enable LLDP service.</div>
                 </td>
             </tr>
             <tr>
@@ -102,6 +106,7 @@ Parameters
                         </ul>
                 </td>
                 <td>
+                        <div>Legacy protocols to support.</div>
                 </td>
             </tr>
             <tr>
@@ -117,7 +122,9 @@ Parameters
                 <td>
                 </td>
                 <td>
-                        <div><code>enable</code> or <code>disable</code>.</div>
+                        <div><code>enable</code> to enable LLDP SNMP subagent.</div>
+                        <div><code>disable</code> to disable it.</div>
+                        <div>Requires SNMP service to be configured on the device.</div>
                 </td>
             </tr>
 
@@ -139,6 +146,10 @@ Parameters
                         </ul>
                 </td>
                 <td>
+                        <div><code>merged</code> - merge config with existing.</div>
+                        <div><code>replaced</code> - replace existing config with provided.</div>
+                        <div><code>deleted</code> - delete LLDP configuration.</div>
+                        <div><code>gathered</code> - return current config without changes.</div>
                 </td>
             </tr>
     </table>
@@ -152,14 +163,34 @@ Examples
 
 .. code-block:: yaml
 
-    - vyos.rest.vyos_lldp_global:
+    - name: Enable LLDP with management address and legacy protocols
+      vyos.rest.vyos_lldp_global:
         config:
           enable: true
-          addresses: [192.0.2.17]
-          snmp: enable
-          legacy_protocols: [cdp, fdp]
+          addresses:
+            - 192.0.2.17
+          legacy_protocols:
+            - cdp
+            - fdp
         state: merged
 
+    - name: Replace LLDP configuration
+      vyos.rest.vyos_lldp_global:
+        config:
+          enable: true
+          addresses:
+            - 192.0.2.99
+        state: replaced
+
+    - name: Delete all LLDP configuration
+      vyos.rest.vyos_lldp_global:
+        state: deleted
+
+    - name: Gather current LLDP configuration
+      vyos.rest.vyos_lldp_global:
+        state: gathered
+      register: result
+
 
 
 Return Values
@@ -185,6 +216,7 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
                 </td>
                 <td>when changed</td>
                 <td>
+                            <div>LLDP configuration after the module ran.</div>
                     <br/>
                 </td>
             </tr>
@@ -199,6 +231,7 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
                 </td>
                 <td>always</td>
                 <td>
+                            <div>LLDP configuration before the module ran.</div>
                     <br/>
                 </td>
             </tr>
@@ -213,6 +246,7 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
                 </td>
                 <td>always</td>
                 <td>
+                            <div>List of commands sent to the device.</div>
                     <br/>
                 </td>
             </tr>
@@ -227,6 +261,7 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
                 </td>
                 <td>when state is gathered</td>
                 <td>
+                            <div>Current LLDP configuration from the device.</div>
                     <br/>
                 </td>
             </tr>
diff --git a/plugins/modules/vyos_lldp_global.py b/plugins/modules/vyos_lldp_global.py
index 1eb10bd..cc24be9 100644
--- a/plugins/modules/vyos_lldp_global.py
+++ b/plugins/modules/vyos_lldp_global.py
@@ -4,59 +4,99 @@ from __future__ import absolute_import, division, print_function
 
 
 __metaclass__ = type
+
 DOCUMENTATION = r"""
 ---
 module: vyos_lldp_global
 short_description: Manage LLDP global configuration on VyOS via REST API.
 description:
   - Manage LLDP global configuration on VyOS via REST API.
+  - Uses C(ansible_connection=ansible.netcommon.httpapi).
 version_added: "1.0.0"
 author: VyOS Community (@vyos)
 options:
   config:
+    description: LLDP global configuration.
     type: dict
     suboptions:
       enable:
+        description: Enable LLDP service.
         type: bool
       addresses:
+        description: List of management addresses to advertise.
         type: list
         elements: str
       snmp:
         description:
-        - C(enable) or C(disable).
+          - C(enable) to enable LLDP SNMP subagent.
+          - C(disable) to disable it.
+          - Requires SNMP service to be configured on the device.
         type: str
       legacy_protocols:
+        description: Legacy protocols to support.
         type: list
         elements: str
         choices: [cdp, edp, fdp, sonmp]
   state:
+    description:
+      - C(merged) - merge config with existing.
+      - C(replaced) - replace existing config with provided.
+      - C(deleted) - delete LLDP configuration.
+      - C(gathered) - return current config without changes.
     type: str
     default: merged
     choices: [merged, replaced, deleted, gathered]
 """
+
 EXAMPLES = r"""
-- vyos.rest.vyos_lldp_global:
+- name: Enable LLDP with management address and legacy protocols
+  vyos.rest.vyos_lldp_global:
     config:
       enable: true
-      addresses: [192.0.2.17]
-      snmp: enable
-      legacy_protocols: [cdp, fdp]
+      addresses:
+        - 192.0.2.17
+      legacy_protocols:
+        - cdp
+        - fdp
     state: merged
+
+- name: Replace LLDP configuration
+  vyos.rest.vyos_lldp_global:
+    config:
+      enable: true
+      addresses:
+        - 192.0.2.99
+    state: replaced
+
+- name: Delete all LLDP configuration
+  vyos.rest.vyos_lldp_global:
+    state: deleted
+
+- name: Gather current LLDP configuration
+  vyos.rest.vyos_lldp_global:
+    state: gathered
+  register: result
 """
+
 RETURN = r"""
 before:
+  description: LLDP configuration before the module ran.
   returned: always
   type: dict
 after:
+  description: LLDP configuration after the module ran.
   returned: when changed
   type: dict
 commands:
+  description: List of commands sent to the device.
   returned: always
   type: list
 gathered:
+  description: Current LLDP configuration from the device.
   returned: when state is gathered
   type: dict
 """
+
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.vyos.rest.plugins.module_utils.vyos import VyOSModule
 
@@ -93,19 +133,42 @@ def _get(vyos):
 def _build(want, have, state):
     cmds = []
 
-    if state in ("replaced", "deleted") and have:
-        cmds.append(("delete", _BASE))
-        if state == "deleted":
-            return cmds
-
-    # enable — only set if not already enabled
-    if want.get("enable") is not False and not have.get("enable"):
+    if state == "deleted":
+        if have:
+            cmds.append(("delete", _BASE))
+        return cmds
+
+    if state == "replaced":
+        # only wipe and rebuild if have differs from want
+        want_addrs = sorted(want.get("addresses") or [])
+        have_addrs = sorted(have.get("addresses") or [])
+        want_protos = sorted(want.get("legacy_protocols") or [])
+        have_protos = sorted(have.get("legacy_protocols") or [])
+        want_snmp = want.get("snmp")
+        have_snmp = have.get("snmp")
+        want_enable = bool(want.get("enable"))
+        have_enable = bool(have.get("enable"))
+
+        if (
+            want_addrs != have_addrs
+            or want_protos != have_protos
+            or want_snmp != have_snmp
+            or want_enable != have_enable
+        ):
+            if have:
+                cmds.append(("delete", _BASE))
+            # fall through to set everything from want
+        else:
+            return cmds  # already matches — idempotent
+
+    # enable
+    if want.get("enable") and not have.get("enable"):
         cmds.append(("set", _BASE))
 
-    # addresses — only add missing ones
-    have_addrs = set(have.get("addresses") or [])
+    # addresses
+    have_addrs_set = set(have.get("addresses") or []) if state != "replaced" else set()
     for addr in want.get("addresses") or []:
-        if addr not in have_addrs:
+        if addr not in have_addrs_set:
             cmds.append(("set", _BASE + ["management-address", addr]))
 
     # snmp
@@ -115,10 +178,10 @@ def _build(want, have, state):
         elif want["snmp"] != "disable" and not have.get("snmp"):
             cmds.append(("set", _BASE + ["snmp"]))
 
-    # legacy_protocols — only add missing ones
-    have_protos = set(have.get("legacy_protocols") or [])
+    # legacy_protocols
+    have_protos_set = set(have.get("legacy_protocols") or []) if state != "replaced" else set()
     for p in want.get("legacy_protocols") or []:
-        if p not in have_protos:
+        if p not in have_protos_set:
             cmds.append(("set", _BASE + ["legacy-protocols", p]))
 
     return cmds
@@ -126,7 +189,7 @@ def _build(want, have, state):
 
 def main():
     module = AnsibleModule(
-        dict(
+        argument_spec=dict(
             config=dict(
                 type="dict",
                 options=dict(
@@ -140,19 +203,27 @@ def main():
                     ),
                 ),
             ),
-            state=dict(default="merged", choices=["merged", "replaced", "deleted", "gathered"]),
+            state=dict(
+                default="merged",
+                choices=["merged", "replaced", "deleted", "gathered"],
+            ),
         ),
         supports_check_mode=True,
     )
+
     vyos = VyOSModule(module)
     state = module.params["state"]
     config = module.params.get("config") or {}
     have = _get(vyos)
+
     if state == "gathered":
         module.exit_json(changed=False, gathered=have)
+
     commands = _build(config, have, state)
+
     if module.check_mode:
         module.exit_json(changed=bool(commands), commands=commands, before=have)
+
     if commands:
         response = vyos.apply_commands(commands)
         saved = vyos.save_config()
@@ -164,6 +235,7 @@ def main():
             saved=saved,
             response=response,
         )
+
     module.exit_json(changed=False, before=have, after=have, commands=[])
 
 
diff --git a/tests/integration/targets/vyos_lldp_global/tests/httpapi/_populate_config.yaml b/tests/integration/targets/vyos_lldp_global/tests/httpapi/_populate_config.yaml
index 3bf4fb0..6c3acf4 100644
--- a/tests/integration/targets/vyos_lldp_global/tests/httpapi/_populate_config.yaml
+++ b/tests/integration/targets/vyos_lldp_global/tests/httpapi/_populate_config.yaml
@@ -1,4 +1,12 @@
 ---
+- name: Configure SNMP first (required for LLDP snmp)
+  vyos.rest.vyos_snmp_server:
+    config:
+      communities:
+        - name: lldp-test
+          authorization_type: ro
+    state: merged
+
 - name: Populate lldp_global config for testing
   vyos.rest.vyos_lldp_global:
     config:
@@ -10,4 +18,3 @@
         - cdp
         - sonmp
     state: merged
-  ignore_errors: true