proposals were moved to ansible/proposals

10 years ago · 0c92ec5e8f
parent 04610106a3
commit 0c92ec5e8f
13 changed files with 0 additions and 1784 deletions
--- a/docs/proposals/auto-install-roles.md
+++ b/docs/proposals/auto-install-roles.md
@ -1,150 +0,0 @@
 # Auto Install Ansible roles
 *Author*: Will Thames <@willthames>
 *Date*: 19/02/2016
 ## Motivation
 To use the latest (or even a specific) version of a playbook with the
 appropriate roles, the following steps are typically required:
 ```
 git pull upstream branch
 ansible-galaxy install -r path/to/rolesfile.yml -p path/to/rolesdir -f
 ansible-playbook run-the-playbook.yml
 ```
 ### Problems
 - 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.
 - Ansible-galaxy does ot sufficiently handle versioning. 
 - There is not a consistent format for specifying a role in a playbook or a dependent role in meta/main.yml.
 ## Approaches
 ### Approach 1: Specify rolesfile and rolesdir in playbook
 Provide new `rolesdir` and `rolesfile` keywords:
 ```
 - hosts: application-env
  become: True
  rolesfile: path/to/rolesfile.yml
  rolesdir: path/to/rolesdir
  roles:
  - roleA
  - { role: roleB, tags: role_roleB }
 ```
 Running ansible-playbook against such a playbook would cause the roles listed in
 `rolesfile` to be installed in `rolesdir`.
 Add new configuration to allow default rolesfile, default rolesdir and
 whether or not to auto update roles (defaulting to False)
 #### Advantages
 - Existing mechanism for roles management is maintained
 - Playbooks are not polluted with roles 'meta' information (version, source)
 #### Disadvantage
 - Adds two new keywords
 - Adds three new configuration variables for defaults
 ### Approach 2: Allow rolesfile inclusion
 Allow the `roles` section to include a roles file:
 ```
 - hosts: application-env
  become: True
  roles:
  - include: path/to/rolesfile.yml
 ```
 Running this playbook would cause the roles to be updated from the included
 roles file.
 This would also be functionally equivalent to specifying the roles file
 content within the playbook:
 ```
 - hosts: application-env
  become: True
  roles:
  - src: https://git.example.com/roleA.git
    scm: git
    version: 0.1
  - src: https://git.example.com/roleB.git
    scm: git
    version: 0.3
    tags: role_roleB
 ```
 #### Advantages
 - The existing rolesfile mechanism is maintained
 - Uses familiar inclusion mechanism
 #### Disadvantage
 - Separate playbooks would need separate rolesfiles. For example, a provision
  playbook and upgrade playbook would likely have some overlap - currently
  you can use the same rolesfile with ansible-galaxy so that the same
  roles are available but only a subset of roles is used by the smaller
  playbook.
 - The roles file would need to be able to include playbook features such
  as role tagging.
 - New configuration defaults would likely still be required (and possibly
  an override keyword for rolesdir and role auto update)
 ### Approach 3:  
 *Author*: chouseknecht<@chouseknecht>
 *Date*: 24/02/2016
 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 notable texceptions: 1) it elmintates maintaing 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.
 Here's the approach:
 - 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.
 - Ansible-galaxy installs or preloads roles also by examining a playbook.
 - Deprecate support for requirements.yaml (the two points above make it unnecessary).
 - Make ansible-playbook auto-downloading of roles configurable in ansible.cfg. In certain circumstance it may be desirable to disable auto-download.
 - Provide one format for specifying a role whether in a playbook or in meta/main.yml. Suggested format: 
    ```
    {
        'scm': 'git',
        'src': 'http://git.example.com/repos/repo.git',
        'version': 'v1.0',
        'name': 'repo’
    }
    ```
 - 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.
 - Refactor the install process to encompass the following :
    - 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.
    - Provide a --force option that overrides idempotency.
    - Install roles via tree-ish references, not just tags or commits (PR exists for this).
    - Support a whitelist of role sources. Galaxy should not be automatically assumed to be part of the whitelist.
    - Continue to be recursive, allowing roles to have dependencies specified in meta/main.yml.
    - Continue to install roles in the roles_path.
    - Use a symlink approach to managing role versions in the roles_path. Example:
        ```
        roles/
           briancoca.oracle_java7.v1.0
           briancoca.oracle_java7.v2.2
           briancoca.oracle_java7.qs3ih6x
           briancoca.oracle_java7 =>  briancoca.oracle_java7.qs3ih6x
        ```
 ## Conclusion
 Feedback is requested to improve any of the above approaches, or provide further approaches to solve this problem.
