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

Question

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?

Answer 1

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

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 

---

You can disable the deprecation warnings

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

---

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.