T6910: fix documentation and argspecs are out of alignment (#358)

chore: update firewall_rules from module
fix: update firewall_global from resource model
chore: update to sync with resource module
chore: update README
fix: comment and formatting
fix: formatting issues
fix: missing imports
fix: import and metadata violations
fix: interface fixes
fix: move the arg spec comment
fix: update interface docs
fix: remove comments for non-RM versions
* T6910: fix documentation and argspecs
* T6910: docs: update per review
* T6910: docs: fix missing pipe

1 files changed, 208 insertions, 206 deletions

diff --git a/plugins/modules/vyos_ntp_global.py b/plugins/modules/vyos_ntp_global.py
index 0fe56ad0..4fd9891b 100644
--- a/plugins/modules/vyos_ntp_global.py
+++ b/plugins/modules/vyos_ntp_global.py
@@ -1,6 +1,6 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-# Copyright 2021 Red Hat
+# Copyright 2024 Red Hat
 # GNU General Public License v3.0+
 # (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
@@ -13,75 +13,78 @@ from __future__ import absolute_import, division, print_function
 
 __metaclass__ = type
 
-
 DOCUMENTATION = """
-  module: vyos_ntp_global
-  version_added: 2.4.0
-  short_description:  Manages ntp modules of Vyos network devices
-  description:
-  - This module manages ntp configuration on devices running Vyos
-  author: Varshitha Yataluru (@YVarshitha)
-  notes:
-  - Tested against vyos 1.3
-  - This module works with connection C(network_cli).
-  options:
-    config:
-        description: List of configurations for ntp module
-        type: dict
+module: vyos_ntp_global
+version_added: 1.0.0
+short_description: NTP global resource module
+description:
+- This module manages ntp configuration on devices running Vyos
+author:
+- Varshitha Yataluru (@YVarshitha)
+notes:
+- Tested against vyos 1.3
+- This module works with connection C(network_cli).
+- "VyOS v.1.4+ uses chronyd, and path changes from `system` to `service`"
+options:
+  config:
+    description: List of configurations for ntp module
+    type: dict
+    suboptions:
+      allow_clients:
+        description: Network Time Protocol (NTP) server options
+        type: list
+        elements: str
+      listen_addresses:
+        description: local IP addresses for service to listen on
+        type: list
+        elements: str
+      servers:
+        description: Network Time Protocol (NTP) server
+        type: list
+        elements: dict
         suboptions:
-            allow_clients:
-                description: Network Time Protocol (NTP) server options
-                type: list
-                elements: str
-            listen_addresses:
-                description: local IP addresses for service to listen on
-                type: list
-                elements: str
-            servers:
-                description: Network Time Protocol (NTP) server
-                type: list
-                elements: dict
-                suboptions:
-                    server:
-                        description: server name for NTP
-                        type: str
-                    options:
-                        description: server options for NTP
-                        type: list
-                        elements: str
-                        choices:
-                            - noselect
-                            - dynamic
-                            - pool
-                            - preempt
-                            - prefer
-    running_config:
-        description:
-        - This option is used only with state I(parsed).
-        - The value of this option should be the output received from the VYOS device by
-          executing the command B(show configuration commands | grep ntp).
-        - The states I(replaced) and I(overridden) have identical
-          behaviour for this module.
-        - The state I(parsed) reads the configuration from C(show configuration commands | grep ntp) option and
-          transforms it into Ansible structured data as per the resource module's argspec
-          and the value is then returned in the I(parsed) key within the result.
-        type: str
-    state:
-        description:
-         - The state the configuration should be left in.
-        type: str
-        choices:
-        - deleted
-        - merged
-        - overridden
-        - replaced
-        - gathered
-        - rendered
-        - parsed
-        default: merged
+          server:
+            description: server name for NTP
+            type: str
+          options:
+            description:
+            - server options for NTP
+            - "`dynamic` changed to `pool` after v1.3"
+            type: list
+            elements: str
+            choices:
+            - noselect
+            - dynamic
+            - pool
+            - preempt
+            - prefer
+  running_config:
+    description:
+    - This option is used only with state I(parsed).
+    - The value of this option should be the output received from the VYOS device by
+      executing the command B(show configuration commands | grep ntp).
+    - The states I(replaced) and I(overridden) have identical
+      behaviour for this module.
+    - The state I(parsed) reads the configuration from C(show configuration commands | grep ntp) option and
+      transforms it into Ansible structured data as per the resource module's argspec
+      and the value is then returned in the I(parsed) key within the result.
+    type: str
+  state:
+    description:
+    - The state the configuration should be left in.
+    type: str
+    choices:
+    - deleted
+    - merged
+    - overridden
+    - replaced
+    - gathered
+    - rendered
+    - parsed
+    default: merged
 """
-EXAMPLES = """
 
+EXAMPLES = """
 # # -------------------
 # # 1. Using merged
 # # -------------------
@@ -89,9 +92,9 @@ EXAMPLES = """
 # # Before state:
 # # -------------
 #   vyos@vyos:~$ show configuration commands | grep ntp
-#     set system ntp server time1.vyos.net
-#     set system ntp server time2.vyos.net
-#     set system ntp server time3.vyos.net
+#     set service ntp server time1.vyos.net
+#     set service ntp server time2.vyos.net
+#     set service ntp server time3.vyos.net
 #   vyos@vyos:~$
 
 # # Task
@@ -140,20 +143,20 @@ EXAMPLES = """
 #    },
 #    "changed": true,
 #    "commands": [
-#        "set system ntp allow-clients address 10.6.6.0/24",
-#        "set system ntp listen-address 10.1.3.1",
-#        "set system ntp server 203.0.113.0 prefer"
+#        "set service ntp allow-clients address 10.6.6.0/24",
+#        "set service ntp listen-address 10.1.3.1",
+#        "set service ntp server 203.0.113.0 prefer"
 #    ]
 
 # After state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp allow-clients address '10.6.6.0/24'
-#        set system ntp listen-address '10.1.3.1'
-#        set system ntp server 203.0.113.0 prefer,
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp allow-clients address '10.6.6.0/24'
+#        set service ntp listen-address '10.1.3.1'
+#        set service ntp server 203.0.113.0 prefer,
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 
@@ -164,25 +167,25 @@ EXAMPLES = """
 # # Before state:
 # # -------------
 #    vyos@vyos:~$ show configuration commands | grep ntp
-#    set system ntp allow-clients address '10.4.9.0/24'
-#    set system ntp allow-clients address '10.4.7.0/24'
-#    set system ntp allow-clients address '10.1.2.0/24'
-#    set system ntp allow-clients address '10.2.3.0/24'
-#    set system ntp listen-address '10.1.9.16'
-#    set system ntp listen-address '10.5.3.2'
-#    set system ntp listen-address '10.7.9.21'
-#    set system ntp listen-address '10.8.9.4'
-#    set system ntp listen-address '10.4.5.1'
-#    set system ntp server 10.3.6.5 noselect
-#    set system ntp server 10.3.6.5 dynamic
-#    set system ntp server 10.3.6.5 preempt
-#    set system ntp server 10.3.6.5 prefer
-#    set system ntp server server4 noselect
-#    set system ntp server server4 dynamic
-#    set system ntp server server5
-#    set system ntp server time1.vyos.net
-#    set system ntp server time2.vyos.net
-#    set system ntp server time3.vyos.net
+#    set service ntp allow-clients address '10.4.9.0/24'
+#    set service ntp allow-clients address '10.4.7.0/24'
+#    set service ntp allow-clients address '10.1.2.0/24'
+#    set service ntp allow-clients address '10.2.3.0/24'
+#    set service ntp listen-address '10.1.9.16'
+#    set service ntp listen-address '10.5.3.2'
+#    set service ntp listen-address '10.7.9.21'
+#    set service ntp listen-address '10.8.9.4'
+#    set service ntp listen-address '10.4.5.1'
+#    set service ntp server 10.3.6.5 noselect
+#    set service ntp server 10.3.6.5 dynamic
+#    set service ntp server 10.3.6.5 preempt
+#    set service ntp server 10.3.6.5 prefer
+#    set service ntp server server4 noselect
+#    set service ntp server server4 dynamic
+#    set service ntp server server5
+#    set service ntp server time1.vyos.net
+#    set service ntp server time2.vyos.net
+#    set service ntp server time3.vyos.net
 #    vyos@vyos:~$
 
 # # Task
@@ -275,32 +278,32 @@ EXAMPLES = """
 #    },
 #    "changed": true,
 #    "commands": [
-#        "delete system ntp allow-clients address 10.4.7.0/24",
-#        "delete system ntp allow-clients address 10.2.3.0/24",
-#        "delete system ntp allow-clients address 10.1.2.0/24",
-#        "delete system ntp allow-clients address 10.4.9.0/24",
-#        "delete system ntp listen-address 10.7.9.21",
-#        "delete system ntp listen-address 10.4.5.1",
-#        "delete system ntp listen-address 10.5.3.2",
-#        "delete system ntp listen-address 10.8.9.4",
-#        "delete system ntp listen-address 10.1.9.16",
-#        "delete system ntp server 10.3.6.5",
-#        "delete system ntp server server4",
-#        "delete system ntp server server5",
-#        "set system ntp allow-clients address 10.6.6.0/24",
-#        "set system ntp listen-address 10.1.3.1",
-#        "set system ntp server 203.0.113.0 prefer"
+#        "delete service ntp allow-clients address 10.4.7.0/24",
+#        "delete service ntp allow-clients address 10.2.3.0/24",
+#        "delete service ntp allow-clients address 10.1.2.0/24",
+#        "delete service ntp allow-clients address 10.4.9.0/24",
+#        "delete service ntp listen-address 10.7.9.21",
+#        "delete service ntp listen-address 10.4.5.1",
+#        "delete service ntp listen-address 10.5.3.2",
+#        "delete service ntp listen-address 10.8.9.4",
+#        "delete service ntp listen-address 10.1.9.16",
+#        "delete service ntp server 10.3.6.5",
+#        "delete service ntp server server4",
+#        "delete service ntp server server5",
+#        "set service ntp allow-clients address 10.6.6.0/24",
+#        "set service ntp listen-address 10.1.3.1",
+#        "set service ntp server 203.0.113.0 prefer"
 #    ]
 
 # After state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp allow-clients address '10.6.6.0/24'
-#        set system ntp listen-address '10.1.3.1'
-#        set system ntp server 203.0.113.0 prefer,
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp allow-clients address '10.6.6.0/24'
+#        set service ntp listen-address '10.1.3.1'
+#        set service ntp server 203.0.113.0 prefer,
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 # # -------------------
@@ -310,12 +313,12 @@ EXAMPLES = """
 # # Before state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp allow-clients address '10.6.6.0/24'
-#        set system ntp listen-address '10.1.3.1'
-#        set system ntp server 203.0.113.0 prefer,
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp allow-clients address '10.6.6.0/24'
+#        set service ntp listen-address '10.1.3.1'
+#        set service ntp server 203.0.113.0 prefer,
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 # Task
@@ -406,31 +409,31 @@ EXAMPLES = """
 #            },
 #            "changed": true,
 #            "commands": [
-#                "delete system ntp allow-clients address 10.6.6.0/24",
-#                "delete system ntp listen-address 10.1.3.1",
-#                "delete system ntp server ser",
-#                "set system ntp allow-clients address 10.3.3.0/24",
-#                "set system ntp listen-address 10.7.8.1",
-#                "set system ntp server server1 dynamic",
-#                "set system ntp server server1 prefer",
-#                "set system ntp server server2 noselect",
-#                "set system ntp server server2 preempt",
-#                "set system ntp server serv"
+#                "delete service ntp allow-clients address 10.6.6.0/24",
+#                "delete service ntp listen-address 10.1.3.1",
+#                "delete service ntp server ser",
+#                "set service ntp allow-clients address 10.3.3.0/24",
+#                "set service ntp listen-address 10.7.8.1",
+#                "set service ntp server server1 dynamic",
+#                "set service ntp server server1 prefer",
+#                "set service ntp server server2 noselect",
+#                "set service ntp server server2 preempt",
+#                "set service ntp server serv"
 #            ]
 
 # After state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp allow-clients address '10.3.3.0/24'
-#        set system ntp listen-address '10.7.8.1'
-#        set system ntp server serv
-#        set system ntp server server1 dynamic
-#        set system ntp server server1 prefer
-#        set system ntp server server2 noselect
-#        set system ntp server server2 preempt
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp allow-clients address '10.3.3.0/24'
+#        set service ntp listen-address '10.7.8.1'
+#        set service ntp server serv
+#        set service ntp server server1 dynamic
+#        set service ntp server server1 prefer
+#        set service ntp server server2 noselect
+#        set service ntp server server2 preempt
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 # 4. Using gathered
@@ -439,16 +442,16 @@ EXAMPLES = """
 # # Before state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp allow-clients address '10.3.3.0/24'
-#        set system ntp listen-address '10.7.8.1'
-#        set system ntp server serv
-#        set system ntp server server1 dynamic
-#        set system ntp server server1 prefer
-#        set system ntp server server2 noselect
-#        set system ntp server server2 preempt
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp allow-clients address '10.3.3.0/24'
+#        set service ntp listen-address '10.7.8.1'
+#        set service ntp server serv
+#        set service ntp server server1 dynamic
+#        set service ntp server server1 prefer
+#        set service ntp server server2 noselect
+#        set service ntp server server2 preempt
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 # Task
@@ -499,16 +502,16 @@ EXAMPLES = """
 # After state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp allow-clients address '10.3.3.0/24'
-#        set system ntp listen-address '10.7.8.1'
-#        set system ntp server serv
-#        set system ntp server server1 dynamic
-#        set system ntp server server1 prefer
-#        set system ntp server server2 noselect
-#        set system ntp server server2 preempt
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp allow-clients address '10.3.3.0/24'
+#        set service ntp listen-address '10.7.8.1'
+#        set service ntp server serv
+#        set service ntp server server1 dynamic
+#        set service ntp server server1 prefer
+#        set service ntp server server2 noselect
+#        set service ntp server server2 preempt
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 
@@ -519,16 +522,16 @@ EXAMPLES = """
 # # Before state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp allow-clients address '10.3.3.0/24'
-#        set system ntp listen-address '10.7.8.1'
-#        set system ntp server serv
-#        set system ntp server server1 dynamic
-#        set system ntp server server1 prefer
-#        set system ntp server server2 noselect
-#        set system ntp server server2 preempt
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp allow-clients address '10.3.3.0/24'
+#        set service ntp listen-address '10.7.8.1'
+#        set service ntp server serv
+#        set service ntp server server1 dynamic
+#        set service ntp server server1 prefer
+#        set service ntp server server2 noselect
+#        set service ntp server server2 preempt
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 # # Task
@@ -591,20 +594,20 @@ EXAMPLES = """
 #            },
 #            "changed": true,
 #            "commands": [
-#                "delete system ntp allow-clients",
-#                "delete system ntp listen-address",
-#                "delete system ntp server serv",
-#                "delete system ntp server server1",
-#                "delete system ntp server server2"
+#                "delete service ntp allow-clients",
+#                "delete service ntp listen-address",
+#                "delete service ntp server serv",
+#                "delete service ntp server server1",
+#                "delete service ntp server server2"
 #
 #            ]
 
 # After state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 
@@ -615,9 +618,9 @@ EXAMPLES = """
 # # Before state:
 # # -------------
 #        vyos@vyos:~$ show configuration commands | grep ntp
-#        set system ntp server time1.vyos.net
-#        set system ntp server time2.vyos.net
-#        set system ntp server time3.vyos.net
+#        set service ntp server time1.vyos.net
+#        set service ntp server time2.vyos.net
+#        set service ntp server time3.vyos.net
 #        vyos@vyos:~$
 
 # Task
@@ -645,16 +648,16 @@ EXAMPLES = """
 # # Task output:
 # # -------------
 #           "rendered": [
-#                "set system ntp allow-clients address 10.7.7.0/24",
-#                "set system ntp allow-clients address 10.8.8.0/24",
-#                "set system ntp listen-address 10.7.9.1",
-#                "set system ntp server server7",
-#                "set system ntp server server45 noselect",
-#                "set system ntp server server45 prefer",
-#                "set system ntp server server45 pool",
-#                "set system ntp server time1.vyos.net",
-#                "set system ntp server time2.vyos.net",
-#                "set system ntp server time3.vyos.net"
+#                "set service ntp allow-clients address 10.7.7.0/24",
+#                "set service ntp allow-clients address 10.8.8.0/24",
+#                "set service ntp listen-address 10.7.9.1",
+#                "set service ntp server server7",
+#                "set service ntp server server45 noselect",
+#                "set service ntp server server45 prefer",
+#                "set service ntp server server45 pool",
+#                "set service ntp server time1.vyos.net",
+#                "set service ntp server time2.vyos.net",
+#                "set service ntp server time3.vyos.net"
 #            ]
 
 
@@ -664,15 +667,15 @@ EXAMPLES = """
 
 # # sample_config.cfg:
 # # -------------
-#           "set system ntp allow-clients address 10.7.7.0/24",
-#           "set system ntp listen-address 10.7.9.1",
-#           "set system ntp server server45 noselect",
-#           "set system ntp allow-clients addres 10.8.6.0/24",
-#           "set system ntp listen-address 10.5.4.1",
-#           "set system ntp server server45 dynamic",
-#           "set system ntp server time1.vyos.net",
-#           "set system ntp server time2.vyos.net",
-#           "set system ntp server time3.vyos.net"
+#           "set service ntp allow-clients address 10.7.7.0/24",
+#           "set service ntp listen-address 10.7.9.1",
+#           "set service ntp server server45 noselect",
+#           "set service ntp allow-clients addres 10.8.6.0/24",
+#           "set service ntp listen-address 10.5.4.1",
+#           "set service ntp server server45 dynamic",
+#           "set service ntp server time1.vyos.net",
+#           "set service ntp server time2.vyos.net",
+#           "set service ntp server time3.vyos.net"
 
 # Task:
 # -------------
@@ -714,6 +717,7 @@ EXAMPLES = """
 #                ]
 #            }
 """
+
 RETURN = """
 before:
   description: The configuration prior to the module execution.
@@ -749,7 +753,6 @@ rendered:
     - set system ntp server server2 noselect
     - set system ntp server server2 preempt
     - set system ntp server server_add preempt
-
 gathered:
   description: Facts about the network resource gathered from the remote device as structured data.
   returned: when I(state) is C(gathered)
@@ -766,7 +769,6 @@ parsed:
     module argspec.
 """
 
-
 from ansible.module_utils.basic import AnsibleModule
 
 from ansible_collections.vyos.vyos.plugins.module_utils.network.vyos.argspec.ntp_global.ntp_global import (