--- a/docs/proposals/docker/docker_container_module.md
+++ b/docs/proposals/docker/docker_container_module.md
@ -1,487 +0,0 @@
 # Docker_Container Module Proposal
 ## Purpose and Scope:
 The purpose of docker_container is to manage the lifecycle of a container. The module will provide a mechanism for
 moving the container between absent, present, stopped and started states. It will focus purely on managing container
 state. The intention of the narrow focus is to make understanding and using the module clear and keep maintenance
 and testing as easy as possible.
 Docker_container will manage a container using docker-py to communicate with either a local or remote API. It will
 support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar to
 how other cloud modules operate.
 The container world is moving rapidly, so the goal is to create a suite of docker modules that keep pace, with docker_container
 leading the way. If this project is successful, it will naturally deprecate the existing docker module.
 ## Parameters:
 Docker_container will accept the parameters listed below. An attempt has been made to represent all the options available to
 docker's create, kill, pause, run, rm, start, stop and update commands.
 Parameters for connecting to the API are not listed here. They are included in the common utility module mentioned above.
 ```
 blkio_weight:
  description:
    - Block IO (relative weight), between 10 and 1000.
  default: null
 capabilities:
  description:
    - List of capabilities to add to the container.
  default: null
 command:
  description:
    - Command or list of commands to execute in the container when it starts.
  default: null
 cpu_period:
  description:
    - Limit CPU CFS (Completely Fair Scheduler) period 
  default: 0
 cpu_quota:
  description:
    - Limit CPU CFS (Completely Fair Scheduler) quota 
  default: 0
 cpuset_cpus:
  description:
    - CPUs in which to allow execution C(1,3) or C(1-3).
  default: null
 cpuset_mems:
  description:
    - Memory nodes (MEMs) in which to allow execution C(0-3) or C(0,1)
  default: null
 cpu_shares:
  description:
    - CPU shares (relative weight).
  default: null 
 detach:
  description:
    - Enable detached mode to leave the container running in background. 
      If disabled, fail unless the process exits cleanly.
  default: true
 devices:
  description:
    - List of host device bindings to add to the container. Each binding is a mapping expressed
      in the format: <path_on_host>:<path_in_container>:<cgroup_permissions> 
  default: null
 dns_servers:
  description:
    - List of custom DNS servers.
  default: null
 dns_search_domains:
  description:
    - List of custom DNS search domains.
  default: null
 env:
  description:
    - Dictionary of key,value pairs.
  default: null
 entrypoint:
  description:
    - String or list of commands that overwrite the default ENTRYPOINT of the image.
  default: null
 etc_hosts:
  description:
    - Dict of host-to-IP mappings, where each host name is key in the dictionary. Hostname will be added to the 
      container's /etc/hosts file.
  default: null
 exposed_ports:
  description:
    - List of additional container ports to expose for port mappings or links.
      If the port is already exposed using EXPOSE in a Dockerfile, it does not
      need to be exposed again.
  default: null
  aliases:
    - exposed
 force_kill:
  description:
    - Use with absent, present, started and stopped states to use the kill command rather
      than the stop command.
  default: false
 groups:
  description:
    - List of additional group names and/or IDs that the container process will run as. 
  default: null
 hostname:
  description:
    - Container hostname.
  default: null
 image:
  description:
    - Container image used to create and match containers.
  required: true
 interactive:
  description:
    - Keep stdin open after a container is launched, even if not attached.
  default: false
 ipc_mode:
  description:
    - Set the IPC mode for the container. Can be one of 
      'container:<name|id>' to reuse another container's IPC namespace
      or 'host' to use the host's IPC namespace within the container.
  default: null
 keep_volumes:
  description:
    - Retain volumes associated with a removed container.
  default: false
 kill_signal:
  description:
    - Override default signal used to kill a running container.
  default null:
 kernel_memory:
  description:
    - Kernel memory limit (format: <number>[<unit>]). Number is a positive integer.
      Unit can be one of b, k, m, or g. Minimum is 4M.
  default: 0
 labels:
   description:
     - Dictionary of key value pairs.
   default: null
 links:
  description:
    - List of name aliases for linked containers in the format C(container_name:alias)
  default: null
 log_driver:
  description:
    - Specify the logging driver.
  choices:
    - json-file
    - syslog
    - journald
    - gelf
    - fluentd
    - awslogs
    - splunk
  defult: json-file
 log_options:
  description:
    - Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/ 
      for details.
  required: false
  default: null
 mac_address:
  description:
    - Container MAC address (e.g. 92:d0:c6:0a:29:33)
 default: null
 memory:
  description:
    - Memory limit (format: <number>[<unit>]). Number is a positive integer.
      Unit can be one of b, k, m, or g
  default: 0
 memory_reservation:
  description:
    - Memory soft limit (format: <number>[<unit>]). Number is a positive integer.
      Unit can be one of b, k, m, or g
  default: 0
 memory_swap:
  description:
    - Total memory limit (memory + swap, format:<number>[<unit>]).
      Number is a positive integer. Unit can be one of b, k, m, or g.
  default: 0
 memory_swappiness:
    description:
      - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
    default: 0
 name:
  description:
    - Assign a name to a new container or match an existing container.
    - When identifying an existing container name may be a name or a long or short container ID.
  required: true
 network_mode:
  description:
    - Connect the container to a network.
  choices:
    - bridge
    - container:<name|id>
    - host
    - none
  default: null
 networks:
  description:
    - Dictionary of networks to which the container will be connected. The dictionary must have a name key (the name of the network).
      Optional keys include: aliases (a list of container aliases), and links (a list of links in the format C(container_name:alias)).
  default: null
 oom_killer:
  desription:
    - Whether or not to disable OOM Killer for the container.
  default: false
 paused:
  description:
    - Use with the started state to pause running processes inside the container.
  default: false
 pid_mode:
  description:
    - Set the PID namespace mode for the container. Currenly only supports 'host'.
  default: null
 privileged:
  description:
    - Give extended privileges to the container.
  default: false
 published_ports:
  description:
    - List of ports to publish from the container to the host.
    - Use docker CLI syntax: C(8000), C(9000:8000), or C(0.0.0.0:9000:8000), where 8000 is a
      container port, 9000 is a host port, and 0.0.0.0 is a host interface.
    - Container ports must be exposed either in the Dockerfile or via the C(expose) option.
    - A value of ALL will publish all exposed container ports to random host ports, ignoring
      any other mappings.
  aliases:
    - ports
 read_only:
  description:
    - Mount the container's root file system as read-only.
  default: false
 recreate:
  description:
    - Use with present and started states to force the re-creation of an existing container.
  default: false
 restart:
  description:
    - Use with started state to force a matching container to be stopped and restarted.
  default: false
 restart_policy:
  description:
    - Container restart policy.
  choices:
    - on-failure
    - always
  default: on-failure 
 restart_retries:
   description:
     - Use with restart policy to control maximum number of restart attempts.
   default: 0 
 shm_size:
  description:
    - Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. 
      Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes).
    - Ommitting the unit defaults to bytes. If you omit the size entirely, the system uses `64m`.
  default: null
 security_opts:
  description:
    - List of security options in the form of C("label:user:User")
  default: null
 state:
  description:
    - "absent" - A container matching the specified name will be stopped and removed. Use force_kill to kill the container
       rather than stopping it. Use keep_volumes to retain volumes associated with the removed container.
    - "present" - Asserts the existence of a container matching the name and any provided configuration parameters. If no
      container matches the name, a container will be created. If a container matches the name but the provided configuration
      does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and re-created
      with the requested config. Use recreate to force the re-creation of the matching container. Use force_kill to kill the
      container rather than stopping it. Use keep_volumes to retain volumes associated with a removed container.
    - "started" - Asserts there is a running container matching the name and any provided configuration. If no container
      matches the name, a container will be created and started. If a container matching the name is found but the
      configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed
      and a new container will be created with the requested configuration and started. Use recreate to always re-create a 
      matching container, even if it is running. Use restart to force a matching container to be stopped and restarted. Use
      force_kill to kill a container rather than stopping it. Use keep_volumes to retain volumes associated with a removed
      container.
    - "stopped" - a container matching the specified name will be stopped. Use force_kill to kill a container rather than
      stopping it.
  required: false
  default: started
  choices:
    - absent
    - present
    - stopped
    - started
 stop_signal:
  description:
    - Override default signal used to stop the container.
  default: null 
 stop_timeout:
  description:
    - Number of seconds to wait for the container to stop before sending SIGKILL.
  required: false
 trust_image_content:
  description:
    - If true, skip image verification.
  default: false
 tty:
  description:
    - Allocate a psuedo-TTY.
  default: false
 ulimits:
  description:
    - List of ulimit options. A ulimit is specified as C(nofile:262144:262144)
  default: null
 user:
  description
    - Sets the username or UID used and optionally the groupname or GID for the specified command.
    - Can be [ user | user:group | uid | uid:gid | user:gid | uid:group ]
  default: null
 uts:
  description:
    - Set the UTS namespace mode for the container.
  default: null
 volumes:
  description:
    - List of volumes to mount within the container.
    - 'Use docker CLI-style syntax: C(/host:/container[:mode])'
    - You can specify a read mode for the mount with either C(ro) or C(rw).
    - SELinux hosts can additionally use C(z) or C(Z) to use a shared or 
      private label for the volume.
 default: null
 volume_driver:
  description:
    - The container's volume driver.
  default: none
 volumes_from:
  description:
    - List of container names or Ids to get volumes from. 
  default: null
 ```
 ## Examples:
 ```
 - name: Create a data container
  docker_container:
    name: mydata
    image: busybox
    volumes:
      - /data
 - name: Re-create a redis container
  docker_container:
    name: myredis
    image: redis
    command: redis-server --appendonly yes
    state: present
    recreate: yes
    expose:
      - 6379
    volumes_from:
      - mydata
 - name: Restart a container
  docker_container:
    name: myapplication
    image: someuser/appimage
    state: started 
    restart: yes
    links:
     - "myredis:aliasedredis"
    devices:
     - "/dev/sda:/dev/xvda:rwm"
    ports:
     - "8080:9000"
     - "127.0.0.1:8081:9001/udp"
    env:
        SECRET_KEY: ssssh
 - name: Container present
  docker_container:
    name: mycontainer
    state: present
    recreate: yes
    forcekill: yes
    image: someplace/image
    command: echo "I'm here!"
 - name: Start 4 load-balanced containers
  docker_container:
    name: "container{{ item }}"
    state: started
    recreate: yes
    image: someuser/anotherappimage
    command: sleep 1d
  with_sequence: count=4
 -name: remove container
  docker_container:
    name: ohno
    state: absent
 - name: Syslogging output 
  docker_container:
    name: myservice
    state: started 
    log_driver: syslog
    log_opt:
      syslog-address: tcp://my-syslog-server:514
      syslog-facility: daemon
      syslog-tag: myservice
 ```
 ## Returns:
 The JSON object returned by the module will include a *results* object providing `docker inspect` output for the affected container.
 ```
 {
    changed: True,
    failed: False,
    rc: 0
    results: {
        < the results of `docker inspect` >
    }
 }
 ```
