How to mark an Ansible Role in a Collection as deprecated?

I manage an Ansible Collection on Ansible Galaxy with multiple roles in it and want to mark some of those roles as deprecated. How can I do this?

In the Ansible documentation there is only a solution for modules.

Can this be adopted to the roles?

There is no such framework AFAIK. But, you can easily create one on your own. Use the configuration parameter DEPRECATION_WARNINGS. For example, declare defaults

shell> cat roles/foo/defaults/main/deprecation.yml
foo_deprecation_warnings: "{{ lookup('ansible.builtin.config', 'DEPRECATION_WARNINGS')}}"
foo_deprecation:
  removal_version: 2.0.0
  warning_text: Read the release notes on how to migrate

, create a task to display the deprecation warning

shell> cat roles/foo/tasks/deprecation.yml
- name: Deprecation warning
  debug:
    msg: |
      [DEPRECATION WARNING]: This role will be removed from the collection in release {{ foo_deprecation.removal_version }}. {{ foo_deprecation.warning_text }}.
      Deprecation warnings can be disabled by setting deprecation_warnings=False in
      ansible.cfg.      

, and include it conditionally

shell> cat roles/foo/tasks/main.yml
- include_tasks: deprecation.yml
  when:
    - foo_deprecation
    - foo_deprecation_warnings
  run_once: true

- debug:
    msg: Role foo is running ...

When you run the role

shell> cat pb.yml
- hosts: localhost
  roles:
    - foo

you'll see the deprecation warning

<sup>

shell> ansible-playbook pb.yml

PLAY [localhost] ******************************************************************************

TASK [foo : include_tasks] ********************************************************************
included: /export/scratch/tmp7/test-428/roles/foo/tasks/deprecation.yml for localhost

TASK [foo : Deprecation warning] **************************************************************
ok: [localhost] => 
  msg: |-
    [DEPRECATION WARNING]: This role will be removed from the collection in release 2.0.0. Read the release notes on how to migrate.
    Deprecation warnings can be disabled by setting deprecation_warnings=False in
    ansible.cfg.    

TASK [foo : debug] ****************************************************************************
ok: [localhost] => 
  msg: Role foo is running ...

PLAY RECAP ************************************************************************************
localhost: ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

</sup>

<hr>

You can disable the deprecation warnings

<sup>

shell> ANSIBLE_DEPRECATION_WARNINGS=false ansible-playbook pb.yml

PLAY [localhost] ******************************************************************************

TASK [foo : include_tasks] ********************************************************************
skipping: [localhost]

TASK [foo : debug] ****************************************************************************
ok: [localhost] => 
  msg: Role foo is running ...

PLAY RECAP ************************************************************************************
localhost: ok=1    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

</sup>

<hr>

Declare an empty dictionary if you don't want a role to display a deprecation warning

foo_deprecation: 

or don't include the task deprecation.yml.

For Ansible Galaxy as provider of the content there is an option available to Deprecate Content

> You can deprecate Collections and Role repositories that you own from the ‘My Content’ page. ...

Just follow the documentation.

Since Roles are for

> ... group your content in roles, you can easily reuse them and share them with other users.

and just source code, scripts, YAML files, there is nothing like a deprecation warning message for the content itself.

To work around one could implement pre_tasks together with specific messages and behavior. In example like

  pre_tasks:

  - name: Check Ansible User
    fail:
      msg: Do not execute under root!
    when: ansible_user == 'root'

Together with Conditionals it can be used to fail with Custom Message, assert that given expressions are true or in order to print WARNINGs from playbook.

Since there is no module to print WARNING messages out-of-box, it needs to be implemented via a Filter Plugin which can be easily Developed and as shown within the given link or as an own Custom Module warn. One may take note that such approach will create further dependencies for a Role and which would need to be resolved before too.

A workaround for that could be simply

  pre_tasks:

  - name: DEPRECATION WARNING
    fail:
      msg: Use v2 instead!
    when: VERSION == 'v1'
    ignore_errors: true

Other Q&A

• Only allow --check and / or --diff for certain Ansible hosts / groups