Repository: ansible/ansible-modules-core

Issue:
docker_image doesn't accept state: build in 2.1.1.0
<!--- Verify first that your issue/request is not already reported in GitHub -->
##### ISSUE TYPE

<!--- Pick one below and delete the rest: -->
- Bug Report
##### COMPONENT NAME

<!--- Name of the plugin/module/task -->

docker_image
##### ANSIBLE VERSION

<!--- Paste verbatim output from “ansible --version” between quotes below -->

```
ansible 2.1.1.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = Default w/o overrides
```
##### CONFIGURATION

<!---
Mention any settings you have changed/added/removed in ansible.cfg
(or using the ANSIBLE_* environment variables).
-->

Default ansible.cfg.
##### OS / ENVIRONMENT

<!---
Mention the OS you are running Ansible from, and the OS you are
managing, or say “N/A” for anything that is not platform-specific.
-->

N/A
##### SUMMARY

<!--- Explain the problem briefly -->

docker_image should accept `state: build` but it doesn't.
##### STEPS TO REPRODUCE

<!---
For bugs, show exactly how to reproduce the problem.
For new features, show how the feature would be used.
-->

<!--- Paste example playbooks or commands between quotes below -->

```
$ cat test.yml

---
  - hosts: all
    tasks:
    - docker_image:
        name: "name"
        path: "/some/path"
        state: build

$ ansible-playbook -i 'localhost,' -c local test.yml
```

<!--- You can also paste gist.github.com links for larger files -->
##### EXPECTED RESULTS

<!--- What did you expect to happen when running the steps above? -->

According to http://docs.ansible.com/ansible/docker_image_module.html `state: build` should be deprecated, not removed. 

> Specifying 'build' will behave the same as 'present'.
##### ACTUAL RESULTS

<!--- What actually happened? If possible run with extra verbosity (-vvvv) -->

<!--- Paste verbatim command output between quotes below -->

```
PLAY [all] *********************************************************************

TASK [setup] *******************************************************************
ok: [localhost]

TASK [docker_image] ************************************************************
fatal: [localhost]: FAILED! => {"changed": false, "failed": true, "msg": "value of state must be one of: absent,present, got: build"}

NO MORE HOSTS LEFT *************************************************************
 [WARNING]: Could not create retry file 'test.retry'.         [Errno 2] No such file or directory: ''


PLAY RECAP *********************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=1   
```



Discussion:
<!-- @alkedr: Thanks for filing this bug report! -->

@ansible ping, this issue is waiting for your response.
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)

<!--- boilerplate: issue_bug_new --->

I can confirm that for some reason _build_ is missing from the list of state choices. Not sure why. However, it is marked as deprecated in the doc strings. Maybe it's time we ripped the bandaid off. 

FWIW, your playbook will work if you remove _state_ altogether or set _state_ to _present_. 

I will also have to add `force: yes` to build image even if it already exists, right?

@alkedr Yes, use _force_ to build an existing image. 


Resolving patch:
diff --git a/cloud/docker/docker_image.py b/cloud/docker/docker_image.py
--- a/cloud/docker/docker_image.py
+++ b/cloud/docker/docker_image.py
@@ -43,8 +43,8 @@
     version_added: "2.0"
   force:
     description:
-      - Use with absent state to un-tag and remove all images matching the specified name. Use with states C(present)
-        and C(tagged) to take action even when an image already exists.
+      - Use with state I(absent) to un-tag and remove all images matching the specified name. Use with state
+        C(present) to build, load or pull an image when the image already exists.
     default: false
     required: false
     version_added: "2.1"
@@ -105,13 +105,14 @@
         from Docker Hub. To build the image, provide a path value set to a directory containing a context and
         Dockerfile. To load an image, specify load_path to provide a path to an archive file. To tag an image to a
         repository, provide a repository path. If the name contains a repository path, it will be pushed.
-      - "NOTE: C(build) is DEPRECATED. Specifying C(build) will behave the same as C(present)."
+      - "NOTE: C(build) is DEPRECATED and will be removed in release 2.3. Specifying C(build) will behave the
+         same as C(present)."
     required: false
     default: present
     choices:
       - absent
       - present
-      - build (DEPRECATED)
+      - build
   tag:
     description:
       - Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to
@@ -528,7 +529,7 @@ def main():
         push=dict(type='bool', default=False),
         repository=dict(type='str'),
         rm=dict(type='bool', default=True),
-        state=dict(type='str', choices=['absent', 'present'], default='present'),
+        state=dict(type='str', choices=['absent', 'present', 'build'], default='present'),
         tag=dict(type='str', default='latest'),
         use_tls=dict(type='str', default='no', choices=['no', 'encrypt', 'verify'])
     )


Test patch: