├── ISSUE_TEMPLATE.md ├── LICENSE ├── README.md ├── archive ├── auto-install-roles.md ├── modules-management.md ├── rename_always_run.md └── roles_revamp.md ├── docker ├── docker_container.md ├── docker_diff.md ├── docker_export.md ├── docker_file.md ├── docker_image.md ├── docker_image_facts.md ├── docker_network.md ├── docker_network_facts.md ├── docker_volume.md └── docker_volume_facts.md ├── proposals_process_proposal.md └── re-run-handlers.md /ISSUE_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Proposal: 4 | 5 | *Author*: Your Name <@yourGitHubID> IRC: handle (if different) 6 | 7 | *Date*: 2018-MM-DD 8 | 9 | - Status: New 10 | - Proposal type: (core design, process, ?) 11 | - Targeted release: 12 | - Associated PR: 13 | - Estimated time to implement: 14 | 15 | 16 | ## Motivation 17 | Describe the reasons for this proposal. 18 | 19 | ### Problems 20 | What problems exist that this proposal will solve? 21 | - Problem #1 22 | - Problem #2 23 | - Or just describe the problem if there is just one. 24 | 25 | ## Solution proposal 26 | - Describe your suggested solution here. 27 | - Insert code in snippets if you would like as shown. 28 | ```yaml 29 | - include: main.yml 30 | vars: 31 | var1: val1 32 | ``` 33 | - Be sure to explain how this solves problems. 34 | 35 | ## Dependencies (optional) 36 | Explain any dependencies. This section is optional but could be helpful. 37 | - Dependency #1 38 | - Dependency #2 39 | 40 | ## Testing (optional) 41 | Does / should this require testing, and if so, how? Describe here. This section is optional but could be helpful. 42 | 43 | ## Documentation (optional) 44 | Does / should this require documentation? If so, describe here. This section is optional but could be helpful. 45 | 46 | ## Anything else? 47 | If you'd like to add anything else beyond the above required and optional sections, you are welcome to do so. 48 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | CC0 1.0 Universal 2 | 3 | Statement of Purpose 4 | 5 | The laws of most jurisdictions throughout the world automatically confer 6 | exclusive Copyright and Related Rights (defined below) upon the creator and 7 | subsequent owner(s) (each and all, an "owner") of an original work of 8 | authorship and/or a database (each, a "Work"). 9 | 10 | Certain owners wish to permanently relinquish those rights to a Work for the 11 | purpose of contributing to a commons of creative, cultural and scientific 12 | works ("Commons") that the public can reliably and without fear of later 13 | claims of infringement build upon, modify, incorporate in other works, reuse 14 | and redistribute as freely as possible in any form whatsoever and for any 15 | purposes, including without limitation commercial purposes. These owners may 16 | contribute to the Commons to promote the ideal of a free culture and the 17 | further production of creative, cultural and scientific works, or to gain 18 | reputation or greater distribution for their Work in part through the use and 19 | efforts of others. 20 | 21 | For these and/or other purposes and motivations, and without any expectation 22 | of additional consideration or compensation, the person associating CC0 with a 23 | Work (the "Affirmer"), to the extent that he or she is an owner of Copyright 24 | and Related Rights in the Work, voluntarily elects to apply CC0 to the Work 25 | and publicly distribute the Work under its terms, with knowledge of his or her 26 | Copyright and Related Rights in the Work and the meaning and intended legal 27 | effect of CC0 on those rights. 28 | 29 | 1. Copyright and Related Rights. A Work made available under CC0 may be 30 | protected by copyright and related or neighboring rights ("Copyright and 31 | Related Rights"). Copyright and Related Rights include, but are not limited 32 | to, the following: 33 | 34 | i. the right to reproduce, adapt, distribute, perform, display, communicate, 35 | and translate a Work; 36 | 37 | ii. moral rights retained by the original author(s) and/or performer(s); 38 | 39 | iii. publicity and privacy rights pertaining to a person's image or likeness 40 | depicted in a Work; 41 | 42 | iv. rights protecting against unfair competition in regards to a Work, 43 | subject to the limitations in paragraph 4(a), below; 44 | 45 | v. rights protecting the extraction, dissemination, use and reuse of data in 46 | a Work; 47 | 48 | vi. database rights (such as those arising under Directive 96/9/EC of the 49 | European Parliament and of the Council of 11 March 1996 on the legal 50 | protection of databases, and under any national implementation thereof, 51 | including any amended or successor version of such directive); and 52 | 53 | vii. other similar, equivalent or corresponding rights throughout the world 54 | based on applicable law or treaty, and any national implementations thereof. 55 | 56 | 2. Waiver. To the greatest extent permitted by, but not in contravention of, 57 | applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and 58 | unconditionally waives, abandons, and surrenders all of Affirmer's Copyright 59 | and Related Rights and associated claims and causes of action, whether now 60 | known or unknown (including existing as well as future claims and causes of 61 | action), in the Work (i) in all territories worldwide, (ii) for the maximum 62 | duration provided by applicable law or treaty (including future time 63 | extensions), (iii) in any current or future medium and for any number of 64 | copies, and (iv) for any purpose whatsoever, including without limitation 65 | commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes 66 | the Waiver for the benefit of each member of the public at large and to the 67 | detriment of Affirmer's heirs and successors, fully intending that such Waiver 68 | shall not be subject to revocation, rescission, cancellation, termination, or 69 | any other legal or equitable action to disrupt the quiet enjoyment of the Work 70 | by the public as contemplated by Affirmer's express Statement of Purpose. 71 | 72 | 3. Public License Fallback. Should any part of the Waiver for any reason be 73 | judged legally invalid or ineffective under applicable law, then the Waiver 74 | shall be preserved to the maximum extent permitted taking into account 75 | Affirmer's express Statement of Purpose. In addition, to the extent the Waiver 76 | is so judged Affirmer hereby grants to each affected person a royalty-free, 77 | non transferable, non sublicensable, non exclusive, irrevocable and 78 | unconditional license to exercise Affirmer's Copyright and Related Rights in 79 | the Work (i) in all territories worldwide, (ii) for the maximum duration 80 | provided by applicable law or treaty (including future time extensions), (iii) 81 | in any current or future medium and for any number of copies, and (iv) for any 82 | purpose whatsoever, including without limitation commercial, advertising or 83 | promotional purposes (the "License"). The License shall be deemed effective as 84 | of the date CC0 was applied by Affirmer to the Work. Should any part of the 85 | License for any reason be judged legally invalid or ineffective under 86 | applicable law, such partial invalidity or ineffectiveness shall not 87 | invalidate the remainder of the License, and in such case Affirmer hereby 88 | affirms that he or she will not (i) exercise any of his or her remaining 89 | Copyright and Related Rights in the Work or (ii) assert any associated claims 90 | and causes of action with respect to the Work, in either case contrary to 91 | Affirmer's express Statement of Purpose. 92 | 93 | 4. Limitations and Disclaimers. 94 | 95 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 96 | surrendered, licensed or otherwise affected by this document. 97 | 98 | b. Affirmer offers the Work as-is and makes no representations or warranties 99 | of any kind concerning the Work, express, implied, statutory or otherwise, 100 | including without limitation warranties of title, merchantability, fitness 101 | for a particular purpose, non infringement, or the absence of latent or 102 | other defects, accuracy, or the present or absence of errors, whether or not 103 | discoverable, all to the greatest extent permissible under applicable law. 104 | 105 | c. Affirmer disclaims responsibility for clearing rights of other persons 106 | that may apply to the Work or any use thereof, including without limitation 107 | any person's Copyright and Related Rights in the Work. Further, Affirmer 108 | disclaims responsibility for obtaining any necessary consents, permissions 109 | or other rights required for any use of the Work. 110 | 111 | d. Affirmer understands and acknowledges that Creative Commons is not a 112 | party to this document and has no duty or obligation with respect to this 113 | CC0 or use of the Work. 114 | 115 | For more information, please see 116 | 117 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Ansible Proposals 2 | Repository for sharing and tracking progress on enhancement proposals for Ansible. 3 | 4 | [Create a new proposal](https://github.com/ansible/proposals/issues/new) 5 | 6 | [List of open proposals](https://github.com/ansible/proposals/issues) 7 | 8 | 9 | Note: We use issues (rather than PRs) to track proposals 10 | -------------------------------------------------------------------------------- /archive/auto-install-roles.md: -------------------------------------------------------------------------------- 1 | ### moved to https://github.com/ansible/proposals/issues/7 2 | 3 | # Auto Install Ansible roles 4 | 5 | *Author*: Will Thames <@willthames> 6 | 7 | *Date*: 19/02/2016 8 | 9 | ## Motivation 10 | 11 | To use the latest (or even a specific) version of a playbook with the 12 | appropriate roles, the following steps are typically required: 13 | 14 | ``` 15 | git pull upstream branch 16 | ansible-galaxy install -r path/to/rolesfile.yml -p path/to/rolesdir -f 17 | ansible-playbook run-the-playbook.yml 18 | ``` 19 | 20 | ### Problems 21 | 22 | - The most likely step in this process to be forgotten is the middle step. While we can improve processes and documentation to try and ensure that this step is not skipped, we can improve ansible-playbook so that the step is not required. 23 | - Ansible-galaxy does ot sufficiently handle versioning. 24 | - There is not a consistent format for specifying a role in a playbook or a dependent role in meta/main.yml. 25 | 26 | ## Approaches 27 | 28 | ### Approach 1: Specify rolesfile and rolesdir in playbook 29 | 30 | Provide new `rolesdir` and `rolesfile` keywords: 31 | 32 | ``` 33 | - hosts: application-env 34 | become: True 35 | rolesfile: path/to/rolesfile.yml 36 | rolesdir: path/to/rolesdir 37 | roles: 38 | - roleA 39 | - { role: roleB, tags: role_roleB } 40 | ``` 41 | 42 | Running ansible-playbook against such a playbook would cause the roles listed in 43 | `rolesfile` to be installed in `rolesdir`. 44 | 45 | Add new configuration to allow default rolesfile, default rolesdir and 46 | whether or not to auto update roles (defaulting to False) 47 | 48 | #### Advantages 49 | 50 | - Existing mechanism for roles management is maintained 51 | - Playbooks are not polluted with roles 'meta' information (version, source) 52 | 53 | #### Disadvantage 54 | 55 | - Adds two new keywords 56 | - Adds three new configuration variables for defaults 57 | 58 | ### Approach 2: Allow rolesfile inclusion 59 | 60 | Allow the `roles` section to include a roles file: 61 | 62 | ``` 63 | - hosts: application-env 64 | become: True 65 | roles: 66 | - include: path/to/rolesfile.yml 67 | ``` 68 | 69 | Running this playbook would cause the roles to be updated from the included 70 | roles file. 71 | 72 | This would also be functionally equivalent to specifying the roles file 73 | content within the playbook: 74 | 75 | ``` 76 | - hosts: application-env 77 | become: True 78 | roles: 79 | - src: https://git.example.com/roleA.git 80 | scm: git 81 | version: 0.1 82 | - src: https://git.example.com/roleB.git 83 | scm: git 84 | version: 0.3 85 | tags: role_roleB 86 | ``` 87 | 88 | #### Advantages 89 | 90 | - The existing rolesfile mechanism is maintained 91 | - Uses familiar inclusion mechanism 92 | 93 | #### Disadvantage 94 | 95 | - Separate playbooks would need separate rolesfiles. For example, a provision 96 | playbook and upgrade playbook would likely have some overlap - currently 97 | you can use the same rolesfile with ansible-galaxy so that the same 98 | roles are available but only a subset of roles is used by the smaller 99 | playbook. 100 | - The roles file would need to be able to include playbook features such 101 | as role tagging. 102 | - New configuration defaults would likely still be required (and possibly 103 | an override keyword for rolesdir and role auto update) 104 | 105 | 106 | ### Approach 3: 107 | 108 | *Author*: chouseknecht<@chouseknecht> 109 | 110 | *Date*: 24/02/2016 111 | 112 | This is a combination of ideas taken from IRC, the ansible development group, and conversations at the recent contributor's summit. It also incorporates most of the ideas from Approach 1 (above) with two notables exceptions: 1) it eliminates maintaining a roles file (or what we think of today as requirements.yml); and 2) it does not include the definition of rolesdir in the playbook. 113 | 114 | Here's the approach: 115 | 116 | - Share the role install logic between ansible-playbook and ansible-galaxy so that ansible-playbook can resolve and install missing roles at playbook run time simply by evaluating the playbook. 117 | - Ansible-galaxy installs or preloads roles also by examining a playbook. 118 | - Deprecate support for requirements.yaml (the two points above make it unnecessary). 119 | - Make ansible-playbook auto-downloading of roles configurable in ansible.cfg. In certain circumstance it may be desirable to disable auto-download. 120 | - Provide one format for specifying a role whether in a playbook or in meta/main.yml. Suggested format: 121 | 122 | ``` 123 | { 124 | 'scm': 'git', 125 | 'src': 'http://git.example.com/repos/repo.git', 126 | 'version': 'v1.0', 127 | 'name': 'repo’ 128 | } 129 | ``` 130 | - For roles installed from Galaxy, Galaxy should provide some measure of security against version change. Galaxy should track the commit related to a version. If the role owner changes historical versions (today tags) and thus changes the commit hash, the affected version would become un-installable. 131 | 132 | - Refactor the install process to encompass the following : 133 | 134 | - Idempotency - If a role version is already installed, don’t attempt to install it again. If symlinks are present (see below), don’t break or remove them. 135 | - Provide a --force option that overrides idempotency. 136 | - Install roles via tree-ish references, not just tags or commits (PR exists for this). 137 | - Support a whitelist of role sources. Galaxy should not be automatically assumed to be part of the whitelist. 138 | - Continue to be recursive, allowing roles to have dependencies specified in meta/main.yml. 139 | - Continue to install roles in the roles_path. 140 | - Use a symlink approach to managing role versions in the roles_path. Example: 141 | 142 | ``` 143 | roles/ 144 | briancoca.oracle_java7.v1.0 145 | briancoca.oracle_java7.v2.2 146 | briancoca.oracle_java7.qs3ih6x 147 | briancoca.oracle_java7 => briancoca.oracle_java7.qs3ih6x 148 | ``` 149 | 150 | ## Conclusion 151 | 152 | Feedback is requested to improve any of the above approaches, or provide further approaches to solve this problem. 153 | -------------------------------------------------------------------------------- /archive/modules-management.md: -------------------------------------------------------------------------------- 1 | ### merge was done for version 2.3 2 | 3 | # Proposal: Proposals - Change how we manage modules in Ansible (the product) and the Ansible Community 4 | 5 | - Date: 09 AUGUST, 2016 6 | 7 | - Status: Rewritten from June proposal 8 | 9 | - Proposal Type: Community Development Process. 10 | 11 | - Targeted Release: 2.3 12 | 13 | - Estimated time to Implement: 3-4 months. 14 | 15 | ## Motivation and Problems 16 | There are currently two module repositories: ansible-modules-core, and ansible-modules-extras. Traditionally this has been recognized to mean that there is a standard for Core modules (since they are to be supported by the Ansible Core team and Red Hat) and Extras (modules that are part of Ansible, but more broadly contributed to and less supported). In practice, Extras became roughly the same thing as Core since both Core and Extras are distributed with Ansible and supported by the Ansible Core team. 17 | 18 | That condition had the unintended consequences of forcing the Core team to set the requirements for Extras modules to be roughly the same as Core. The result was that lots of modules contributed by the Ansible community were either rejected or asked to reach a certain level of robustness or feature-completion for inclusion. This gave the community little room to have "starter" functionality, or a place to contribute simpler or differentiated functionality that is not necessarily a part of the "Core" product, but is nonetheless a good place to get other functionality into ansible. 19 | 20 | Having multiple repos also made it more difficult for contributors to contribute things besides the module itself. module_utils and tests for modules would have to be contributed to the main ansible repository even though the module itself lived in the ansible-modules-extras repository. Bugs for modules might end up submitted against the main ansible repository or the ansible-modules-core repository even though the module lived in ansible-modules-extras. 21 | 22 | ## Solution 23 | Ansible Core team and Contributors (from the Contributor Summit at the 2016 Ansible Fest San Francisco) propose to create categories of ansible Modules where Modules are grouped by a rough category of like-functionality (Nagios Modules would be grouped together, as would AWS, VMware, etc). There are a large number of implications for that working in the Ansible workflow and Community: 24 | - There *will not* be multiple repos. There will be one overall repo in github for all of Ansible. 25 | - We will remove the /{core,extra}/ par of the directory structure 26 | - `lib/ansible/modules/core/commands/shell.py` -> `lib/ansible/modules/commands/shell.py` 27 | - We will start tagging modules to imply a "state" that the modules is in. 28 | - States cover both how usable the module is and how the module is supported. 29 | Full proposal with list of states and format of metadata here: 30 | - https://github.com/ansible/proposals/issues/30 31 | - Github Issues and PRs 32 | - All issues will be associated with one repo, since there will be only one repo! 33 | - Move and close pr’s and issues so they end up in the right place. 34 | - *Existing PRs that are in flight will have to be reviewed and moved.* 35 | - Packaging 36 | - Sometime towards 2.3 (early to mid 2017) we will split packaging along functionality lines, *not* along support lines. The reason for this one is that it decreases the likelihood that that modules would move among packages, which would be a major headache for users. 37 | - Rely on tagging in metadata to describe support levels rather than either packaging or repositories. 38 | 39 | ## Before Merge 40 | - Ensure the sub directories under `ansible-modules*/` are alined, some modules may need `git mv` in advance to ensure categories are the same 41 | - Define metadata format -- Sooner is better as many things depend on this 42 | - Update `validate-modules` to enforce this, though should be configured to only WARN initially apart from on new modules 43 | - Define tags we’re using for metadata(Toshio) 44 | - Code for PluginLoader to extract metadata and associate it with modules in a way that other code can emit warnings based on the metadata. 45 | - packaging -- setup.py needs to generate separate manifests via manifests 46 | - `--version` updated 47 | - ansible doc generation will need to change. 48 | - Replace repo label with metadata about supported by Ansible vs supported by Community 49 | - Update "To submit an update to module docs, edit the 'DOCUMENTATION' metadata in the core and extras modules source repositories." 50 | - Rpm/Deb and pip packaging concerns… think we can see how to address things for rpm and deb but pip will need thought. Somewhat mitigated by splitting packages via function rather than support but still some hard problems here. 51 | - Scripts needed to migrate PRs. Maybe migrate issues as well? 52 | - Script or procedure to combine the repos. 53 | - Script or update to the release playbook to generate multiple tarballs 54 | - Update to code that drives testing to handle single repo (targeted PR testing may be harder. Other things are just different) 55 | - Bot code needs to be updated to handle metadata - policy differences for ansible supported vs community supported and handling of metadata at all. 56 | - Documentation 57 | - How to develop 58 | - ./README.md 59 | - ./lib/ansible/modules/core/CONTRIBUTING.md 60 | - ./lib/ansible/modules/extras/GUIDELINES.md 61 | - ./lib/ansible/modules/extras/CONTRIBUTING.md 62 | - ./docsite/_themes/srtd/footer.html 63 | - ./docsite/rst/developing_modules.rst 64 | - ./docsite/rst/modules_extra.rst 65 | - ./docsite/rst/community.rst 66 | - ./docsite/rst/dev_guide/developing_modules.rst 67 | - ./docsite/rst/developing_modules.rst 68 | - ./docsite/rst/modules_extra.rst 69 | - ./docsite/rst/community.rst 70 | - ./docsite/rst/dev_guide/developing_modules.rst 71 | - ./docsite/rst/modules_core.rst 72 | - ./docsite/rst/common_return_values.rst 73 | - Functional 74 | - ./lib/ansible/modules/core/source_control/git.py 75 | - ./lib/ansible/modules/core/system/mount.py 76 | - ./lib/ansible/modules/core/system/cron.py 77 | - ./lib/ansible/modules/core/packaging/os/apt.py 78 | - ./lib/ansible/modules/extras/cloud/amazon/ec2_customer_gateway.py 79 | - ./lib/ansible/module_utils/ismount.py 80 | - ./lib/ansible/plugins/lookup/password.py 81 | - ./ticket_stubs/_module_issue_move.md 82 | - ./ticket_stubs/_module_pr_move.md 83 | - ./ticket_stubs/module_repo.md 84 | - ./hacking/unify_repos.sh 85 | - ./hacking/module_formatter.py 86 | 87 | ## During Merge 88 | 89 | - Lockdown 90 | - Remove git commit rights to ansible-modules-core and ansible-modules-extras 91 | - Migrate 92 | - Migrate (with history) ansible-modules-core and ansible-modules-extras 93 | - https://github.com/ansible/ansible/blob/devel/hacking/unify_repos.sh 94 | - Migrate open issues 95 | - Use Bot to add automated link to migrate tool 96 | - Give users a message and link to web tool to migrate 97 | - After some time, migrate rest of open issues for the users via the web tool (loses ownership but we can CC the owner. They’ll just lose the ability to close/open/etc themselves) 98 | - Migrate PRs 99 | - Do we need a script here 100 | - Similar to GitHubs’s manual steps for merging a PR 101 | - We’re not sure if we can do this… It’s not easy as the files could change location and commit hashes will be different. Can we drive this via git format-patch? Can we make a tool that migrates what it can and only then punt on the rest? 102 | - We could write a script that will do this but the user would have to run it as PRs need to come from a fork of ansible/ansible that the user controls 103 | - Restrict permission on ansible-modules-core ansible-modules-extras 104 | - Restrict writing to `devel` on the two module branches 105 | - Change issue templates & Bot to auto close Issues 106 | - Unlock any branches as needed 107 | 108 | ## After Merge 109 | 110 | - Re-enable commit rights (needed for new releases on the stable-2.x branches) 111 | - Allocate lots of time in schedule to deal with fallout 112 | - Revisit the discussion regarding splitting the distribution into multiple packages 113 | - Ability to release groups of modules on their own, e.g. (modules-extras) could be released more often that Ansible Core Program 114 | - It hasn't yet been decided if we will split into multiple packages 115 | 116 | ## Long time after Merge 117 | 118 | - Close all Issues & PRs in old repo (that were created a long time ago - Newer PRs may exist for bugfixes for 2.0 or 2.1) 119 | -------------------------------------------------------------------------------- /archive/rename_always_run.md: -------------------------------------------------------------------------------- 1 | ### THIS WAS IMPLMENTENTED AS implemented as `check_mode: false|true` to override the command line check mode state 2 | 3 | # Rename always_run to ignore_checkmode 4 | 5 | *Author*: René Moser <@resmo> 6 | 7 | *Date*: 02/03/2016 8 | 9 | ## Motivation 10 | 11 | The task argument `always_run` is misleading. 12 | 13 | Ansible is known to be readable by users without deep knowledge of creating playbooks, they do not understand 14 | what `always_run` does at the first glance. 15 | 16 | ### Problems 17 | 18 | The following looks scary if you have no idea, what `always_run` does: 19 | 20 | ``` 21 | - shell: dangerous_cleanup.sh 22 | when: cleanup == "yes" 23 | always_run: yes 24 | ``` 25 | 26 | You have a conditional but also a word that says `always`. This is a conflict in terms of understanding. 27 | 28 | ## Solution Proposal 29 | 30 | Deprecate `always_run` by rename it to `ignore_checkmode`: 31 | 32 | ``` 33 | - shell: dangerous_cleanup.sh 34 | when: cleanup == "yes" 35 | ignore_checkmode: yes 36 | ``` 37 | -------------------------------------------------------------------------------- /archive/roles_revamp.md: -------------------------------------------------------------------------------- 1 | ### THIS WAS IMPLMENTENTED AS include_role 2 | 3 | # Proposal: Revamp Roles 4 | 5 | *Author*: Brian Coca <@bcoca> 6 | 7 | *Date*: 04/01/2016 8 | 9 | - Status: New 10 | - Proposal type: core design 11 | - Targeted Release: 2.2 12 | - PR for Comments: 13 | - Estimated time to implement: 4 weeks 14 | 15 | 16 | ## Motivation 17 | Roles are a good way to share and reuse resources, but they are a bit limited in application. 18 | This proposal aims at expanding the usefulness and reusability of roles. 19 | 20 | ### Problems 21 | Roles lack flexibility in execution and inclusion. 22 | 23 | ## Solution proposal 24 | - Add exec_main flag to roles (default True to keep current behaviour), when false a role will not execute tasks/main.yml in `roles:` section of a play. 25 | ``` 26 | - roles: 27 | - role: myrole 28 | exec_main: no 29 | ``` 30 | - Expand includes to be able to execute 'role tasks' in 'role context'. 31 | ``` 32 | - include: main.yml 33 | role: myrole 34 | 35 | - include: role=myrole other.yml 36 | vars: 37 | var1: val1 38 | ``` 39 | This allows for a more controlled execution and easier reuse of roles and it's resources. 40 | -------------------------------------------------------------------------------- /docker/docker_container.md: -------------------------------------------------------------------------------- 1 | # Docker_Container Module Proposal 2 | 3 | ## Purpose and Scope: 4 | 5 | The purpose of docker_container is to manage the lifecycle of a container. The module will provide a mechanism for 6 | moving the container between absent, present, stopped and started states. 7 | 8 | docker_container will also support pulling images from a local or remote registry prior to creating a container. If 9 | the state of a container is present or started and the image is not available, the module will attempt to pull the 10 | image from the default registry. An option will be provided to override this behavior and always pull the latest 11 | version of an image prior to building a container. 12 | 13 | Docker_container will manage a container using docker-py to communicate with either a local or remote API. It will 14 | support API versions >= 1.14. The minimum supported version of docker-py has not been decided. 15 | 16 | API connection details will be handled externally in a shared utility module. 17 | 18 | Registry connectivity and image pulling will be handled externally in a module shared between docker_container and 19 | docker_image modules. 20 | 21 | ## Parameters: 22 | 23 | Docker_container will accept the parameters listed below. An attempt has been made to represent all the options available to 24 | docker's create, kill, pause, run, rm, start, stop and update commands. 25 | 26 | Parameters for connecting to the API are not listed here. They are included in the common utility module mentioned above. 27 | 28 | ``` 29 | blkio_weight: 30 | description: 31 | - Block IO (relative weight), between 10 and 1000. 32 | default: null 33 | 34 | capabilities: 35 | description: 36 | - List of capabilities to add to the container. 37 | default: null 38 | 39 | command: 40 | description: 41 | - Command or list of commands to execute in the container when it starts. 42 | default: null 43 | 44 | cpu_period: 45 | description: 46 | - Limit CPU CFS (Completely Fair Scheduler) period 47 | default: 0 48 | 49 | cpu_quota: 50 | description: 51 | - Limit CPU CFS (Completely Fair Scheduler) quota 52 | default: 0 53 | 54 | cpuset_cpus: 55 | description: 56 | - CPUs in which to allow execution C(1,3) or C(1-3). 57 | default: null 58 | 59 | cpuset_mems: 60 | description: 61 | - Memory nodes (MEMs) in which to allow execution C(0-3) or C(0,1) 62 | default: null 63 | 64 | cpu_shares: 65 | description: 66 | - CPU shares (relative weight). 67 | default: null 68 | 69 | detach: 70 | description: 71 | - Enable detached mode to leave the container running in background. 72 | If disabled, fail unless the process exits cleanly. 73 | default: true 74 | 75 | devices: 76 | description: 77 | - List of host device bindings to add to the container. Each binding is a mapping expressed 78 | in the format: :: 79 | default: null 80 | 81 | dns_servers: 82 | description: 83 | - List of custom DNS servers. 84 | default: null 85 | 86 | dns_search_domains: 87 | description: 88 | - List of custom DNS search domains. 89 | default: null 90 | 91 | env: 92 | description: 93 | - Dictionary of key,value pairs. 94 | default: null 95 | 96 | entrypoint: 97 | description: 98 | - String or list of commands that overwrite the default ENTRYPOINT of the image. 99 | default: null 100 | 101 | etc_hosts: 102 | description: 103 | - Dict of host-to-IP mappings, where each host name is key in the dictionary. Hostname will be added to the 104 | container's /etc/hosts file. 105 | default: null 106 | 107 | exposed_ports: 108 | description: 109 | - List of additional container ports to expose for port mappings or links. 110 | If the port is already exposed using EXPOSE in a Dockerfile, it does not 111 | need to be exposed again. 112 | default: null 113 | aliases: 114 | - exposed 115 | 116 | force_kill: 117 | description: 118 | - Use with absent, present, started and stopped states to use the kill command rather 119 | than the stop command. 120 | default: false 121 | 122 | groups: 123 | description: 124 | - List of additional group names and/or IDs that the container process will run as. 125 | default: null 126 | 127 | hostname: 128 | description: 129 | - Container hostname. 130 | default: null 131 | 132 | ignore_image: 133 | description: 134 | - When state is present or started the module compares the configuration of an existing 135 | container to requested configuration. The evaluation includes the image version. If 136 | the image vesion in the registry does not match the container, the container will be 137 | rebuilt. To stop this behavior set ignore_image to true. 138 | default: false 139 | 140 | image: 141 | description: 142 | - Repository path and tag used to create the container. If an image is not found or pull is true, the image 143 | will be pulled from the registry. If no tag is included, 'latest' will be used. 144 | default: null 145 | 146 | interactive: 147 | description: 148 | - Keep stdin open after a container is launched, even if not attached. 149 | default: false 150 | 151 | ipc_mode: 152 | description: 153 | - Set the IPC mode for the container. Can be one of 154 | 'container:' to reuse another container's IPC namespace 155 | or 'host' to use the host's IPC namespace within the container. 156 | default: null 157 | 158 | keep_volumes: 159 | description: 160 | - Retain volumes associated with a removed container. 161 | default: true 162 | 163 | kill_signal: 164 | description: 165 | - Override default signal used to kill a running container. 166 | default null: 167 | 168 | kernel_memory: 169 | description: 170 | - Kernel memory limit (format: []). Number is a positive integer. 171 | Unit can be one of b, k, m, or g. Minimum is 4M. 172 | default: 0 173 | 174 | labels: 175 | description: 176 | - Dictionary of key value pairs. 177 | default: null 178 | 179 | links: 180 | description: 181 | - List of name aliases for linked containers in the format C(container_name:alias) 182 | default: null 183 | 184 | log_driver: 185 | description: 186 | - Specify the logging driver. 187 | choices: 188 | - json-file 189 | - syslog 190 | - journald 191 | - gelf 192 | - fluentd 193 | - awslogs 194 | - splunk 195 | defult: json-file 196 | 197 | log_options: 198 | description: 199 | - Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/ 200 | for details. 201 | required: false 202 | default: null 203 | 204 | mac_address: 205 | description: 206 | - Container MAC address (e.g. 92:d0:c6:0a:29:33) 207 | default: null 208 | 209 | memory: 210 | description: 211 | - Memory limit (format: []). Number is a positive integer. 212 | Unit can be one of b, k, m, or g 213 | default: 0 214 | 215 | memory_reservation: 216 | description: 217 | - Memory soft limit (format: []). Number is a positive integer. 218 | Unit can be one of b, k, m, or g 219 | default: 0 220 | 221 | memory_swap: 222 | description: 223 | - Total memory limit (memory + swap, format:[]). 224 | Number is a positive integer. Unit can be one of b, k, m, or g. 225 | default: 0 226 | 227 | memory_swappiness: 228 | description: 229 | - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. 230 | default: 0 231 | 232 | name: 233 | description: 234 | - Assign a name to a new container or match an existing container. 235 | - When identifying an existing container name may be a name or a long or short container ID. 236 | required: true 237 | 238 | network_mode: 239 | description: 240 | - Connect the container to a network. 241 | choices: 242 | - bridge 243 | - container: 244 | - host 245 | - none 246 | default: null 247 | 248 | networks: 249 | description: 250 | - Dictionary of networks to which the container will be connected. The dictionary must have a name key (the name of the network). 251 | Optional keys include: aliases (a list of container aliases), and links (a list of links in the format C(container_name:alias)). 252 | default: null 253 | 254 | oom_killer: 255 | desription: 256 | - Whether or not to disable OOM Killer for the container. 257 | default: false 258 | 259 | paused: 260 | description: 261 | - Use with the started state to pause running processes inside the container. 262 | default: false 263 | 264 | pid_mode: 265 | description: 266 | - Set the PID namespace mode for the container. Currenly only supports 'host'. 267 | default: null 268 | 269 | privileged: 270 | description: 271 | - Give extended privileges to the container. 272 | default: false 273 | 274 | published_ports: 275 | description: 276 | - List of ports to publish from the container to the host. 277 | - Use docker CLI syntax: C(8000), C(9000:8000), or C(0.0.0.0:9000:8000), where 8000 is a 278 | container port, 9000 is a host port, and 0.0.0.0 is a host interface. 279 | - Container ports must be exposed either in the Dockerfile or via the C(expose) option. 280 | - A value of ALL will publish all exposed container ports to random host ports, ignoring 281 | any other mappings. 282 | aliases: 283 | - ports 284 | 285 | pull: 286 | description: 287 | - If true, always pull the latest version of an image. Otherwise, will only pull an image 288 | when missing. 289 | default: false 290 | 291 | read_only: 292 | description: 293 | - Mount the container's root file system as read-only. 294 | default: false 295 | 296 | recreate: 297 | description: 298 | - Use with present and started states to force the re-creation of an existing container. 299 | default: false 300 | 301 | registry: 302 | description: 303 | - Registry URL from which to pull images. If not specified, images will be pulled from 304 | the default registry found in the local docker config.json file. 305 | default: null 306 | 307 | restart: 308 | description: 309 | - Use with started state to force a matching container to be stopped and restarted. 310 | default: false 311 | 312 | restart_policy: 313 | description: 314 | - Container restart policy. 315 | choices: 316 | - on-failure 317 | - always 318 | default: on-failure 319 | 320 | restart_retries: 321 | description: 322 | - Use with restart policy to control maximum number of restart attempts. 323 | default: 0 324 | 325 | shm_size: 326 | description: 327 | - Size of `/dev/shm`. The format is ``. `number` must be greater than `0`. 328 | Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). 329 | - Ommitting the unit defaults to bytes. If you omit the size entirely, the system uses `64m`. 330 | default: null 331 | 332 | security_opts: 333 | description: 334 | - List of security options in the form of C("label:user:User") 335 | default: null 336 | 337 | state: 338 | description: 339 | - "absent" - A container matching the specified name will be stopped and removed. Use force_kill to kill the container 340 | rather than stopping it. Use keep_volumes to retain volumes associated with the removed container. 341 | 342 | - "present" - Asserts the existence of a container matching the name and any provided configuration parameters. If no 343 | container matches the name, a container will be created. If a container matches the name but the provided configuration 344 | does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and re-created 345 | with the requested config. Image version will be taken into account when comparing configuration. To ignore image 346 | version use the ignore_image option. Use the recreate option to force the re-creation of the matching container. Use 347 | force_kill to kill the container rather than stopping it. Use keep_volumes to retain volumes associated with a removed 348 | container. 349 | 350 | - "started" - Asserts there is a running container matching the name and any provided configuration. If no container 351 | matches the name, a container will be created and started. If a container matching the name is found but the 352 | configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed 353 | and a new container will be created with the requested configuration and started. Image version will be taken into 354 | account when comparing configuration. To ignore image version use the ignore_image option. Use recreate to always 355 | re-create a matching container, even if it is running. Use restart to force a matching container to be stopped and 356 | restarted. Use force_kill to kill a container rather than stopping it. Use keep_volumes to retain volumes associated 357 | with a removed container. 358 | 359 | - "stopped" - a container matching the specified name will be stopped. Use force_kill to kill a container rather than 360 | stopping it. 361 | 362 | required: false 363 | default: started 364 | choices: 365 | - absent 366 | - present 367 | - stopped 368 | - started 369 | 370 | stop_signal: 371 | description: 372 | - Override default signal used to stop the container. 373 | default: null 374 | 375 | stop_timeout: 376 | description: 377 | - Number of seconds to wait for the container to stop before sending SIGKILL. 378 | required: false 379 | 380 | trust_image_content: 381 | description: 382 | - If true, skip image verification. 383 | default: false 384 | 385 | tty: 386 | description: 387 | - Allocate a psuedo-TTY. 388 | default: false 389 | 390 | ulimits: 391 | description: 392 | - List of ulimit options. A ulimit is specified as C(nofile:262144:262144) 393 | default: null 394 | 395 | user: 396 | description 397 | - Sets the username or UID used and optionally the groupname or GID for the specified command. 398 | - Can be [ user | user:group | uid | uid:gid | user:gid | uid:group ] 399 | default: null 400 | 401 | uts: 402 | description: 403 | - Set the UTS namespace mode for the container. 404 | default: null 405 | 406 | volumes: 407 | description: 408 | - List of volumes to mount within the container. 409 | - 'Use docker CLI-style syntax: C(/host:/container[:mode])' 410 | - You can specify a read mode for the mount with either C(ro) or C(rw). 411 | - SELinux hosts can additionally use C(z) or C(Z) to use a shared or 412 | private label for the volume. 413 | default: null 414 | 415 | volume_driver: 416 | description: 417 | - The container's volume driver. 418 | default: none 419 | 420 | volumes_from: 421 | description: 422 | - List of container names or Ids to get volumes from. 423 | default: null 424 | ``` 425 | 426 | 427 | ## Examples: 428 | 429 | ``` 430 | - name: Create a data container 431 | docker_container: 432 | name: mydata 433 | image: busybox 434 | volumes: 435 | - /data 436 | 437 | - name: Re-create a redis container 438 | docker_container: 439 | name: myredis 440 | image: redis 441 | command: redis-server --appendonly yes 442 | state: present 443 | recreate: yes 444 | expose: 445 | - 6379 446 | volumes_from: 447 | - mydata 448 | 449 | - name: Restart a container 450 | docker_container: 451 | name: myapplication 452 | image: someuser/appimage 453 | state: started 454 | restart: yes 455 | links: 456 | - "myredis:aliasedredis" 457 | devices: 458 | - "/dev/sda:/dev/xvda:rwm" 459 | ports: 460 | - "8080:9000" 461 | - "127.0.0.1:8081:9001/udp" 462 | env: 463 | SECRET_KEY: ssssh 464 | 465 | 466 | - name: Container present 467 | docker_container: 468 | name: mycontainer 469 | state: present 470 | recreate: yes 471 | forcekill: yes 472 | image: someplace/image 473 | command: echo "I'm here!" 474 | 475 | 476 | - name: Start 4 load-balanced containers 477 | docker_container: 478 | name: "container{{ item }}" 479 | state: started 480 | recreate: yes 481 | image: someuser/anotherappimage 482 | command: sleep 1d 483 | with_sequence: count=4 484 | 485 | -name: remove container 486 | docker_container: 487 | name: ohno 488 | state: absent 489 | 490 | - name: Syslogging output 491 | docker_container: 492 | name: myservice 493 | state: started 494 | log_driver: syslog 495 | log_opt: 496 | syslog-address: tcp://my-syslog-server:514 497 | syslog-facility: daemon 498 | syslog-tag: myservice 499 | 500 | ``` 501 | 502 | ## Returns: 503 | 504 | The JSON object returned by the module will include a *results* object providing `docker inspect` output for the affected container. 505 | 506 | ``` 507 | { 508 | changed: True, 509 | failed: False, 510 | check_mode: False, 511 | actions: [ list of performed actions ] 512 | results: { 513 | < container inspection output > 514 | } 515 | } 516 | ``` 517 | 518 | ## Get Involved 519 | 520 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 521 | 522 | Review and contribute to [the code](https://github.com/ansible/docker). 523 | 524 | ## Author 525 | 526 | [Chris Houseknecht] (https://github.com/chouseknecht) 527 | 528 | [@chouseknecht](https://twitter.com/chouseknecht) 529 | 530 | 531 | -------------------------------------------------------------------------------- /docker/docker_diff.md: -------------------------------------------------------------------------------- 1 | # Docker Diff Modules Proposal 2 | 3 | ## Purpose and Scope 4 | 5 | The docker_diff module will provide a mechanism for retrieving a list of changed files from a container's 6 | file system. 7 | 8 | Docker_diff will manage a container using docker-py to communicate with either a local or remote API. It will 9 | support API versions >= 1.14. The minimum supported version of docker-py has not been decided. 10 | 11 | API connection details will be handled externally in a shared utility module similar to how other cloud modules operate. 12 | 13 | ## Parameters 14 | 15 | Docker_diff accepts the parameters listed below. API connection parameters will be part of a shared utility module 16 | as mentioned above. 17 | 18 | ``` 19 | name: 20 | description: 21 | - Provide one or more container names or IDs. For each container a list of changed files and directories found on the 22 | container's file system will be returned. 23 | default: null 24 | required: true 25 | 26 | event_type: 27 | description: 28 | - Select the specific event type to list in the diff output. 29 | choices: 30 | - all 31 | - add 32 | - delete 33 | - change 34 | default: all 35 | ``` 36 | 37 | ## Examples 38 | 39 | ``` 40 | - name: List all differences for multiple containers. 41 | docker_diff: 42 | diff: 43 | - mycontainer1 44 | - mycontainer2 45 | 46 | - name: Included changed files only in diff output 47 | docker_diff: 48 | diff: 49 | - mycontainer1 50 | event_type: change 51 | ``` 52 | 53 | ## Returns 54 | 55 | ``` 56 | { 57 | diff: { 58 | mycontainer1: [ 59 | { state: 'C', path: '/dev' }, 60 | { state: 'A', path: '/dev/kmsg' }, 61 | { state: 'C', path: '/etc' }, 62 | { state: 'A', path: '/etc/mtab' } 63 | ], 64 | mycontainer2: [ 65 | { state: 'C', path: '/foo' }, 66 | { state: 'A', path: '/foo/bar.txt' } 67 | ] 68 | } 69 | } 70 | ``` 71 | 72 | 73 | ## Get Involved 74 | 75 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 76 | 77 | Review and contribute to [the code](https://github.com/ansible/docker). 78 | 79 | ## Author 80 | 81 | [Chris Houseknecht] (https://github.com/chouseknecht) 82 | 83 | [@chouseknecht](https://twitter.com/chouseknecht) 84 | -------------------------------------------------------------------------------- /docker/docker_export.md: -------------------------------------------------------------------------------- 1 | # Docker_Export Modules Proposal 2 | 3 | ## Purpose and Scope 4 | 5 | The purpose of docker_export is providing the ability to export a container's entire filesystem as a tar archive. 6 | 7 | Docker_export will manage a container using docker-py to communicate with either a local or remote API. It will 8 | support API versions >= 1.14. The minimum supported version of docker-py has not been decided. 9 | 10 | API connection details will be handled externally in a shared utility module similar to how other cloud modules operate. 11 | 12 | ## Parameters 13 | 14 | Docker_export accepts the parameters listed below. API connection parameters will be part of a shared utility module 15 | as mentioned above. 16 | 17 | ``` 18 | name: 19 | description: 20 | - Provide a container name or ID to have it's file system exported. 21 | default: null 22 | required: true 23 | 24 | dest: 25 | description: 26 | - The path and name of the destination archive. 27 | default: defaults to the name + '.tar' 28 | ``` 29 | 30 | ## Examples 31 | 32 | ``` 33 | - name: Export container filesystem 34 | docker_file: 35 | export: container1 36 | dest: /tmp/conainer1.tar 37 | ``` 38 | 39 | ## Returns 40 | 41 | ``` 42 | { 43 | changed: true 44 | export: { 45 | src: container_name, 46 | dest: local/path/archive_name.tar 47 | } 48 | } 49 | 50 | ``` 51 | 52 | 53 | ## Get Involved 54 | 55 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 56 | 57 | Review and contribute to [the code](https://github.com/ansible/docker). 58 | 59 | ## Author 60 | 61 | [Chris Houseknecht] (https://github.com/chouseknecht) 62 | 63 | [@chouseknecht](https://twitter.com/chouseknecht) 64 | -------------------------------------------------------------------------------- /docker/docker_file.md: -------------------------------------------------------------------------------- 1 | # Docker File Module Proposal 2 | 3 | ## Purpose and Scope 4 | 5 | The purpose of docker_file is to provide for retrieving a file or folder from a container's file system, or 6 | inserting a file or folder into a container. 7 | 8 | Docker_file will manage a container using docker-py to communicate with either a local or remote API. It will 9 | support API versions >= 1.14. The minimum supported version of docker-py has not been decided. 10 | 11 | API connection details will be handled externally in a shared utility module similar to how other cloud modules operate. 12 | 13 | ## Parameters 14 | 15 | Docker_file accepts the parameters listed below. API connection parameters will be part of a shared utility module 16 | as mentioned above. 17 | 18 | ``` 19 | dest: 20 | description: 21 | - Destination path of copied files. If the destination is a container file system, precede the path with a 22 | container name or ID + ':'. For example, C(mycontainer:/path/to/file.txt). If the destination path does not 23 | exist, it will be created. If the destination path exists on a the local filesystem, it will not be overwritten. 24 | Use the force option to overwrite existing files on the local filesystem. 25 | default: null 26 | required: true 27 | 28 | follow_link: 29 | description: 30 | - Follow symbolic links in the src path. If src is local and file is a symbolic link, the symbolic link, not the 31 | target is copied by default. To copy the link target and not the link, set follow_link to true. 32 | default: false 33 | 34 | src: 35 | description: 36 | - The source path of file(s) to be copied. If source files are found on the container's file system, precede the 37 | path with the container name or ID + ':'. For example, C(mycontainer:/path/to/files). 38 | default: null 39 | required: yes 40 | 41 | ``` 42 | 43 | ## Examples 44 | 45 | ``` 46 | - name: Copy files from the local file system to a container's file system 47 | docker_file: 48 | src: /tmp/rpm 49 | dest: "mycontainer:/tmp" 50 | follow_links: yes 51 | 52 | - name: Copy files from the container to the local filesystem and overwrite existing files 53 | docker_file: 54 | src: "container1:/var/lib/data" 55 | dest: /tmp/container1/data 56 | force: yes 57 | 58 | ``` 59 | 60 | ## Returns 61 | 62 | ``` 63 | { 64 | files: { 65 | src: /tmp/rpms, 66 | dest: mycontainer:/tmp 67 | files_copied: [ 68 | 'file1.txt', 69 | 'file2.jpg' 70 | ] 71 | } 72 | } 73 | ``` 74 | 75 | 76 | ## Get Involved 77 | 78 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 79 | 80 | Review and contribute to [the code](https://github.com/ansible/docker). 81 | 82 | ## Author 83 | 84 | [Chris Houseknecht] (https://github.com/chouseknecht) 85 | 86 | [@chouseknecht](https://twitter.com/chouseknecht) 87 | -------------------------------------------------------------------------------- /docker/docker_image.md: -------------------------------------------------------------------------------- 1 | 2 | # Docker_Image Module Proposal 3 | 4 | ## Purpose and Scope 5 | 6 | The purpose is to update the existing docker_image module. The updates include expanding the module's capabilities to 7 | match the build, load, pull, push, rmi, and save docker commands and adding support for remote registries. 8 | 9 | 10 | Docker_image will manage images using docker-py to communicate with either a local or remote API. It will 11 | support API versions >= 1.14. The minimum supported version of docker-py has not been decided. 12 | 13 | API connection details will be handled externally in a shared utility module. 14 | 15 | ## Parameters 16 | 17 | Docker_image will support the parameters listed below. API connection parameters will be part of a shared utility 18 | module as mentioned above. 19 | 20 | ``` 21 | archive_path: 22 | description: 23 | - Save image to the provided path. Use with state present to always save the image to a tar archive. If 24 | intermediate directories in the path do not exist, they will be created. If a matching 25 | archive already exists, it will be overwritten. 26 | default: null 27 | 28 | config_path: 29 | description: 30 | - Path to a custom docker config file. Docker-py defaults to using ~/.docker/config.json. 31 | default: null 32 | 33 | container_limits: 34 | description: 35 | - A dictionary of limits applied to each container created by the build process. 36 | Valid keys include: memory, memswap, cpushares, cpusetcpus. 37 | default: null 38 | 39 | dockerfile: 40 | description: 41 | - Name of dockerfile to use when building an image. 42 | default: Dockerfile 43 | 44 | force: 45 | description: 46 | - Use with absent state to un-tag and remove all images matching the specified name. Use with states present and tagged 47 | to ignore idempotents and take action even when an image already exists. If archive_path is specified, the force option 48 | will cause an existing archive to be overwritten. 49 | default: false 50 | 51 | http_timeout: 52 | description: 53 | - Timeout for HTTP requests during the image build operation. Provide a positive integer value for the number of 54 | seconds. 55 | default: null 56 | 57 | load_path: 58 | description: 59 | - Use with state present to load a previously saved image. Provide the full path to the image archive file. 60 | default: null 61 | 62 | name: 63 | description: 64 | - Image name. Name format will be one of: name, repository/name, registry_server:port/name. 65 | When pushing or pulling an image the name can optionally include the tag by appending ':tag_name'. 66 | required: true 67 | 68 | nocache: 69 | description: 70 | - Do not use cache when building an image. 71 | deafult: false 72 | 73 | path: 74 | description: 75 | - File path or URL to a context from which to build an image. 76 | default: null 77 | 78 | push: 79 | description: 80 | - Use with state present to always push an image to the registry. The image name must contain a repository 81 | path and optionally a registry. For example: registry.ansible.com/user_a/repository 82 | default: false 83 | 84 | pull: 85 | description: 86 | - When building an image downloads any updates to the FROM image in Dockerfiles. 87 | default: true 88 | 89 | repository: 90 | description: 91 | - Use with state tagged to set the repository for the tag. 92 | default: null 93 | 94 | rm: 95 | description: 96 | - Remove intermediate containers after build. 97 | default: true 98 | 99 | state: 100 | description: 101 | - "absent" - if image exists, unconditionally remove it. Use the force option to un-tag and remove all images 102 | matching the provided name. 103 | - "present" - check if an image is present using the provided name and tag. If the image is not present or the 104 | force option is used, the image will either be pulled, built or loaded. To build the image, provide a path 105 | to the context and Dockerfile. To load an image, use load_path to provide a path to an archive file. If no 106 | path or load_path is provided, the image will be pulled. 107 | - "tagged" - tag an image into a repository. Use the force option to replace an existing image. 108 | default: present 109 | choices: 110 | - absent 111 | - present 112 | - tagged 113 | 114 | tag: 115 | description: 116 | - Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to 117 | 'latest' when pulling an image. Required when tagging. 118 | default: latest 119 | 120 | ``` 121 | 122 | 123 | ## Examples 124 | 125 | ``` 126 | - name: build image 127 | docker_image: 128 | path: "/path/to/build/dir" 129 | name: "my_app" 130 | tags: 131 | - v1.0 132 | - mybuild 133 | 134 | - name: force pull an image and all tags 135 | docker_image: 136 | name: "my/app" 137 | force: yes 138 | tags: all 139 | 140 | - name: untag and remove image 141 | docker_image: 142 | name: "my/app" 143 | state: absent 144 | force: yes 145 | 146 | - name: push an image to Docker Hub with all tags 147 | docker_image: 148 | name: my_image 149 | push: yes 150 | tags: all 151 | 152 | - name: pull image from a private registry 153 | docker_image: 154 | name: centos 155 | registry: https://private_registry:8080 156 | 157 | ``` 158 | 159 | 160 | ## Returns 161 | 162 | ``` 163 | { 164 | changed: True 165 | check_mode: False 166 | failed: False 167 | action: [ a list of performed actions ] 168 | results: { 169 | < image inspection output > 170 | } 171 | } 172 | ``` 173 | 174 | ## Get Involved 175 | 176 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 177 | 178 | Review and contribute to [the code](https://github.com/ansible/docker). 179 | 180 | ## Author 181 | 182 | [Chris Houseknecht] (https://github.com/chouseknecht) 183 | 184 | [@chouseknecht](https://twitter.com/chouseknecht) 185 | -------------------------------------------------------------------------------- /docker/docker_image_facts.md: -------------------------------------------------------------------------------- 1 | # Docker_Image_Facts Module Proposal 2 | 3 | ## Purpose and Scope 4 | 5 | The purpose of docker_image_facts is to inspect docker images. 6 | 7 | Docker_image_facts will use docker-py to communicate with either a local or remote API. It will support API 8 | versions >= 1.14. The minimum supported version of docker-py has not been decided. 9 | 10 | API connection details will be handled externally in a shared utility module similar 11 | to how other cloud modules operate. 12 | 13 | ## Parameters 14 | 15 | Docker_image_facts will support the parameters listed below. API connection parameters will be part of a shared 16 | utility module as mentioned above. 17 | 18 | ``` 19 | name: 20 | description: 21 | - An image name or list of image names. The image name can include a tag using the format C(name:tag). 22 | default: null 23 | ``` 24 | 25 | ## Examples 26 | 27 | ``` 28 | - name: Inspect all images 29 | docker_image_facts 30 | register: image_facts 31 | 32 | - name: Inspect a single image 33 | docker_image_facts: 34 | name: myimage:v1 35 | register: myimage_v1_facts 36 | ``` 37 | 38 | ## Returns 39 | 40 | ``` 41 | { 42 | changed: False 43 | failed: False 44 | result: [ < inspection output > ] 45 | } 46 | ``` 47 | 48 | ## Get Involved 49 | 50 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 51 | 52 | Review and contribute to [the code](https://github.com/ansible/docker). 53 | 54 | ## Author 55 | 56 | [Chris Houseknecht] (https://github.com/chouseknecht) 57 | 58 | [@chouseknecht](https://twitter.com/chouseknecht) 59 | -------------------------------------------------------------------------------- /docker/docker_network.md: -------------------------------------------------------------------------------- 1 | # Docker_Network Module Proposal 2 | 3 | ## Purpose and Scope: 4 | 5 | The purpose of Docker_network is to create networks, connect containers to networks, disconnect containers from 6 | networks, and delete networks. 7 | 8 | Docker_network will use docker-py to communicate with either a local or remote API. It will support API 9 | versions >= 1.14. The minimum supported version of docker-py has not been decided. 10 | 11 | API connection details will be handled externally in a shared utility module similar to 12 | how other cloud modules operate. 13 | 14 | ## Parameters: 15 | 16 | Docker_network will accept the parameters listed below. Parameters related to connecting to the API will be handled in 17 | a shared utility module, as mentioned above. 18 | 19 | ``` 20 | connected: 21 | description: 22 | - List of container names or container IDs to connect to a network. 23 | default: null 24 | 25 | driver: 26 | description: 27 | - Specify the type of network. Docker provides bridge and overlay drivers, but 3rd party drivers can also be used. 28 | default: bridge 29 | 30 | driver_options: 31 | description: 32 | - Dictionary of network settings. Consult docker docs for valid options and values. 33 | default: null 34 | 35 | force: 36 | description: 37 | - With state 'absent' forces disconnecting all containers from the network prior to deleting the network. With 38 | state 'present' will disconnect all containers, delete the network and re-create the network. 39 | default: false 40 | 41 | incremental: 42 | description: 43 | - By default the connected list is canonical, meaning containers not on the list are removed from the network. 44 | Use incremental to leave existing containers connected. 45 | default: false 46 | 47 | ipam_driver: 48 | description: 49 | - Specifiy an IPAM driver. 50 | default: null 51 | 52 | ipam_options: 53 | description: 54 | - Dictionary of IPAM options. 55 | default: null 56 | 57 | network_name: 58 | description: 59 | - Name of the network to operate on. 60 | default: null 61 | required: true 62 | 63 | state: 64 | description: 65 | - "absent" deletes the network. If a network has connected containers, it cannot be deleted. Use the force option 66 | to disconnect all containers and delete the network. 67 | - "present" creates the network, if it does not already exist with the specified parameters, and connects the list 68 | of containers provided via the connected parameter. Containers not on the list will be disconnected. An empty 69 | list will leave no containers connected to the network. Use the incremental option to leave existing containers 70 | connected. Use the force options to force re-creation of the network. 71 | default: present 72 | choices: 73 | - absent 74 | - present 75 | ``` 76 | 77 | 78 | ## Examples: 79 | 80 | ``` 81 | - name: Create a network 82 | docker_network: 83 | name: network_one 84 | 85 | - name: Remove all but selected list of containers 86 | docker_network: 87 | name: network_one 88 | connected: 89 | - containera 90 | - containerb 91 | - containerc 92 | 93 | - name: Remove a single container 94 | docker_network: 95 | name: network_one 96 | connected: "{{ fulllist|difference(['containera']) }}" 97 | 98 | - name: Add a container to a network, leaving existing containers connected 99 | docker_network: 100 | name: network_one 101 | connected: 102 | - containerc 103 | incremental: yes 104 | 105 | - name: Create a network with options (Not sure if 'ip_range' is correct key name) 106 | docker_network 107 | name: network_two 108 | options: 109 | subnet: '172.3.26.0/16' 110 | gateway: 172.3.26.1 111 | ip_range: '192.168.1.0/24' 112 | 113 | - name: Delete a network, disconnecting all containers 114 | docker_network: 115 | name: network_one 116 | state: absent 117 | force: yes 118 | ``` 119 | 120 | ## Returns: 121 | 122 | ``` 123 | { 124 | changed: True, 125 | check_mode: False, 126 | failed: False 127 | action: [ list of performed actions ], 128 | results: { 129 | < network inspection output > 130 | } 131 | } 132 | ``` 133 | 134 | 135 | ## Get Involved 136 | 137 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 138 | 139 | Review and contribute to [the code](https://github.com/ansible/docker). 140 | 141 | ## Author 142 | 143 | [Chris Houseknecht] (https://github.com/chouseknecht) 144 | 145 | [@chouseknecht](https://twitter.com/chouseknecht) 146 | -------------------------------------------------------------------------------- /docker/docker_network_facts.md: -------------------------------------------------------------------------------- 1 | # Docker_Network_Facts Module Proposal 2 | 3 | ## Purpose and Scope 4 | 5 | Docker_network_facts will inspect networks. 6 | 7 | Docker_network_facs will use docker-py to communicate with either a local or remote API. It will support API 8 | versions >= 1.14. The minimum supported version of docker-py has not been decided. 9 | 10 | API connection details will be handled externally in a shared utility module similar 11 | to how other cloud modules operate. 12 | 13 | ## Parameters 14 | 15 | Docker_network_facts will accept the parameters listed below. API connection parameters will be part of a shared 16 | utility module as mentioned above. 17 | 18 | ``` 19 | name: 20 | description: 21 | - Network name or list of network names. 22 | default: null 23 | 24 | ``` 25 | 26 | 27 | ## Examples 28 | 29 | ``` 30 | - name: Inspect all networks 31 | docker_network_facts 32 | register: network_facts 33 | 34 | - name: Inspect a specific network and format the output 35 | docker_network_facts 36 | name: web_app 37 | register: web_app_facts 38 | ``` 39 | 40 | # Returns 41 | 42 | ``` 43 | { 44 | changed: False 45 | failed: False 46 | results: [ < inspection output > ] 47 | } 48 | ``` 49 | 50 | 51 | ## Get Involved 52 | 53 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 54 | 55 | Review and contribute to [the code](https://github.com/ansible/docker). 56 | 57 | ## Author 58 | 59 | [Chris Houseknecht] (https://github.com/chouseknecht) 60 | 61 | [@chouseknecht](https://twitter.com/chouseknecht) 62 | -------------------------------------------------------------------------------- /docker/docker_volume.md: -------------------------------------------------------------------------------- 1 | # Docker_Volume Modules Proposal 2 | 3 | ## Purpose and Scope 4 | 5 | The purpose of docker_volume is to manage volumes. 6 | 7 | Docker_volume will use docker-py to communicate with either a local or remote API. It will support API 8 | versions >= 1.14. The minimum supported version of docker-py has not been decided. 9 | 10 | API connection details will be handled externally in a shared utility module similar to how other cloud modules operate. 11 | 12 | ## Parameters 13 | 14 | Docker_volume accepts the parameters listed below. Parameters for connecting to the API are not listed here, as they 15 | will be part of the shared module mentioned above. 16 | 17 | ``` 18 | driver: 19 | description: 20 | - Volume driver. 21 | default: local 22 | 23 | force: 24 | description: 25 | - Use with state 'present' to force removal and re-creation of an existing volume. This will not remove and 26 | re-create the volume if it is already in use. 27 | 28 | name: 29 | description: 30 | - Name of the volume. 31 | required: true 32 | default: null 33 | 34 | options: 35 | description: 36 | - Dictionary of driver specific options. The local driver does not currently support 37 | any options. 38 | default: null 39 | 40 | state: 41 | description: 42 | - "absent" removes a volume. A volume cannot be removed if it is in use. 43 | - "present" create a volume with the specified name, if the volume does not already exist. Use the force 44 | option to remove and re-create a volume. Even with the force option a volume cannot be removed and re-created if 45 | it is in use. 46 | default: present 47 | choices: 48 | - absent 49 | - present 50 | ``` 51 | 52 | ## Examples 53 | 54 | ``` 55 | - name: Create a volume 56 | docker_volume: 57 | name: data 58 | 59 | - name: Remove a volume 60 | docker_volume: 61 | name: data 62 | state: absent 63 | 64 | - name: Re-create an existing volume 65 | docker_volume: 66 | name: data 67 | state: present 68 | force: yes 69 | ``` 70 | 71 | ## Returns 72 | 73 | ``` 74 | { 75 | changed: true, 76 | failed: false, 77 | action: [ list of actions taken ], 78 | results: { 79 | < volume inspection ouptut > 80 | } 81 | } 82 | ``` 83 | 84 | 85 | ## Get Involved 86 | 87 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 88 | 89 | Review and contribute to [the code](https://github.com/ansible/docker). 90 | 91 | ## Author 92 | 93 | [Chris Houseknecht] (https://github.com/chouseknecht) 94 | 95 | [@chouseknecht](https://twitter.com/chouseknecht) 96 | 97 | -------------------------------------------------------------------------------- /docker/docker_volume_facts.md: -------------------------------------------------------------------------------- 1 | # Docker_Volume_Facts Module Proposal 2 | 3 | ## Purpose and Scope 4 | 5 | Docker_volume_facts will inspect volumes. 6 | 7 | Docker_volume_facts will use docker-py to communicate with either a local or remote API. It will support API 8 | versions >= 1.14. The minimum supported version of docker-py has not been decided. 9 | 10 | API connection details will be handled externally in a shared utility module similar to how other cloud modules operate. 11 | 12 | ## Parameters 13 | 14 | Docker_volume_facts will accept the parameters listed below. API connection parameters will be part of a shared 15 | utility module as mentioned above. 16 | 17 | 18 | ``` 19 | name: 20 | description: 21 | - Volume name or list of volume names. 22 | default: null 23 | ``` 24 | 25 | 26 | ## Examples 27 | 28 | ``` 29 | - name: Inspect all volumes 30 | docker_volume_facts 31 | register: volume_facts 32 | 33 | - name: Inspect a specific volume 34 | docker_volume_facts: 35 | name: data 36 | register: data_vol_facts 37 | ``` 38 | 39 | # Returns 40 | 41 | ``` 42 | { 43 | changed: False 44 | failed: False 45 | results: [ < output from volume inspection > ] 46 | } 47 | ``` 48 | 49 | ## Get Involved 50 | 51 | Share your thoughts and ideas in [the open issue](https://github.com/ansible/proposals/issues/1). 52 | 53 | Review and contribute to [the code](https://github.com/ansible/docker). 54 | 55 | ## Author 56 | 57 | [Chris Houseknecht] (https://github.com/chouseknecht) 58 | 59 | [@chouseknecht](https://twitter.com/chouseknecht) 60 | -------------------------------------------------------------------------------- /proposals_process_proposal.md: -------------------------------------------------------------------------------- 1 | # Proposal: Proposals - have a process and documentation 2 | 3 | *Author*: Robyn Bergeron <@robynbergeron> 4 | 5 | *Date*: 04/03/2016 6 | 7 | - Status: New 8 | - Proposal type: community development process 9 | - Targeted Release: Forever, until we improve it more at a later date. 10 | - PR for Comments: https://github.com/ansible/ansible/pull/14802# (THIS IS OLD, file has moved) 11 | - Issue for comments: https://github.com/ansible/proposals/issues/5 12 | - Estimated time to implement: 2 weeks at most 13 | 14 | Comments on this proposal prior to acceptance are accepted in the comments section of the pull request linked above. 15 | 16 | ## Motivation 17 | Define light process for how proposals are created and accepted, and document the process permanently in community.html somewhere. 18 | 19 | The following suggested process was created with the following ideas in mind: 20 | - Transparency: notifications, decisions made in public meetings, etc. helps people to know what is going on. 21 | - Avoid proliferation of multiple comments in multiple places; keep everything in the PR. 22 | - Action is being taken: Knowing when and where decisions are made, and knowing who is the final authority, gives people the sense that things are moving. 23 | - Ensure that new features or enhancements are added to the roadmap and release notes. 24 | 25 | ### Problems 26 | Proposals are confusing. Should I write one? Where do I put it? Why can’t I find any documentation about this? Who approves things? This is why we should have a light and unbureaucratic process. 27 | 28 | ## Solution proposal 29 | This proposal has multiple parts: 30 | - Proposed process for submitting / accepting proposals 31 | - Suggested proposal template 32 | 33 | Once the process and template are approved, a PR will be submitted for documenting the process permanently in documentation, as well as a PR to ansible/docs/proposals for the proposal template. 34 | 35 | ### Proposed Process 36 | 1: PROPOSAL CREATION 37 | - Person making the proposal creates the proposal document in ansible/proposals via PR, following the proposal template/ 38 | - Person making the proposal creates an issue in ansible/proposals for that proposal. 39 | - Author of proposal PR updates the proposal with link to the created issue #. 40 | - Notify the community that this proposal exists. 41 | - Author notifies ansible-devel mailing list for transparency, providing link to issue. 42 | - Author includes commentary indicating that comments should *not* be in response to this email, but rather, community members should add comments or feedback in the issue. 43 | - PRs may be made to the proposal, and can merged or not at submitter's discretion, and should be discussed/linked in the issue. 44 | 45 | 2: KEEP THE PROPOSAL MOVING TOWARDS A DECISION. 46 | - Create tags in the ansible/proposals repo to indicate progress of the various proposal issues; ie: Discussion, Ready for meeting, Approved. (Can be used in conjunction with a board on waffle.io to show this, kanban style.) 47 | - Proposals use public meetings as a mechanism to keep them moving. 48 | - All proposals are decided on in a public meeting by a combination of folks with commit access to Ansible and any interested parties / users, as well as the author of the proposal. Time for approvals will be a portion of the overall schedule; proposals will be reviewed in the order received and may occasionally be deferred to the next meeting. If we are overwhelmed, a separate meeting may be scheduled. 49 | 50 | (Note: ample feedback in the comments of the proposal issue should allow for folks to come to broad consensus in one way or another in the meeting rather rapidly, generally without an actual counted vote. However, the decision should be made *in the meeting*, so as to avoid any questions around whether or not the approval of one Ansible maintain / committer reflects the opinions or decision of everyone.) 51 | 52 | - *New* proposals are explicitly added to the public IRC meeting agenda for each week by the meeting organizer for for acknowledgement of ongoing discussion and existence, and/or easy approval/rejection. (Either via a separate issue somewhere tracking any meeting items, or by adding a “meeting” label to the PR.) 53 | - Existing new, not-yet-approved proposals are reviewed weekly by meeting organizer to check for slow-moving/stalled proposals, or for flags from the proposal owner indicating that they'd like to have it addressed in the weeks meeting 54 | 55 | 3: PROPOSAL APPROVED 56 | - Amendments needed to the proposal after IRC discussion should be made immediately. 57 | - The proposal status should be changed to Approved / In Progress in the document. 58 | - The proposal should be moved from /ansible/proposals to a roadmap folder (or similar). 59 | - The proposal issue comments should be updated with a note by the meeting organizer that the proposal has been accepted, and further commentary should be in the PRs implementing the code itself. 60 | - Proposals can also be PENDING or NEEDS INFO (waiting on something), or DECLINED. 61 | 62 | 4: CODE IN PROGRESS 63 | - Approved proposals should be periodically checked for progress, especially if tied to a release and/or is noted as release blocking. 64 | - PRs implementing the proposal are recommended to link to the original proposal PR or document for context. 65 | 5: CODE COMPLETE 66 | - Proposal document, which should be in docs/roadmap, should have their status updated to COMPLETE. 67 | - The release notes file for the targeted release should be updated with a small note regarding the feature or enhancement; completed proposals for community processes should have a follow-up mail sent to the mailing list providing information and links to the new process. 68 | - Hooray! Buy your friend a tasty beverage of their choosing. 69 | 70 | ### Suggested Proposal Template Outline 71 | Following the .md convention, a proposal template should go in the docs/proposals repository. This is a suggested outline; the template will provide more guidance / context and will be submitted as a PR upon approval of this proposal. 72 | 73 | Please note that, in line with the above guidance that some processes will require fine-tuning over time, that the suggested template outline below, as well as the final submitted template to the docs/proposals repo has wiggle room in terms of description, and that what makes sense may vary from one proposal to another. The expectation is that people will simply do what seems right, and over time we’ll figure out what works best — but in the meantime, guidance is nice. 74 | 75 | #### TEMPLATE OUTLINE 76 | - Proposal Title 77 | - Author (w/github ID linked) 78 | - Date: 79 | 80 | - Status: New, Approved, Pending, Complete 81 | - Proposal type: Feature / enhancement / community development process 82 | - Targeted Release: 83 | - PR for comments: 84 | - Estimated time to implement: 85 | 86 | Comments on this proposal prior to acceptance are accepted in the comments of the PR linked above. 87 | 88 | - Motivation / Problems solved: 89 | - Proposed Solution: (what you’re doing, and why; keeping this loose for now.) 90 | 91 | Other Suggested things to include: 92 | - Dependencies / requirements: 93 | - Testing: 94 | - Documentation: 95 | 96 | ## Dependencies / requirements 97 | 98 | - Approval of this proposed process is needed to create the actual documentation of the process. 99 | - Weekly, public IRC meetings (which should probably be documented Wrt time / day of week / etc. in the contributor documentation) of the Ansible development community. 100 | - Creation of appropriate labels in GitHub (or defining some other mechanism to gather items for a weekly meeting agenda, such as a separate issue in GitHub that links to the PRs.) 101 | - Coming to an agreement regarding “what qualifies as a feature or enhancement that requires a proposal, vs. just submitting a PR with code.” It could simply be that if the change is large or very complicated, our recommendation is always to file a proposal to ensure (a) transparency (b) that a contributor doesn’t waste their time on something that ultimately can’t be merged at this time. 102 | - Nice to have: Any new proposal PR landing in ansible/proposals is automatically merged and an email automatically notifies the mailing list of the existence and location of the proposal & related issue # for comments. 103 | 104 | ## Testing 105 | 106 | Testing of this proposal will literally be via submitting this proposal through the proposed proposal process. If it fails miserably, we’ll know it needs fine-tuning or needs to go in the garbage can. 107 | 108 | ## Documentation: 109 | 110 | - Documentation of the process, including “what is a feature or enhancement vs. just a regular PR,” along with the steps shown above, will be added to the Ansible documentation in .rst format via PR. The documentation should also provide guidance on the standard wording of the email notifying ansible-devel list that the proposal exists and is ready for review in the issue comments. 111 | - A proposal template should also be created in the ansible/proposals repo directory. 112 | -------------------------------------------------------------------------------- /re-run-handlers.md: -------------------------------------------------------------------------------- 1 | # Proposal: Re-run handlers cli option 2 | 3 | *Author*: René Moser <@resmo> 4 | 5 | *Date*: 07/03/2016 6 | 7 | - Status: New 8 | 9 | ## Motivation 10 | 11 | The most annoying thing users face using ansible in production is running handlers manually after a task failed after a notified handler. 12 | 13 | ### Problems 14 | 15 | Handler notifications get lost after a task failed and there is no help from ansible to catch up the notified handlers in a next ansible playbook run. 16 | 17 | ~~~yaml 18 | - hosts: localhost 19 | gather_facts: no 20 | tasks: 21 | - name: simple task 22 | shell: echo foo 23 | notify: get msg out 24 | 25 | - name: this tasks fails 26 | fail: msg="something went wrong" 27 | 28 | handlers: 29 | - name: get msg out 30 | shell: echo handler run 31 | ~~~ 32 | 33 | Result: 34 | 35 | ~~~ 36 | $ ansible-playbook test.yml 37 | 38 | PLAY *************************************************************************** 39 | 40 | TASK [simple task] ************************************************************* 41 | changed: [localhost] 42 | 43 | TASK [this tasks fails] ******************************************************** 44 | fatal: [localhost]: FAILED! => {"changed": false, "failed": true, "msg": "something went wrong"} 45 | 46 | NO MORE HOSTS LEFT ************************************************************* 47 | 48 | RUNNING HANDLER [get msg out] ************************************************** 49 | to retry, use: --limit @test.retry 50 | 51 | PLAY RECAP ********************************************************************* 52 | localhost : ok=1 changed=1 unreachable=0 failed=1 53 | ~~~ 54 | 55 | ## Solution proposal 56 | 57 | Similar to retry, ansible should provide a way to manully invoke a list of handlers additionaly to the notified handlers in the plays: 58 | 59 | ~~~ 60 | $ ansible-playbook test.yml --notify-handlers ,, 61 | $ ansible-playbook test.yml --notify-handlers @test.handlers 62 | ~~~ 63 | 64 | Example: 65 | 66 | ~~~ 67 | $ ansible-playbook test.yml --notify-handlers "get msg out" 68 | ~~~ 69 | 70 | The stdout of a failed play should provide an example how to run notified handlers in the next run: 71 | 72 | ~~~ 73 | ... 74 | RUNNING HANDLER [get msg out] ************************************************** 75 | to retry, use: --limit @test.retry --notify-handlers @test.handlers 76 | ~~~ 77 | 78 | --------------------------------------------------------------------------------