--- a/docs/proposals/docker/docker_files_module.md
+++ b/docs/proposals/docker/docker_files_module.md
@ -1,159 +0,0 @@
 # Docker_Files Modules Proposal
 ## Purpose and Scope
 The purpose of docker_files is to provide for retrieving a file or folder from a container's file system, 
 inserting a file or folder into a container, exporting a container's entire filesystem as a tar archive, or 
 retrieving a list of changed files from a container's file system.
 Docker_files will manage a container using docker-py to communicate with either a local or remote API. It will
 support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar to
 how other cloud modules operate.
 ## Parameters
 Docker_files accepts the parameters listed below. API connection parameters will be part of a shared utility module
 as mentioned above.
 ```
 diff:
  description:
    - Provide a list of container names or IDs. For each container a list of changed files and directories found on the
      container's file system will be returned. Diff is mutually exclusive from all other options except event_type. 
      Use event_type to choose which events to include in the output.
  default: null
 export:
  description: 
    - Provide a container name or ID. The container's file system will be exported to a tar archive. Use dest
      to provide a path for the archive on the local file system. If the output file already exists, it will not be
      overwritten. Use the force option to overwrite an existing archive.
  default: null
 dest:
  description:
    - Destination path of copied files. If the destination is a container file system, precede the path with a
      container name or ID + ':'. For example, C(mycontainer:/path/to/file.txt). If the destination path does not
      exist, it will be created. If the destination path exists on a the local filesystem, it will not be overwritten.
      Use the force option to overwrite existing files on the local filesystem.
  default: null
 force: 
  description:
    - Overwrite existing files on the local filesystem. 
  default: false
 follow_link:
  description:
    - Follow symbolic links in the src path. If src is local and file is a symbolic link, the symbolic link, not the 
    target is copied by default. To copy the link target and not the link, set follow_link to true.
  default: false
 event_type:
  description:
    - Select the specific event type to list in the diff output.
  choices:
    - all
    - add
    - delete
    - change
  default: all
 src:
  description:
    - The source path of file(s) to be copied. If source files are found on the container's file system, precede the
      path with the container name or ID + ':'. For example, C(mycontainer:/path/to/files).
  default: null
 ```
 ## Examples
 ```
 - name: Copy files from the local file system to a container's file system
  docker_files:
    src: /tmp/rpm
    dest: mycontainer:/tmp
    follow_links: yes
 - name: Copy files from the container to the local filesystem and overwrite existing files
  docker_files:
    src: container1:/var/lib/data
    dest: /tmp/container1/data
    force: yes
 - name: Export container filesystem
  docker_file:
    export: container1
    dest: /tmp/conainer1.tar
    force: yes
 - name: List all differences for multiple containers.
  docker_files:
    diff:
      - mycontainer1
      - mycontainer2
 - name: Included changed files only in diff output
  docker_files:
    diff:
      - mycontainer1
    event_type: change
 ```
 ## Returns
 Returned from diff:
 ```
 {
    changed: false,
    failed: false,
    rc: 0,
    results: {
        mycontainer1: [
            { state: 'C', path: '/dev' },
            { state: 'A', path: '/dev/kmsg' },
            { state: 'C', path: '/etc' },
            { state: 'A', path: '/etc/mtab' }
        ],
        mycontainer2: [
            { state: 'C', path: '/foo' },
            { state: 'A', path: '/foo/bar.txt' }
        ]
    }
 }
 ```
 Returned when copying files:
 ```
 {
    changed: true,
    failed: false,
    rc: 0,
    results: {
        src: /tmp/rpms,
        dest: mycontainer:/tmp
        files_copied: [
            'file1.txt',
            'file2.jpg'
        ]
    }
 }
 ```
 Return when exporting container filesystem:
 ```
 {
   changed: true,
    failed: false,
    rc: 0,
    results: {
        src: container_name,
        dest: local/path/archive_name.tar
    }
 }
 ```
