new common return `created`

[resmo]

Proposal: new common return created

Author: René Moser <@resmo> IRC: resmo

Date: 2017/10/11

• Status: New
• Proposal type: core design
• Targeted Release: future
• Associated PR: n/a
• Estimated time to implement: n/a

Motivation

Giving a more detailed view how the resource changed, allowing to conditionally act on new created resources.

Problems

This allows to fine tune actions depending on new created resources. E.g. only execute this installation script if app was newly installed.

Solution proposal

the new common return is a bool, always returned (default is false): created: <true/false>. A new filter should be added similar to changed/failed/success/skipped

Below an example if a resource was created:

- apt:
    pkg: foo
  register: result

- assert:
    that:
    - result|success
    - result|changed
    - result|created
    - not result|failed
    - not result|skipped

- shell: /bin/bar
  when: result|created

Below an example if a resource was only changed (installed new version of a pkg):

- apt:
    pkg: foo
    state: latest
  register: result

- assert:
    that:
    - result|success
    - result|changed
    - not result|created
    - not result|failed
    - not result|skipped

For some modules, e.g. command, shell, etc. we can not determine if a resource was created, so we return the default created: false.

Dependencies (optional)

Most likely there will be modules, already returning this new reserved keyword created for own purposes. Identify these modules and suggest a different name for the return.

Testing (optional)

Add tests similar to changed

Documentation (optional)

The new common return should be documented here http://docs.ansible.com/ansible/latest/common_return_values.html#common

[willthames]

I'm persuadable on this (not sure how much that counts for anything) but I would like to see more use cases - it is additional effort to introduce this into our modules, I can't think of many benefits (but that doesn't mean there aren't any) and so it should be better justified.

[caphrim007]

in the /bin/bar example provided, (understandably a contrived example) does not a similar feature already exist in creates for the shell module? http://docs.ansible.com/ansible/latest/shell_module.html#options

[caphrim007]

i'm also with @willthames though; impartial. On one hand I like the pipe syntax for checking for this, on the other hand I don't know of the benefits, but am persuadable.