draft Network FAQ #38359
draft Network FAQ #38359
Conversation
acozine
added this to Docsite work
in Ansible-maintained Collections Documentation
via automation
ansibot
added
docs
|
The test |
ansibot
added
ci_verified
acozine
moved this from Docsite work
to In progress
in Ansible-maintained Collections Documentation
ansibot
removed
ci_verified
mkrizek
removed
the
needs_triage
| How can I improve performance for network playbooks? | ||
| ==================================================== | ||
|
|
||
| * Set ``strategy: free`` at the playbook level if you are running on multiple hosts |
There was a problem hiding this comment.
Wonder if each of the "hows" should be separate headings with anchors. Would improve formatting and give us the ability to link directly to the relevant section
Looking at the rendered version the current bullet point version looks a bit strange to me
| ==================================================== | ||
|
|
||
| * Set ``strategy: free`` at the playbook level if you are running on multiple hosts | ||
|
|
There was a problem hiding this comment.
Maybe something like:
What is this option
When would this make sense (i.e. how do you know if this is something to consider)
|
|
||
| * Set ``strategy: free`` at the playbook level if you are running on multiple hosts | ||
|
|
||
| The ``strategy`` plugin controls the ordering of tasks on hosts. When ``strategy=linear``, Ansible will wait until the current task has run on all hosts before starting the next host. When ``strategy=free``, Ansible will execute the next task on each host as soon as that host completes the current task, so overall execution is not waiting for the slowest host. |
There was a problem hiding this comment.
I was wondering if we should link to the linear and free pages though these seem low in detail
http://docs.ansible.com/ansible/latest/user_guide/playbooks_strategies.html
https://docs.ansible.com/ansible/devel/plugins/strategy/linear.html
https://docs.ansible.com/ansible/devel/plugins/strategy/free.html
I wonder if we should flesh those pages out a bit and include links from here. That would mean as the reference material is improved we guide people to those pages.
|
|
||
| * Use ``ProxyCommand`` only if you absolutely must | ||
|
|
||
| Network modules support the use of a jump host with the ``ProxyCommand`` parameter. However, when you use a jump host, Ansible must open a new SSH connection for every task, even if you are using a persistent connection type (``network_cli`` or ``netconf``). To maximize the performance benefits of the persistent connection types introduced in version 2.5, avoid using jump hosts whenever possible. |
There was a problem hiding this comment.
I'm not sure what page you mean by "proxy details" - are you thinking of here -http://docs.ansible.com/ansible/devel/network/user_guide/network_debug_troubleshooting.html#proxy-issues ? Or here - http://docs.ansible.com/ansible/devel/user_guide/playbooks_environment.html?highlight=proxy ?
| Why is my output sometimes replaced with "********"? | ||
| ==================================================== | ||
|
|
||
| Ansible replaces any string marked ``no_log``, including passwords, with ``********`` in Ansible output. This is done by design, to protect your sensitive data. Most users are happy to have their passwords redacted. However, Ansible replaces every string that matches your password with ``********``. If you use a common word for your password, this can be a problem. For example, if you choose ``Admin`` as your password, Ansible will replace every instance of the word ``Admin`` with ``********`` in your output. This may make your output harder to read. To avoid this problem, select a password that will not occur elsewhere in your Ansible output. |
There was a problem hiding this comment.
Suggestion: select a password -> select a secure password
| Ansible Network FAQ | ||
| ******************* | ||
|
|
||
| How can I improve performance for network playbooks? |
There was a problem hiding this comment.
@privateip had a way of avoiding all the skipped tasks (network_os) which may be relevant for this section. He mentioned it during the four playbook exercises in Durham
| Why do the ``*_config`` modules always return ``changed=true`` with short-form commands? | ||
| ======================================================================================== | ||
|
|
||
| When you are issuing commands directly on a network device, you can use long-form and short-form commands interchangeably. For example ``interface`` and ``int`` have the same effect. Ansible's ``*_command`` modules return the same results no matter which form of the command you use, because they run those commands through the network OS. However, behind the scenes, the network OS will convert short-form commands into long-form before committing the state of the configuration. Ansible's ``*_config`` modules check the difference between the command provided and the existing configuration. Because existing configuration is always expressed long-form, using the short-form commands with the ``*_config`` modules will always return ``changed=true``, even when the state of the configuration matches the short-form command given. To avoid this problem and make your playbooks more efficient, use long-form commands with the ``*_config`` modules. |
There was a problem hiding this comment.
If we change to headings (rather than bullet points) I wonder if we could split this block of text up a bit to increase readability.
ansibot
added
the
needs_revision
|
|
||
| .. _network_faq_redacted_output: | ||
|
|
||
| Why is my output sometimes replaced with "********"? |
There was a problem hiding this comment.
Should these quotes be backticks?
ansibot
added
needs_ci
|
|
||
| Ansible's ``*_config`` modules check the difference between the commands provided and the running configuration. Because existing configuration is always expressed long-form, the ``*_config`` modules will always return ``changed=true`` if you use abbreviations. | ||
|
|
||
| To avoid this problem and make your playbooks more efficient, use long-form commands with the ``*_config`` modules: |
There was a problem hiding this comment.
Suggestion: Explain what's meant by efficient, or just remove that term?
There was a problem hiding this comment.
Thanks. I clarified this. Comments in this section addressed by 2b28b394b4b1bf37681fd71eaa492a7a312e62c5
| Why do the ``*_config`` modules always return ``changed=true`` with abbreviated commands? | ||
| ========================================================================================= | ||
|
|
||
| When you issue commands directly on a network device, you can use abbreviated commands. For example, ``int g1/0/11`` and ``interface GigabitEthernet1/0/11`` do the same thing; ``shut`` and ``shutdown`` do the same thing. Ansible's ``*_command`` modules work with abbreviations, because they run commands through the network OS. |
There was a problem hiding this comment.
Why did the short form example get removed?
suggestion: do the same thing -> are functionally identical?
There was a problem hiding this comment.
I re-thought that example. If we include sample tasks or playbooks demonstrating the wrong way to do things, customers can copy/paste those by mistake. In the porting guides, we need to include examples of the "old" way to help customers upgrade their playbooks. But elsewhere the examples should all be correct and current.
|
|
||
| When committing configuration, however, the network OS converts abbreviations into full descriptions. In the above example, whether you use ``shut`` or ``shutdown`` to close the port on ``GigabitEthernet1/0/1``, the result in the running config is the same: ``shutdown``. | ||
|
|
||
| Ansible's ``*_config`` modules check the difference between the commands provided and the running configuration. Because existing configuration is always expressed long-form, the ``*_config`` modules will always return ``changed=true`` if you use abbreviations. |
There was a problem hiding this comment.
suggestion: check the text difference?
There was a problem hiding this comment.
thanks, I've made some changes to this bit and I think it's better now
ansibot
removed
the
needs_revision
acozine
moved this from Done
to Backport to 2.5
in Ansible-maintained Collections Documentation
(cherry picked from commit ea99cf3)
acozine
moved this from Backport to 2.5
to Done
in Ansible-maintained Collections Documentation
SUMMARY
Closes #37935
Closes #37866
Closes #37637
Closes #37413
Introduces a Network FAQ for 2.5 to the documentation.
ISSUE TYPE
COMPONENT NAME
Network Documentation
ANSIBLE VERSION
2.5 and higher