Fix: documentation for per-task timeout

[991jo]

SUMMARY

Corrected the documentation regarding per-task timeouts. The timeout variable is not available in all modules in the way it is shown. See for example

- hosts: all                     
  tasks:                         
    - name: show version         
      cisco.nxos.nxos_command:   
        commands: "show version" 
        retries: 1               
        timeout: 60              

which leads to

fatal: [rcn-lab-s-2.lab.tmn.scc.kit.edu]: FAILED! => {"changed": false, "msg": "Unsupported parameters for (cisco.nxos.nxos_command) module: timeout. Supported parameters include: interval, wait_for (waitfor), retries, commands, match."}

ISSUE TYPE

• Docs Pull Request

+label: docsite_pr

[ansibot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at #docs:ansible.im and on libera IRC at #ansible-docs if you ever want to join us and chat about the docs! We meet there on Tuesdays (see the Ansible calendar) and welcome additions to our weekly agenda items - scroll down to find the upcoming agenda and add a comment to put something new on that agenda.

click here for bot help

[bcoca]

You are confusing the per task timeout keyword with specific module timeout options. The first applies to all modules (it is a task level keyword) and is implemented in the core engine, while the latter is implemented by the module itself.

The documentation you are updating ONLY refers to the second one.

[991jo]

By task level option you refer to this list: https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html#task

But then there is an error in the indentation. Currently it is:

      - name: save running-config
        cisco.ios.ios_command:
          commands: copy running-config startup-config
          provider: "{{ cli }}"
          timeout: 30

But it should be:

      - name: save running-config
        cisco.ios.ios_command:
          commands: copy running-config startup-config
          provider: "{{ cli }}"
        timeout: 30

[bcoca]

yes, that is the task level one, some modules implement their own so it can be confusing and the indentation makes the difference. Also ansible_command_timeout affects ONLY the module ones that implement that (really it affects the networking additional connection plugins cli/cli_conf/httpapi/etc) ... sadly timeout is a very overloaded term.

[991jo]

Okay, so to summarize, there are 3 ways to do it:

1. the task level timeout
2. some modules might have their own timeout
3. some module may use the ansible_command_timeout variable

I think that the documentation does not make these 3 ways and the varying support by different modules very clear.

[bcoca]

• so the 'task timeout' is universal and works at the task/host execution level
• the per module 'timeout' is handled by the module itself
• ansible_command_timeout is handled by the networking connection plugins, works very similar to the module version of 'timeout' but is not exactly the same

[oraNod]

Thanks @991jo