Reversible include_tasks

[TimEisler]

Proposal: Reversible include_tasks

Author: Tim Eisler <@TimEisler>

Date: 2021-11-06

• Status: New
• Proposal type: (core design)
• Targeted release: 2.13+
• Associated PR: No PR at this time.
• Estimated time to implement: Already completed.

Motivation

To allow a task file to be shared by a block and a rescue but to run the tasks in reverse order in rescue to achieve an undo.

Problems

The number of YAML files to be maintained can be reduced.

Solution proposal

• Add the optional parameter reverse: True to the include_tasks directive.

- hosts: all
  gather_facts: yes
  vars:
    pip_pkgname: 'bottle'
    path: '/usr/local/{{ pip_pkgname }}'
    marker_file_name: '{{ pip_pkgname }}_installed.txt'

  tasks:
    - block:
      - name: Block. Reversal is not expected
        include_tasks:
          file: ./shared_task_file.yml
      rescue:
      - name: Rescue. Reversal is expected
        include_tasks:
          file: ./shared_task_file.yml
          reverse: true
          apply:
            vars:
              - state: absent

• As shown in the YAML above, the same file is included in both block and rescue.

Dependencies (optional)

• The parameter reverse must be added as a valid option,
• When debugging a play, it should be discosed that reverse was seen,
• tasks in included file must be reversed after they are read from the YAML file and before they are returned to the play.
• the message about the file being included should say when they have been reversed, for example:
  included: /home/ansible/playbooks/BlockRescueIncludeTaskReverse/shared_task_file.yml for localhost (reversed)
• shared task files need to be written with more extensive when: conditionals to know when rescue is active.
• shared task files need to be written to allow rescue to overrdie state to absent.

Testing (optional)

Unit tests should be written to verify the reverse option is accepted.
The existing integration tests for the includes target should be extended to check for reversed task order when reverse: True is used.

Documentation (optional)

Documentation for include_tasks should be revised to list rescue and provide examples; namely, the DOCUMENTATION and EXAMPLES docstrings in lib/ansible/modules/include_tasks.py

Anything else?

I have already implemented this feature in https://github.com/TimEisler/ansible/tree/feature/IncludeTaskReverse

I have documented this in a Gist at https://gist.github.com/TimEisler/c4c5e49d7c05a60c92527a60866c3abd

I have posted a notice about this to the ansible-devel google group on Nov 7, 2021.

Files created or modified by my feature per git diff --name-only devel feature/IncludeTaskReverse are:

lib/ansible/modules/include_tasks.py
lib/ansible/playbook/task_include.py
lib/ansible/plugins/callback/default.py
lib/ansible/plugins/strategy/__init__.py
test/integration/targets/includes/aliases
test/integration/targets/includes/always_includable_tasks.yml
test/integration/targets/includes/block_rescue_includable_tasks.yml
test/integration/targets/includes/include_task_reverse.yml
test/integration/targets/includes/runme.sh
test/integration/targets/includes/setup.yml
test/integration/targets/includes/test_include_task_reverse.py
test/units/playbook/test_helpers.py
test/units/playbook/test_included_file.py