--- a/docs/proposals/docker/docker_image_facts_module.md
+++ b/docs/proposals/docker/docker_image_facts_module.md
@ -1,47 +0,0 @@
 # Docker_Image_Facts Module Proposal
 ## Purpose and Scope
 The purpose of docker_image_facts is to inspect docker images.
 Docker_image_facts will use docker-py to communicate with either a local or remote API. It will
 support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar
 to how other cloud modules operate.
 ## Parameters
 Docker_image_facts will support the parameters listed below. API connection parameters will be part of a shared
 utility module as mentioned above.
 ```
 name:
  description:
    - An image name or list of image names. The image name can include a tag using the format C(name:tag).
  default: null
 ```
 ## Examples
 ```
 - name: Inspect all images
  docker_image_facts
  register: image_facts
 - name: Inspect a single image
  docker_image_facts:
    name: myimage:v1
  register: myimage_v1_facts
 ```
 ## Returns
 ```
 {
   changed: False
   failed: False
   rc: 0
   result: [ < inspection output > ]
 }
 ```
--- a/docs/proposals/docker/docker_image_module.md
+++ b/docs/proposals/docker/docker_image_module.md
@ -1,207 +0,0 @@
 # Docker_Image Module Proposal
 ## Purpose and Scope
 The purpose is to update the existing docker_image module. The updates include expanding the module's capabilities to
 match the build, load, pull, push, rmi, and save docker commands and adding support for remote registries.
 Docker_image will manage images using docker-py to communicate with either a local or remote API. It will
 support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar 
 to how other cloud modules operate.
 ## Parameters
 Docker_image will support the parameters listed below. API connection parameters will be part of a shared utility 
 module as mentioned above.
 ```
 archive_path:
  description:
    - Save image to the provided path. Use with state present to always save the image to a tar archive. If
      intermediate directories in the path do not exist, they will be created. If a matching
      archive already exists, it will be overwritten.
  default: null
 config_path:
  description:
    - Path to a custom docker config file. Docker-py defaults to using ~/.docker/config.json.
 cgroup_parent:
  description:
    - Optional parent cgroup for build containers.
  default: null
 cpu_shares:
  description:
    - CPU shares for build containers. Integer value.
  default: 0
 cpuset_cpus:
  description:
    - CPUs in which to allow build container execution C(1,3) or C(1-3).
  default: null
 dockerfile:
  description:
    - Name of dockerfile to use when building an image.
  default: Dockerfile
 email:
  description:
    - The email for the registry account. Provide with username and password when credentials are not encoded
      in docker configuration file or when encoded credentials should be updated.
  default: null
  nolog: true
 force:
  description:
    - Use with absent state to un-tag and remove all images matching the specified name. Use with present state to
      force a pull or rebuild of the image.
  default: false
 load_path:
  description:
    - Use with state present to load a previously save image. Provide the full path to the image archive file.
  default: null
 memory:
  description:
    - Build container limit. Memory limit specified as a positive integer for number of bytes.
 memswap:
  description:
    - Build container limit. Total memory (memory + swap). Specify as a positive integer for number of bytes or
      -1 to disable swap.
  default: null
 name:
  description:
    - Image name or ID.
  required: true
 nocache:
  description:
    - Do not use cache when building an image.
  deafult: false
 password:
  description:
    - Password used when connecting to the registry. Provide with username and email when credentials are not encoded
      in docker configuration file or when encoded credentials should be updated.
  default: null
  nolog: true
 path:
  description:
    - Path to Dockerfile and context from which to build an image.
  default: null
 push:
  description:
    - Use with state present to always push an image to the registry.
  default: false
 registry:
  description:
    - URL of the registry. If not provided, defaults to Docker Hub.
  default: null
 rm:
  description:
    - Remove intermediate containers after build.
  default: true
 tag:
  description:
    - Image tags. When pulling or pushing, set to 'all' to include all tags.
  default: latest
 url:
  description:
    - The location of a Git repository. The repository acts as the context when building an image.
    - Mutually exclusive with path.
 username:
  description:
    - Username used when connecting to the registry. Provide with password and email when credentials are not encoded 
      in docker configuration file or when encoded credentials should be updated.
  default: null
  nolog: true
 state:
  description:
    - "absent" - if image exists, unconditionally remove it. Use the force option to un-tag and remove all images
      matching the provided name.
    - "present" - check if image is present with the provided tag. If the image is not present or the force option
      is used, the image will either be pulled from the registry, built or loaded from an archive. To build the image,
      provide a path or url to the context and Dockerfile. To load an image, use load_path to provide a path to
      an archive file. If no path, url or load_path is provided, the image will be pulled. Use the registry
      parameters to control the registry from which the image is pulled.
 required: false
 default: present
 choices:
  - absent
  - present
 http_timeout:
  description:
    - Timeout for HTTP requests during the image build operation. Provide a positive integer value for the number of
      seconds.
  default: null
 ```
 ## Examples
 ```
 - name: build image
  docker_image:
    path: "/path/to/build/dir"
    name: "my_app"
    tags:
      - v1.0
      - mybuild
 - name: force pull an image and all tags
  docker_image:
    name: "my/app"
    force: yes
    tags: all
 - name: untag and remove image
  docker_image:
    name: "my/app"
    state: absent
    force: yes
 - name: push an image to Docker Hub with all tags
  docker_image:
    name: my_image
    push: yes
    tags: all
 - name: pull image from a private registry
  docker_image:
    name: centos
    registry: https://private_registry:8080
 ```
 ## Returns
 ```
 {
   changed: True
   failed: False
   rc: 0
   action: built | pulled | loaded | removed | none
   msg: < text confirming the action that was taken >
   results: {
      < output from docker inspect for the affected image >
   }
 }
 ```
