diff --git a/changelogs/fragments/command-check_mode.yml b/changelogs/fragments/command-check_mode.yml new file mode 100644 index 00000000..6f2ae312 --- /dev/null +++ b/changelogs/fragments/command-check_mode.yml @@ -0,0 +1,4 @@ +known_issues: + - "The ``community.routeros.command`` module claims to support check mode. + Since it cannot judge whether the commands executed modify state or not, this behavior is incorrect. + Since this potentially breaks existing playbooks, we will not change this behavior until community.routeros 3.0.0." diff --git a/docs/docsite/rst/api-guide.rst b/docs/docsite/rst/api-guide.rst index a96d84c8..92a96745 100644 --- a/docs/docsite/rst/api-guide.rst +++ b/docs/docsite/rst/api-guide.rst @@ -17,7 +17,7 @@ No special setup is needed; the module needs to be run on a host that can connec --- - name: RouterOS test with API hosts: localhost - gather_facts: no + gather_facts: false vars: hostname: 192.168.1.1 username: admin @@ -71,7 +71,7 @@ To avoid having to specify common parameters for all the API based modules in ev --- - name: RouterOS test with API hosts: localhost - gather_facts: no + gather_facts: false module_defaults: group/community.routeros.api hostname: 192.168.1.1 diff --git a/meta/runtime.yml b/meta/runtime.yml index c9cdbbf7..5aafd31d 100644 --- a/meta/runtime.yml +++ b/meta/runtime.yml @@ -6,8 +6,8 @@ requires_ansible: '>=2.9.10' action_groups: api: - - api - - api_facts - - api_find_and_modify - - api_info - - api_modify + - api + - api_facts + - api_find_and_modify + - api_info + - api_modify diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py new file mode 100644 index 00000000..e18a48ff --- /dev/null +++ b/plugins/doc_fragments/attributes.py @@ -0,0 +1,98 @@ +# -*- coding: utf-8 -*- + +# Copyright (c) Ansible Project +# GNU General Public License v3.0+ (see COPYING 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 + + +class ModuleDocFragment(object): + + # Standard documentation fragment + DOCUMENTATION = r''' +options: {} +attributes: + check_mode: + description: Can run in C(check_mode) and return changed status prediction without modifying target. + diff_mode: + description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. + platform: + description: Target OS/families that can be operated against. + support: N/A +''' + + # Should be used together with the standard fragment + INFO_MODULE = r''' +options: {} +attributes: + check_mode: + support: full + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. +''' + + ACTIONGROUP_API = r''' +options: {} +attributes: + action_group: + description: Use C(group/community.routeros.api) in C(module_defaults) to set defaults for this module. + support: full + membership: + - community.routeros.api +''' + + CONN = r''' +options: {} +attributes: + become: + description: Is usable alongside C(become) keywords. + connection: + description: Uses the target's configured connection information to execute code on it. + delegation: + description: Can be used in conjunction with C(delegate_to) and related keywords. +''' + + FACTS = r''' +options: {} +attributes: + facts: + description: Action returns an C(ansible_facts) dictionary that will update existing host facts. +''' + + # Should be used together with the standard fragment and the FACTS fragment + FACTS_MODULE = r''' +options: {} +attributes: + check_mode: + support: full + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. + facts: + support: full +''' + + FILES = r''' +options: {} +attributes: + safe_file_operations: + description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption. +''' + + FLOW = r''' +options: {} +attributes: + action: + description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller. + async: + description: Supports being used with the C(async) keyword. +''' diff --git a/plugins/modules/api.py b/plugins/modules/api.py index ea667a5e..dbf9d3de 100644 --- a/plugins/modules/api.py +++ b/plugins/modules/api.py @@ -18,12 +18,23 @@ - This module can add, remove, update, query and execute arbitrary command in RouterOS via API. notes: - I(add), I(remove), I(update), I(cmd) and I(query) are mutually exclusive. - - I(check_mode) is not supported. - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules for more specific modifications, and the M(community.routeros.api_info) module for a more controlled way of returning all entries for a path. extends_documentation_fragment: - community.routeros.api + - community.routeros.attributes + - community.routeros.attributes.actiongroup_api +attributes: + check_mode: + support: none + diff_mode: + support: none + platform: + support: full + platforms: RouterOS + action_group: + version_added: 2.1.0 options: path: description: diff --git a/plugins/modules/api_facts.py b/plugins/modules/api_facts.py index 7db910c4..59de196d 100644 --- a/plugins/modules/api_facts.py +++ b/plugins/modules/api_facts.py @@ -28,6 +28,14 @@ RouterOS API, similar to the M(community.routeros.api) module. extends_documentation_fragment: - community.routeros.api + - community.routeros.attributes + - community.routeros.attributes.actiongroup_api + - community.routeros.attributes.facts + - community.routeros.attributes.facts_module +attributes: + platform: + support: full + platforms: RouterOS options: gather_subset: description: diff --git a/plugins/modules/api_find_and_modify.py b/plugins/modules/api_find_and_modify.py index a3b61f02..0be3f703 100644 --- a/plugins/modules/api_find_and_modify.py +++ b/plugins/modules/api_find_and_modify.py @@ -24,9 +24,18 @@ there are at least N such values, you can use I(require_matches_min=N) together with I(allow_no_matches=true). This will make the module fail if there are less than N such entries, but not if there is no match. The latter case is needed for idempotency of the task: once the values have been changed, there should be no further match." - - Supports I(check_mode). extends_documentation_fragment: - community.routeros.api + - community.routeros.attributes + - community.routeros.attributes.actiongroup_api +attributes: + check_mode: + support: full + diff_mode: + support: full + platform: + support: full + platforms: RouterOS options: path: description: diff --git a/plugins/modules/api_info.py b/plugins/modules/api_info.py index d580bb6b..bf1b23f8 100644 --- a/plugins/modules/api_info.py +++ b/plugins/modules/api_info.py @@ -24,10 +24,15 @@ - B(Note) that this module is still heavily in development, and only supports B(some) paths. If you want to support new paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/). -notes: - - Supports I(check_mode). extends_documentation_fragment: - community.routeros.api + - community.routeros.attributes + - community.routeros.attributes.actiongroup_api + - community.routeros.attributes.info_module +attributes: + platform: + support: full + platforms: RouterOS options: path: description: diff --git a/plugins/modules/api_modify.py b/plugins/modules/api_modify.py index a0d76bab..9e73c91f 100644 --- a/plugins/modules/api_modify.py +++ b/plugins/modules/api_modify.py @@ -24,12 +24,20 @@ - B(Note) that this module is still heavily in development, and only supports B(some) paths. If you want to support new paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/). -notes: - - Supports I(check_mode). requirements: - Needs L(ordereddict,https://pypi.org/project/ordereddict) for Python 2.6 extends_documentation_fragment: - community.routeros.api + - community.routeros.attributes + - community.routeros.attributes.actiongroup_api +attributes: + check_mode: + support: full + diff_mode: + support: full + platform: + support: full + platforms: RouterOS options: path: description: diff --git a/plugins/modules/command.py b/plugins/modules/command.py index c96e1533..83cd776f 100644 --- a/plugins/modules/command.py +++ b/plugins/modules/command.py @@ -20,6 +20,21 @@ - The module always indicates a (changed) status. You can use R(the changed_when task property,override_the_changed_result) to determine whether a command task actually resulted in a change or not. +notes: + - The module declares that it B(supports check mode). This is a bug and will + be changed in community.routeros 3.0.0. +extends_documentation_fragment: + - community.routeros.attributes +attributes: + check_mode: + support: partial + details: + - The module claims to support check mode, but it simply always executes the command. + diff_mode: + support: none + platform: + support: full + platforms: RouterOS options: commands: description: diff --git a/plugins/modules/facts.py b/plugins/modules/facts.py index cefaf5c5..7b1cd0d8 100644 --- a/plugins/modules/facts.py +++ b/plugins/modules/facts.py @@ -18,6 +18,14 @@ base network fact keys with C(ansible_net_). The facts module will always collect a base set of facts from the device and can enable or disable collection of additional facts. +extends_documentation_fragment: + - community.routeros.attributes + - community.routeros.attributes.facts + - community.routeros.attributes.facts_module +attributes: + platform: + support: full + platforms: RouterOS options: gather_subset: description: