From a2df7ab75ea8f1fc5f021a78bdab446a7eac3e59 Mon Sep 17 00:00:00 2001 From: Alicia Cozine Date: Wed, 18 Apr 2018 13:41:54 -0500 Subject: [PATCH] adds FAQ TOC entry, links & examples to modules (#38706) * adds FAQ TOC entry, links & examples to modules * moves link to Notes, corrects examples (cherry picked from commit 0ebc0b9e5ab55f11beecdabed8d5403230260cb2) --- docs/docsite/rst/network/index.rst | 1 + lib/ansible/modules/network/eos/eos_config.py | 10 ++++++++++ lib/ansible/modules/network/ios/ios_config.py | 10 ++++++++++ lib/ansible/modules/network/iosxr/iosxr_config.py | 10 ++++++++++ lib/ansible/modules/network/junos/junos_config.py | 8 ++++++++ lib/ansible/modules/network/nxos/nxos_config.py | 10 ++++++++++ lib/ansible/modules/network/vyos/vyos_config.py | 8 ++++++++ 7 files changed, 57 insertions(+) diff --git a/docs/docsite/rst/network/index.rst b/docs/docsite/rst/network/index.rst index 7ced8eca9c2..d0ced97d349 100644 --- a/docs/docsite/rst/network/index.rst +++ b/docs/docsite/rst/network/index.rst @@ -32,6 +32,7 @@ For documentation on using a particular network module, consult the :doc:`list o :caption: User Guide user_guide/index + user_guide/faq user_guide/network_best_practices_2.5 user_guide/network_debug_troubleshooting user_guide/network_working_with_command_output diff --git a/lib/ansible/modules/network/eos/eos_config.py b/lib/ansible/modules/network/eos/eos_config.py index d4a79d0d517..e3794ae714a 100644 --- a/lib/ansible/modules/network/eos/eos_config.py +++ b/lib/ansible/modules/network/eos/eos_config.py @@ -36,6 +36,8 @@ description: extends_documentation_fragment: eos notes: - Tested against EOS 4.15 + - Abbreviated commands are NOT idempotent, see + L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands). options: lines: description: @@ -257,6 +259,14 @@ EXAMPLES = """ eos_config: diff_against: intended intended_config: "{{ lookup('file', 'master.cfg') }}" + +- name: for idempotency, use full-form commands + eos_config: + lines: + # - shut + - shutdown + # parents: int eth1 + parents: interface Ethernet1 """ RETURN = """ diff --git a/lib/ansible/modules/network/ios/ios_config.py b/lib/ansible/modules/network/ios/ios_config.py index 244baee4499..0882c3b7081 100644 --- a/lib/ansible/modules/network/ios/ios_config.py +++ b/lib/ansible/modules/network/ios/ios_config.py @@ -35,6 +35,8 @@ description: extends_documentation_fragment: ios notes: - Tested against IOS 15.6 + - Abbreviated commands are NOT idempotent, see + L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands). options: lines: description: @@ -285,6 +287,14 @@ EXAMPLES = """ - name: save running to startup when modified ios_config: save_when: modified + +- name: for idempotency, use full-form commands + ios_config: + lines: + # - shut + - shutdown + # parents: int gig1/0/11 + parents: interface GigabitEthernet1/0/11 """ RETURN = """ diff --git a/lib/ansible/modules/network/iosxr/iosxr_config.py b/lib/ansible/modules/network/iosxr/iosxr_config.py index c3691fc6039..0b7023f8942 100644 --- a/lib/ansible/modules/network/iosxr/iosxr_config.py +++ b/lib/ansible/modules/network/iosxr/iosxr_config.py @@ -27,6 +27,8 @@ extends_documentation_fragment: iosxr notes: - Tested against IOS XRv 6.1.2 - This module does not support netconf connection + - Abbreviated commands are NOT idempotent, see + L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands). - Avoid service disrupting changes (viz. Management IP) from config replace. - Do not use C(end) in the replace config file. options: @@ -170,6 +172,14 @@ EXAMPLES = """ src: config.cfg replace: config backup: yes + +- name: for idempotency, use full-form commands + iosxr_config: + lines: + # - shut + - shutdown + # parents: int g0/0/0/1 + parents: interface GigabitEthernet0/0/0/1 """ RETURN = """ diff --git a/lib/ansible/modules/network/junos/junos_config.py b/lib/ansible/modules/network/junos/junos_config.py index e1cbf5bff21..95f942894fd 100644 --- a/lib/ansible/modules/network/junos/junos_config.py +++ b/lib/ansible/modules/network/junos/junos_config.py @@ -143,6 +143,8 @@ requirements: notes: - This module requires the netconf system service be enabled on the remote device being managed. + - Abbreviated commands are NOT idempotent, see + L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands). - Loading JSON-formatted configuration I(json) is supported starting in Junos OS Release 16.1 onwards. - Tested against vSRX JUNOS version 15.1X49-D15.4, vqfx-10000 JUNOS Version 15.1X53-D60.4. @@ -174,6 +176,12 @@ EXAMPLES = """ - name: confirm a previous commit junos_config: confirm_commit: yes + +- name: for idempotency, use full-form commands + junos_config: + lines: + # - set int ge-0/0/1 unit 0 desc "Test interface" + - set interfaces ge-0/0/1 unit 0 description "Test interface" """ RETURN = """ diff --git a/lib/ansible/modules/network/nxos/nxos_config.py b/lib/ansible/modules/network/nxos/nxos_config.py index 69b2ed2b450..996a52aef5a 100644 --- a/lib/ansible/modules/network/nxos/nxos_config.py +++ b/lib/ansible/modules/network/nxos/nxos_config.py @@ -229,6 +229,9 @@ options: set it to I(intended). required: false version_added: "2.4" +notes: + - Abbreviated commands are NOT idempotent, see + L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands). """ EXAMPLES = """ @@ -269,6 +272,13 @@ EXAMPLES = """ replace_src: config.txt replace: config +- name: for idempotency, use full-form commands + nxos_config: + lines: + # - shut + - shutdown + # parents: int eth1/1 + parents: interface Ethernet1/1 """ RETURN = """ diff --git a/lib/ansible/modules/network/vyos/vyos_config.py b/lib/ansible/modules/network/vyos/vyos_config.py index 848ae6fa823..6d89d818529 100644 --- a/lib/ansible/modules/network/vyos/vyos_config.py +++ b/lib/ansible/modules/network/vyos/vyos_config.py @@ -36,6 +36,8 @@ description: extends_documentation_fragment: vyos notes: - Tested against VYOS 1.1.7 + - Abbreviated commands are NOT idempotent, see + L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands). options: lines: description: @@ -112,6 +114,12 @@ EXAMPLES = """ vyos_config: src: vyos.cfg backup: yes + +- name: for idempotency, use full-form commands + vyos_config: + lines: + # - set int eth eth2 description 'OUTSIDE' + - set interface ethernet eth2 description 'OUTSIDE' """ RETURN = """