--- a/docs/proposals/docker/docker_network_facts.md
+++ b/docs/proposals/docker/docker_network_facts.md
@ -1,48 +0,0 @@
 # Docker_Network_Facts Module Proposal
 ## Purpose and Scope
 Docker_network_facts will inspect networks.
 Docker_network_facts will use docker-py to communicate with either a local or remote API. It will
 support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar
 to how other cloud modules operate.
 ## Parameters
 Docker_network_facts will accept the parameters listed below. API connection parameters will be part of a shared
 utility module as mentioned above.
 ```
 name:
  description:
    - Network name or list of network names. 
  default: null
 ```
 ## Examples
 ```
 - name: Inspect all networks
  docker_network_facts
  register: network_facts
 - name: Inspect a specific network and format the output
  docker_network_facts
    name: web_app
  register: web_app_facts
 ```
 # Returns
 ```
 {
   changed: False
   failed: False
   rc: 0
   results: [ < inspection output > ]
 }
 ```
--- a/docs/proposals/docker/docker_network_module.md
+++ b/docs/proposals/docker/docker_network_module.md
@ -1,130 +0,0 @@
 # Docker_Network Module Proposal
 ## Purpose and Scope:
 The purpose of Docker_network is to create networks, connect containers to networks, disconnect containers from 
 networks, and delete networks.
 Docker network will manage networks using docker-py to communicate with either a local or remote API. It will
 support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar to
 how other cloud modules operate.
 ## Parameters:
 Docker_network will accept the parameters listed below. Parameters related to connecting to the API will be handled in 
 a shared utility module, as mentioned above.
 ```
 connected:
  description:
    - List of container names or container IDs to connect to a network.
  default: null
 driver:
  description:
    - Specify the type of network. Docker provides bridge and overlay drivers, but 3rd party drivers can also be used.
  default: bridge
 driver_options:
  description:
    - Dictionary of network settings. Consult docker docs for valid options and values.
  default: null
 force:
  description:
    - With state 'absent' forces disconnecting all containers from the network prior to deleting the network. With
      state 'present' will disconnect all containers, delete the network and re-create the network.
  default: false
 incremental:
  description:
    - By default the connected list is canonical, meaning containers not on the list are removed from the network.
      Use incremental to leave existing containers connected.
  default: false
 ipam_driver:
  description:
    - Specifiy an IPAM driver.
  default: null 
 ipam_options:
  description:
    - Dictionary of IPAM options.  
  default: null
 network_name:
  description:
    - Name of the network to operate on.
  default: null
  required: true
 state:
  description:
    - "absent" deletes the network. If a network has connected containers, it cannot be deleted. Use the force option
      to disconnect all containers and delete the network.
    - "present" creates the network, if it does not already exist with the specified parameters, and connects the list
      of containers provided via the connected parameter. Containers not on the list will be disconnected. An empty
      list will leave no containers connected to the network. Use the incremental option to leave existing containers
      connected. Use the force options to force re-creation of the network.
  default: present
  choices:
    - absent
    - present
 ```
 ## Examples:
 ```
 - name: Create a network
  docker_network:
    name: network_one
 - name: Remove all but selected list of containers
  docker_network:
    name: network_one
    connected:
      - containera
      - containerb
      - containerc
 - name: Remove a single container
  docker_network:
    name: network_one
    connected: "{{ fulllist|difference(['containera']) }}"
 - name: Add a container to a network, leaving existing containers connected
  docker_network:
    name: network_one
    connected:
      - containerc
    incremental: yes
 - name: Create a network with options (Not sure if 'ip_range' is correct key name)
  docker_network
    name: network_two
    options:
      subnet: '172.3.26.0/16'
      gateway: 172.3.26.1
      ip_range: '192.168.1.0/24'
 - name: Delete a network, disconnecting all containers
  docker_network:
    name: network_one
    state: absent
    force: yes      
 ```
 ## Returns:
 ```
 {
    changed: True,
    failed: false
    rc: 0
    action: created | removed | none
    results: {
        < results from docker inspect for the affected network >
    }
 }
 ```
--- a/docs/proposals/docker/docker_volume_facts.md
+++ b/docs/proposals/docker/docker_volume_facts.md
@ -1,48 +0,0 @@
 # Docker_Volume_Facts Module Proposal
 ## Purpose and Scope
 Docker_volume_facts will inspect volumes.
 Docker_volume_facts will use docker-py to communicate with either a local or remote API. It will
 support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar
 to how other cloud modules operate.
 ## Parameters
 Docker_volume_facts will accept the parameters listed below. API connection parameters will be part of a shared
 utility module as mentioned above.
 ```
 name:
  description:
    - Volume name or list of volume names. 
  default: null
 ```
 ## Examples
 ```
 - name: Inspect all volumes
  docker_volume_facts
  register: volume_facts
 - name: Inspect a specific volume
  docker_volume_facts:
    name: data
  register: data_vol_facts
 ```
 # Returns
 ```
 {
   changed: False
   failed: False
   rc: 0
   results: [ < output from volume inspection  > ]
 }
 ```
--- a/docs/proposals/docker/docker_volume_module.md
+++ b/docs/proposals/docker/docker_volume_module.md
@ -1,82 +0,0 @@
 # Docker_Volume Modules Proposal
 ## Purpose and Scope
 The purpose of docker_volume is to manage volumes.
 Docker_volume will manage volumes using docker-py to communicate with either a local or remote API. It will
 support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar 
 to how other cloud modules operate.
 ## Parameters
 Docker_volume accepts the parameters listed below. Parameters for connecting to the API are not listed here, as they
 will be part of the shared module mentioned above.
 ```
 driver:
  description:
    - Volume driver.
  default: local
 force:
  description:
    - Use with state 'present' to force removal and re-creation of an existing volume. This will not remove and
      re-create the volume if it is already in use.
 name:
  description:
    - Name of the volume.
  required: true
  default: null
 options:
  description:
    - Dictionary of driver specific options. The local driver does not currently support
      any options.
  default: null
 state:
  description:
    - "absent" removes a volume. A volume cannot be removed if it is in use.
    - "present" create a volume with the specified name, if the volume does not already exist. Use the force
      option to remove and re-create a volume. Even with the force option a volume cannot be removed and re-created if
      it is in use.
  default: present
  choices:
    - absent
    - present  
 ```
 ## Examples
 ```
 - name: Create a volume
  docker_volume:
    name: data
 - name: Remove a volume
  docker_volume:
    name: data
    state: absent
 - name: Re-create an existing volume
  docker_volume:
    name: data
    state: present
    force: yes
 ```
 ## Returns
 ```
 {
    changed: true,
    failed: false,
    rc: 0,
    action: removed | created | none
    results: {
        < show the result of docker inspect of an affected volume >
    }
 }
 ```
