Add automated playbook updater tool that implements the Porting Guide

[gundalow]

Proposal:

Author: John Barker <@gundalow>

Date: 2019-11-04

• Status: New
• Proposal type: Core
• Targeted release: Future, though could be in standarlone tool
• Associated PR: none yet
• Estimated time to implement: month?

Motivation

Currently, each version of Ansible includes a Porting Guide containing manual steps that users are required to look at and manually update their Playbooks, or just keep on running ansible-playbook till the deprecation notices go away.

A Porting Guide

This can include things like:

• Module has been renamed from foo to bar
• A Module's argument has been updated from foo to far
• Change in functionality, such as the default option
• Language changes

Size of Porting Guide

Rounded number of lines porting_guide_2.x.rst:

• 2.0: 400
• 2.3: 230
• 2.4: 230
• 2.5: 400
• 2.6: 110
• 2.7: 250
• 2.8: 560
• 2.9: 730

Partly the size is increasing as we get better at including things in the porting guide, partly as we are forcing users to change more per release.

This could be done in a way so Porting Guide fragments could be contained in Collections and pulled together to go alongside Ansible releases.

Solution proposal

Create a tool to "upgrade" Playbooks from one version of Ansible to the next, similar to:

• phpcs
• Python's 2to3
• Ruby's rubocop

Some of this could be automated, ie:

porting_data_2.9.yml (Steps needed to go from Ansible 2.8 to Ansible 2.9)

renames:
  modules:
    - ec2_ami_find:
      new_module: ec2_ami_facts 
    - kubernetes:
      new_module: k8s_raw 
    - cs_instance_facts:
      new_module: cs_instance_info 
    - net_banner: # Script can't fix this for you.
      manual_message: Use the platform-specific [netos]_banner modules instead
   lookup:
     - redis_kv:
       new_plugin: redism
module_changes:
  - win_firewall_rule:
    arg: force
    removed: true

Example upgrade

New tool ansible-update (or could be related to ansible-lint)

Think it terms of

$ ansible-update  -v .
Upgrading playbooks to Ansible 2.9 format
[I] roles/setup/tasks/main.yml:1 ec2_ami_find -> ec2_ami_facts
[E] roles/switch_basic/tasks/main.yaml:4  Manual update needed for `net_banner` Use the platform-specific [netos]_banner modules instead
$ git diff

diff --git a/roles/setup/tasks/main.yml b/roles/setup/tasks/main.yml
index 49111d4..c0fbfca 100644
--- a/roles/setup/tasks/main.yml
+++ b/roles/setup/tasks/main.yml
@@ -1,3 +1,3 @@
 - name: gather information about an AMI using ami-id
-  ec2_ami_facts:
+  ec2_ami_info:
     image_ids: ami-5b488823

Generating Docs

This, along with https://github.com/ansible/ansible/blob/816e194e375913537b31c2c8e2bd5baa6fdfb308/lib/ansible/modules/network/vyos/_vyos_interface.py#L36-L39 could be used to generate the Porting Guides.

Rather than a list, this could be used to generate a table like debops do, thanks drybjed for the suggestion.

Dependencies (optional)

Explain any dependencies. This section is optional but could be helpful.

• Dependency Docker Modules #1
• Dependency Adding Docker module proposals #2

Testing (optional)

• Various example old Playbooks with expected output

Documentation (optional)

• yes, fixme

Anything else?

[tremble]

The deprecation example you give is deprecating a whole module. There are also cases where we want to deprecate options/defaults. It might be worth adding a something similar for options.

[gundalow]

I still think this is a useful thing. I know it can't ever do everything. I feel like this plus linter would be good for Devtools, thiugh needs to be part of a wider plan, rather than piecemeal.