diff --git a/docs/docsite/rst/collections_guide/collections_using_playbooks.rst b/docs/docsite/rst/collections_guide/collections_using_playbooks.rst index 22f17477ece..3a900a9698f 100644 --- a/docs/docsite/rst/collections_guide/collections_using_playbooks.rst +++ b/docs/docsite/rst/collections_guide/collections_using_playbooks.rst @@ -18,7 +18,7 @@ Once installed, you can reference a collection content by its fully qualified co This works for roles or any type of plugin distributed within the collection: -.. code-block:: yaml +.. code-block:: yaml+jinja - name: Reference collections contents using their FQCNs hosts: all @@ -64,7 +64,7 @@ Using ``collections`` in playbooks In a playbook, you can control the collections Ansible searches for modules and action plugins to execute. However, any roles you call in your playbook define their own collections search order; they do not inherit the calling playbook's settings. This is true even if the role does not define its own ``collections`` keyword. -.. code-block:: yaml +.. code-block:: yaml+jinja - name: Run a play using the collections keyword hosts: all @@ -116,7 +116,7 @@ From inside a playbook: A few recommendations when creating such playbooks, ``hosts:`` should be generic or at least have a variable input. -.. code-block:: yaml +.. code-block:: yaml+jinja - hosts: all # Use --limit or customized inventory to restrict hosts targeted diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index af44d273696..8e3260e3e71 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -90,7 +90,7 @@ A collection skeleton is a directory that looks like a collection directory but An example ``galaxy.yml.j2`` file that accepts an optional dictionary variable ``dependencies`` could look like this: -.. code-block:: yaml +.. code-block:: yaml+jinja namespace: {{ namespace }} name: {{ collection_name }} diff --git a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst index 9f9a8d38164..7c9380921e2 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst @@ -220,7 +220,7 @@ For example, to exclude the :file:`sensitive` folder within the ``playbooks`` fo By default, the ``MANIFEST.in`` style directives would exclude all files by default, but there are default directives in place. Those default directives are described below. To see the directives in use during build, pass ``-vvv`` with the ``ansible-galaxy collection build`` command. -.. code-block:: +.. code-block:: text include meta/*.yml include *.txt *.md *.rst COPYING LICENSE diff --git a/docs/docsite/rst/inventory_guide/intro_patterns.rst b/docs/docsite/rst/inventory_guide/intro_patterns.rst index ac75090a33f..9aa59278d74 100644 --- a/docs/docsite/rst/inventory_guide/intro_patterns.rst +++ b/docs/docsite/rst/inventory_guide/intro_patterns.rst @@ -179,7 +179,7 @@ Slicing at specific items If *i* is negative, the index is relative to the end of sequence *s*: ``len(s) + i`` is substituted. However ``-0`` is ``0``. -.. code-block:: yaml +.. code-block:: python webservers[0] # == cobweb webservers[-1] # == weber @@ -198,7 +198,7 @@ If *i* is greater than *j*, the slice is empty. If *i* is equal to *j*, the *s[i]* is substituted. -.. code-block:: yaml +.. code-block:: python webservers[0:2] # == webservers[0],webservers[1],webservers[2] # == cobweb,webbing,weber diff --git a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst index 3df7870ac9f..63a2e2e8f5d 100644 --- a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst +++ b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst @@ -558,69 +558,66 @@ The following example walks through the integration tests for the ``vyos.vyos.vy ``test/integration/targets/vyos_l3_interfaces/tests/cli/overridden.yaml`` -.. code-block:: yaml +.. code-block:: yaml+jinja --- - - debug: - msg: START vyos_l3_interfaces merged integration tests on connection={{ ansible_connection - }} + - debug: null + msg: START vyos_l3_interfaces merged integration tests on connection={{ ansible_connection }} - import_tasks: _remove_config.yaml - block: - - - import_tasks: _populate.yaml - - - name: Overrides all device configuration with provided configuration - register: result - vyos.vyos.vyos_l3_interfaces: &id001 - config: - - - name: eth0 - ipv4: - - - address: dhcp - - - name: eth1 - ipv4: - - - address: 192.0.2.15/24 - state: overridden - - - name: Assert that before dicts were correctly generated - assert: - that: - - "{{ populate | symmetric_difference(result['before']) |length == 0 }}" - - - name: Assert that correct commands were generated - assert: - that: - - "{{ overridden['commands'] | symmetric_difference(result['commands'])\ - \ |length == 0 }}" - - - name: Assert that after dicts were correctly generated - assert: - that: - - "{{ overridden['after'] | symmetric_difference(result['after']) |length\ - \ == 0 }}" - - - name: Overrides all device configuration with provided configurations (IDEMPOTENT) - register: result - vyos.vyos.vyos_l3_interfaces: *id001 - - - name: Assert that the previous task was idempotent - assert: - that: - - result['changed'] == false - - - name: Assert that before dicts were correctly generated - assert: - that: - - "{{ overridden['after'] | symmetric_difference(result['before']) |length\ - \ == 0 }}" + - import_tasks: _populate.yaml + - name: Overrides all device configuration with provided configuration + register: result + vyos.vyos.vyos_l3_interfaces: + config: + - name: eth0 + ipv4: + - address: dhcp + - name: eth1 + ipv4: + - address: 192.0.2.15/24 + state: overridden + - name: Assert that before dicts were correctly generated + assert: + that: + - "{{ populate | symmetric_difference(result['before']) | length == 0 }}" + - name: Assert that correct commands were generated + assert: + that: + - >- + overridden['commands'] + | symmetric_difference(result['commands']) + | length + == 0 + - name: Assert that after dicts were correctly generated + assert: + that: + - "{{ overridden['after'] | symmetric_difference(result['after']) + | length == 0 }}" + - name: Override device configuration with provided configuration (IDEMPOTENT) + register: result + vyos.vyos.vyos_l3_interfaces: + config: + - name: eth0 + ipv4: + - address: dhcp + - name: eth1 + ipv4: + - address: 192.0.2.15/24 + state: overridden + - name: Assert that the previous task was idempotent + assert: + that: + - result is not changed + - name: Assert that before dicts were correctly generated + assert: + that: + - "{{ overridden['after'] | symmetric_difference(result['before']) + | length == 0 }}" always: - - - import_tasks: _remove_config.yaml + - import_tasks: _remove_config.yaml Detecting test resources at runtime diff --git a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst index 30668dff309..a47dc9a0557 100644 --- a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst +++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst @@ -113,7 +113,7 @@ Be sure to fully understand the security implications of enabling this option. T Before running ``ansible-playbook`` run the following commands to enable logging: -.. code-block:: text +.. code-block:: shell # Specify the location for the log file export ANSIBLE_LOG_PATH=~/ansible.log @@ -140,7 +140,7 @@ To make this a global setting, add the following to your ``ansible.cfg`` file: or enable the environment variable `ANSIBLE_PERSISTENT_LOG_MESSAGES`: -.. code-block:: text +.. code-block:: shell # Enable device interaction logging export ANSIBLE_PERSISTENT_LOG_MESSAGES=True @@ -168,9 +168,9 @@ For Ansible this can be done by ensuring you are only running against one remote `ad hoc` refers to running Ansible to perform some quick command using ``/usr/bin/ansible``, rather than the orchestration language, which is ``/usr/bin/ansible-playbook``. In this case we can ensure connectivity by attempting to execute a single command on the remote device: -.. code-block:: text +.. code-block:: shell - ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k + ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k In the above example, we: @@ -184,7 +184,7 @@ If you have SSH keys configured correctly, you don't need to specify the ``-k`` If the connection still fails you can combine it with the enable_network_logging parameter. For example: -.. code-block:: text +.. code-block:: shell # Specify the location for the log file export ANSIBLE_LOG_PATH=~/ansible.log @@ -208,7 +208,7 @@ The ``Socket path does not exist or cannot be found`` and ``Unable to connect t For example: -.. code-block:: none +.. code-block:: ansible-output fatal: [spine02]: FAILED! => { "changed": false, @@ -221,7 +221,7 @@ For example: or -.. code-block:: none +.. code-block:: ansible-output fatal: [spine02]: FAILED! => { "changed": false, @@ -240,13 +240,13 @@ Suggestions to resolve: If the identified error message from the log file is: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | command timeout triggered, timeout value is 30 secs or -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | persistent connection idle timeout triggered, timeout value is 30 secs @@ -267,7 +267,7 @@ The ``unable to open shell`` message means that the ``ansible-connection`` daemo For example: -.. code-block:: none +.. code-block:: ansible-output TASK [prepare_eos_tests : enable cli on remote device] ************************************************** fatal: [veos01]: FAILED! => {"changed": false, "failed": true, "msg": "unable to open shell"} @@ -276,7 +276,7 @@ For example: or: -.. code-block:: none +.. code-block:: ansible-output TASK [ios_system : configure name_servers] ************************************************************* task path: @@ -303,7 +303,7 @@ Indicates that the remote host you are trying to connect to can not be reached For example: -.. code-block:: yaml +.. code-block:: console 2017-04-04 11:39:48,147 p=15299 u=fred | control socket path is /home/fred/.ansible/pc/ca5960d27a 2017-04-04 11:39:48,147 p=15299 u=fred | current working directory is /home/fred/git/ansible-inc/stable-2.3/test/integration @@ -332,7 +332,7 @@ Occurs if the credentials (username, passwords, or ssh keys) passed to ``ansible For example: -.. code-block:: yaml +.. code-block:: text ESTABLISH CONNECTION FOR USER: cisco on PORT 22 TO ios01 Authentication failed. @@ -342,7 +342,7 @@ Suggestions to resolve: If you are specifying credentials through ``password:`` (either directly or through ``provider:``) or the environment variable `ANSIBLE_NET_PASSWORD` it is possible that ``paramiko`` (the Python SSH library that Ansible uses) is using ssh keys, and therefore the credentials you are specifying are being ignored. To find out if this is the case, disable "look for keys". This can be done like this: -.. code-block:: yaml +.. code-block:: shell export ANSIBLE_PARAMIKO_LOOK_FOR_KEYS=False @@ -363,7 +363,7 @@ When using persistent connections with Paramiko, the connection runs in a backgr For example: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:06:03,486 p=17981 u=fred | using connection plugin network_cli 2017-04-04 12:06:04,680 p=17981 u=fred | connecting to host veos01 returned an error @@ -412,7 +412,7 @@ Error: "No authentication methods available" For example: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | creating new control socket for host veos01:None as user admin 2017-04-04 12:19:05,670 p=18591 u=fred | control socket path is /home/fred/.ansible/pc/ca5960d27a @@ -451,7 +451,7 @@ Persistent connection idle timeout By default, ``ANSIBLE_PERSISTENT_CONNECT_TIMEOUT`` is set to 30 (seconds). You may see the following error if this value is too low: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | persistent connection idle timeout triggered, timeout value is 30 secs @@ -459,7 +459,7 @@ Suggestions to resolve: Increase value of persistent connection idle timeout: -.. code-block:: sh +.. code-block:: shell export ANSIBLE_PERSISTENT_CONNECT_TIMEOUT=60 @@ -477,7 +477,7 @@ By default, ``ANSIBLE_PERSISTENT_COMMAND_TIMEOUT`` is set to 30 (seconds). Prior You may see the following error if this value is too low: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | command timeout triggered, timeout value is 30 secs @@ -486,7 +486,7 @@ Suggestions to resolve: * Option 1 (Global command timeout setting): Increase value of command timeout in configuration file or by setting environment variable. - .. code-block:: yaml + .. code-block:: shell export ANSIBLE_PERSISTENT_COMMAND_TIMEOUT=60 @@ -510,8 +510,8 @@ Suggestions to resolve: Suggestions to resolve: Some modules support a ``timeout`` option, which is different to the ``timeout`` keyword for tasks. - - .. code-block:: yaml + + .. code-block:: yaml+jinja - name: save running-config cisco.ios.ios_command: @@ -521,7 +521,7 @@ Suggestions to resolve: Suggestions to resolve: - + If the module does not support the ``timeout`` option directly, most networking connection plugins can enable similar functionality with the ``ansible_command_timeout`` variable. .. code-block:: yaml @@ -543,7 +543,7 @@ Persistent connection retry timeout By default, ``ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT`` is set to 15 (seconds). You may see the following error if this value is too low: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:35,708 p=18591 u=fred | connect retry timeout expired, unable to connect to control socket 2017-04-04 12:19:35,709 p=18591 u=fred | persistent_connect_retry_timeout is 15 secs @@ -555,7 +555,7 @@ Note: This value should be greater than the SSH timeout value (the timeout value section in the configuration file) and less than the value of the persistent connection idle timeout (connect_timeout). -.. code-block:: yaml +.. code-block:: shell export ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT=30 @@ -668,7 +668,7 @@ network device by first connecting to the host specified in You can also set the proxy target for all hosts by using environment variables. -.. code-block:: sh +.. code-block:: shell export ANSIBLE_SSH_ARGS='-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -693,7 +693,7 @@ from the given custom ssh file path Example ssh config file (~/.ssh/config) --------------------------------------- -.. code-block:: ini +.. code-block:: text Host jumphost HostName jumphost.domain.name.com diff --git a/docs/docsite/rst/os_guide/intro_bsd.rst b/docs/docsite/rst/os_guide/intro_bsd.rst index bcbeba5a227..7657b4ec81d 100644 --- a/docs/docsite/rst/os_guide/intro_bsd.rst +++ b/docs/docsite/rst/os_guide/intro_bsd.rst @@ -157,7 +157,7 @@ The playbook below displays the details -.. code-block:: yaml +.. code-block:: console shell> ANSIBLE_STDOUT_CALLBACK=yaml ansible-playbook -i hosts playbook.yml diff --git a/docs/docsite/rst/os_guide/windows_ssh.rst b/docs/docsite/rst/os_guide/windows_ssh.rst index e55b9049b00..fcd9c338c2f 100644 --- a/docs/docsite/rst/os_guide/windows_ssh.rst +++ b/docs/docsite/rst/os_guide/windows_ssh.rst @@ -128,7 +128,7 @@ SSH key authentication on Windows works in the same way as SSH key authenticatio One difference is that the ``authorized_keys`` file for admin users is not located in the ``.ssh`` folder in the user's profile directory but in ``C:\ProgramData\ssh\administrators_authorized_keys``. It is possible to change the location of the ``authorized_keys`` file for admin users back to the user profile directory by removing, or commenting, the lines in ``C:\ProgramData\ssh\sshd_config`` and restarting the ``sshd`` service. -.. code-block:: +.. code-block:: text Match Group administrators AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys diff --git a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst index 1c4fc845d8c..70cc3327ff2 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst @@ -116,7 +116,9 @@ If you are running legacy playbooks or roles, you may see the debugger enabled a - hosts: test strategy: debug tasks: - ... + - name: Example task + debug: + msg: "This is a debug message" Or in ansible.cfg: diff --git a/docs/docsite/rst/playbook_guide/playbooks_templating.rst b/docs/docsite/rst/playbook_guide/playbooks_templating.rst index 506a17dab3e..5f828c8d9fb 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_templating.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_templating.rst @@ -19,15 +19,15 @@ Ansible parses templates on the control node and passes only the information nee .. note:: Files and data used by the :ref:`template module ` must be utf-8 encoded. - + Jinja2 Example ================== In this example, we want to write the server hostname to its /tmp/hostname. Our directory looks like this: - -.. code-block:: + +.. code-block:: console ├── hostname.yml ├── templates @@ -51,7 +51,7 @@ Our test.j2: .. code-block:: yaml My name is {{ ansible_facts['hostname'] }} - + .. seealso:: diff --git a/docs/docsite/rst/reference_appendices/general_precedence.rst b/docs/docsite/rst/reference_appendices/general_precedence.rst index 7beb76b1c73..2441b7c2a96 100644 --- a/docs/docsite/rst/reference_appendices/general_precedence.rst +++ b/docs/docsite/rst/reference_appendices/general_precedence.rst @@ -167,7 +167,7 @@ This category only applies to things that take direct options, generally modules Outside of task actions, the most recognizable 'direct assignments' are with lookup, filter and test plugins: -.. code:: +.. code:: text lookup('plugin', direct1='value', direct2='value2')