--- a/docs/proposals/proposals_process_proposal.MD
+++ b/docs/proposals/proposals_process_proposal.MD
@ -1,110 +0,0 @@
 # Proposal: Proposals - have a process and documentation
 *Author*: Robyn Bergeron <@robynbergeron>
 *Date*: 04/03/2016
 - Status: New
 - Proposal type: community development process
 - Targeted Release: Forever, until we improve it more at a later date.
 - PR for Comments: https://github.com/ansible/ansible/pull/14802#
 - Estimated time to implement: 2 weeks at most
 Comments on this proposal prior to acceptance are accepted in the comments section of the pull request linked above.
 ## Motivation
 Define light process for how proposals are created and accepted, and document the process permanently in community.html somewhere.
 The following suggested process was created with the following ideas in mind:
 - Transparency: notifications, decisions made in public meetings, etc. helps people to know what is going on.
 - Avoid proliferation of multiple comments in multiple places; keep everything in the PR.
 - 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.
 - Ensure that new features or enhancements are added to the roadmap and release notes.
 ### Problems
 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.
 ## Solution proposal
 This proposal has multiple parts:
 - Proposed process for submitting / accepting proposals
 - Suggested proposal template
 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.
 ### Proposed Process
 1: PROPOSAL CREATION
 - Person making the proposal creates the proposal document in ansible/proposals via PR, following the proposal template/
 - Person making the proposal creates an issue in ansible/proposals for that proposal.
 - Author of proposal PR updates the proposal with link to the created issue #. 
 - Notify the community that this proposal exists.
 - Author notifies ansible-devel mailing list for transparency, providing link to issue.
 - 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.
 - PRs may be made to the proposal, and can merged or not at submitter's discretion, and should be discussed/linked in the issue. 
 2: KEEP THE PROPOSAL MOVING TOWARDS A DECISION.
 - 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.)
 - Proposals use public meetings as a mechanism to keep them moving.
 - 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.
 (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.)
 - *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.)
 - 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
 3: PROPOSAL APPROVED
 - Amendments needed to the proposal after IRC discussion should be made immediately.
 - The proposal status should be changed to Approved / In Progress in the document.
 - The proposal should be moved from /ansible/proposals to a roadmap folder (or similar).
 - 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.
 - Proposals can also be PENDING or NEEDS INFO (waiting on something), or DECLINED. 
 4: CODE IN PROGRESS
 - Approved proposals should be periodically checked for progress, especially if tied to a release and/or is noted as release blocking.
 - PRs implementing the proposal are recommended to link to the original proposal PR or document for context.
 5: CODE COMPLETE
 - Proposal document, which should be in docs/roadmap, should have their status updated to COMPLETE.
 - 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.
 - Hooray! Buy your friend a tasty beverage of their choosing.
 ### Suggested Proposal Template Outline
 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.
 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.
 #### TEMPLATE OUTLINE
 - Proposal Title
 - Author (w/github ID linked)
 - Date:
 - Status: New, Approved, Pending, Complete
 - Proposal type: Feature  / enhancement / community development process
 - Targeted Release:
 - PR for comments:
 - Estimated time to implement:
 Comments on this proposal prior to acceptance are accepted in the comments of the PR linked above.
 - Motivation / Problems solved:
 - Proposed Solution: (what you’re doing, and why; keeping this loose for now.)
 Other Suggested things to include:
 - Dependencies / requirements:
 - Testing:
 - Documentation:
 ## Dependencies / requirements
 - Approval of this proposed process is needed to create the actual documentation of the process.
 - Weekly, public IRC meetings (which should probably be documented Wrt time / day of week / etc. in the contributor documentation) of the Ansible development community.
 - 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.)
 - 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.
 - 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.
 ## Testing
 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.
 ## Documentation:
 - 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.
 - A proposal template should also be created in the ansible/proposals repo directory.
