From 0ebc0b9e5ab55f11beecdabed8d5403230260cb2 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 --- 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 cca91532a0a..5ad3fb52027 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: @@ -235,6 +237,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 f490070f358..af74b0a7c67 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: @@ -262,6 +264,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 9f0153e044a..6f05c4c2232 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: @@ -152,6 +154,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 566e56f4735..894d849875b 100644 --- a/lib/ansible/modules/network/junos/junos_config.py +++ b/lib/ansible/modules/network/junos/junos_config.py @@ -127,6 +127,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. @@ -158,6 +160,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 c88cf111978..686ad434ccb 100644 --- a/lib/ansible/modules/network/nxos/nxos_config.py +++ b/lib/ansible/modules/network/nxos/nxos_config.py @@ -205,6 +205,9 @@ options: argument, the task should also modify the C(diff_against) value and set it to I(intended). 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 = """ @@ -245,6 +248,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 e768f212135..4b0214494e7 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: @@ -102,6 +104,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 = """