--- a/docs/proposals/publish-subscribe.md
+++ b/docs/proposals/publish-subscribe.md
@ -1,205 +0,0 @@
 # Publish / Subscribe for Handlers
 *Author*: René Moser <@resmo>
 *Date*: 07/03/2016
 ## Motivation
 In some use cases a publish/subscribe kind of event to run a handler is more convenient, e.g. restart services after replacing SSL certs.
 However, ansible does not provide a built-in way to handle it yet.
 ### Problem
 If your SSL cert changes, you usually have to reload/restart services to use the new certificate.
 However, If you have a ssl role or a generic ssl play, you usually don't want to add specific handlers to it.
 Instead it would be much more convenient to use a publish/subscribe kind of paradigm in the roles where the services are configured in.
 The way we implemented it currently:
 I use notify to set a fact where later (in different plays) we act on a fact using notify again.
 ~~~yaml
 ---
 - hosts: localhost
  gather_facts: no
  tasks:
  - name: copy an ssl cert
    shell: echo cert has been changed
    notify: publish ssl cert change
  handlers:
  - name: publish ssl cert change
    set_fact:
      ssl_cert_changed: true
 - hosts: localhost
  gather_facts: no
  tasks:
  - name: subscribe for ssl cert change
    shell: echo cert changed
    notify: service restart one
    when: ssl_cert_changed is defined and ssl_cert_changed
  handlers:
  - name: service restart one
    shell: echo service one restarted
 - hosts: localhost
  gather_facts: no
  tasks:
  - name: subscribe for ssl cert change
    shell: echo cert changed
    when: ssl_cert_changed is defined and ssl_cert_changed
    notify: service restart two
  handlers:
  - name: service restart two
    shell: echo service two restarted
 ~~~
 However, this looks like a workaround of a feature that ansible should provide in a much cleaner way.
 ## Approaches
 ### Approach 1:
 Provide new `subscribe` keyword on handlers:
 ~~~yaml
 - hosts: localhost
  gather_facts: no
  tasks:
  - name: copy an ssl cert
    shell: echo cert has been changed
 - hosts: localhost
  gather_facts: no
  handlers:
  - name: service restart one
    shell: echo service one restarted
    subscribe: copy an ssl cert
 - hosts: localhost
  gather_facts: no
  handlers:
  - name: service restart two
    shell: echo service two restarted
    subscribe: copy an ssl cert
 ~~~
 ### Approach 2:
 Provide new `subscribe` on handlers and `publish` keywords in tasks:
 ~~~yaml
 - hosts: localhost
  gather_facts: no
  tasks:
  - name: copy an ssl cert
    shell: echo cert has been changed
    publish: yes
 - hosts: localhost
  gather_facts: no
  handlers:
  - name: service restart one
    shell: echo service one restarted
    subscribe: copy an ssl cert
 - hosts: localhost
  gather_facts: no
  handlers:
  - name: service restart two
    shell: echo service two restarted
    subscribe: copy an ssl cert
 ~~~
 ### Approach 3:
 Provide new `subscribe` module:
 A subscribe module could consume the results of a task by name, optionally the value to react on could be specified (default: `changed`)
 ~~~yaml
 - hosts: localhost
  gather_facts: no
  tasks:
  - name: copy an ssl cert
    shell: echo cert has been changed
 - hosts: localhost
  gather_facts: no
  tasks:
  - subscribe:
      name: copy an ssl cert
    notify: service restart one
  handlers:
  - name: service restart one
    shell: echo service one restarted
 - hosts: localhost
  gather_facts: no
  tasks:
  - subscribe:
      name: copy an ssl cert
      react_on: changed
    notify: service restart two
  handlers:
  - name: service restart two
    shell: echo service two restarted
 ~~~
 ### Approach 4:
 Provide new `subscribe` module (same as Approach 3) and `publish` keyword:
 ~~~yaml
 - hosts: localhost
  gather_facts: no
  tasks:
  - name: copy an ssl cert
    shell: echo cert has been changed
    publish: yes
 - hosts: localhost
  gather_facts: no
  tasks:
  - subscribe:
      name: copy an ssl cert
    notify: service restart one
  handlers:
  - name: service restart one
    shell: echo service one restarted
 - hosts: localhost
  gather_facts: no
  tasks:
  - subscribe:
      name: copy an ssl cert
    notify: service restart two
  handlers:
  - name: service restart two
    shell: echo service two restarted
 ~~~
 ### Clarifications about role dependencies and publish
 When using service roles having the subscription handlers and the publish task (e.g. cert change) is defined in a depended role (SSL role) only the first service role running the "cert change" task as dependency will trigger the publish.
 In any other service role in the playbook having "SSL role" as dependency, the task won't be `changed` anymore.
 Therefore a once published "message" should not be overwritten or so called "unpublished" by running the same task in a followed role in the playbook.
 ## Conclusion
 Feedback is requested to improve any of the above approaches, or provide further approaches to solve this problem.
--- a/docs/proposals/re-run-handlers.md
+++ b/docs/proposals/re-run-handlers.md
@ -1,77 +0,0 @@
 # Proposal: Re-run handlers cli option
 *Author*: René Moser <@resmo>
 *Date*: 07/03/2016
 - Status: New
 ## Motivation
 The most annoying thing users face using ansible in production is running handlers manually after a task failed after a notified handler.
 ### Problems
 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.
 ~~~yaml
 - hosts: localhost
  gather_facts: no
  tasks:
    - name: simple task
      shell: echo foo
      notify: get msg out
    - name: this tasks fails
      fail: msg="something went wrong"
  handlers:
    - name: get msg out
      shell: echo handler run
 ~~~
 Result:
 ~~~
 $ ansible-playbook test.yml
 PLAY ***************************************************************************
 TASK [simple task] *************************************************************
 changed: [localhost]
 TASK [this tasks fails] ********************************************************
 fatal: [localhost]: FAILED! => {"changed": false, "failed": true, "msg": "something went wrong"}
 NO MORE HOSTS LEFT *************************************************************
 RUNNING HANDLER [get msg out] **************************************************
 	to retry, use: --limit @test.retry
 PLAY RECAP *********************************************************************
 localhost                  : ok=1    changed=1    unreachable=0    failed=1
 ~~~
 ## Solution proposal
 Similar to retry, ansible should provide a way to manully invoke a list of handlers additionaly to the notified handlers in the plays:
 ~~~
 $ ansible-playbook test.yml --notify-handlers <handler>,<handler>,<handler>
 $ ansible-playbook test.yml --notify-handlers @test.handlers
 ~~~
 Example:
 ~~~
 $ ansible-playbook test.yml --notify-handlers "get msg out"
 ~~~
 The stdout of a failed play should provide an example how to run notified handlers in the next run:
 ~~~
 ...
 RUNNING HANDLER [get msg out] **************************************************
 	to retry, use: --limit @test.retry --notify-handlers @test.handlers
 ~~~
--- a/docs/proposals/rename_always_run.md
+++ b/docs/proposals/rename_always_run.md
@ -1,34 +0,0 @@
 # Rename always_run to ignore_checkmode
 *Author*: René Moser <@resmo>
 *Date*: 02/03/2016
 ## Motivation
 The task argument `always_run` is misleading.
 Ansible is known to be readable by users without deep knowledge of creating playbooks, they do not understand
 what `always_run` does at the first glance.
 ### Problems
 The following looks scary if you have no idea, what `always_run` does:
 ```
 - shell: dangerous_cleanup.sh
  when: cleanup == "yes"
  always_run: yes
 ```
 You have a conditional but also a word that says `always`. This is a conflict in terms of understanding.
 ## Solution Proposal
 Deprecate `always_run` by rename it to `ignore_checkmode`:
 ```
 - shell: dangerous_cleanup.sh
  when: cleanup == "yes"
  ignore_checkmode: yes
 ```