#!/usr/bin/python
#
# Copyright 2016 Red Hat | Ansible
#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.

DOCUMENTATION = '''
---
module: docker_container

short_description: manage docker containers

description:
  - Manage the life cycle of docker containers.
  - Supports check mode. Run with --check and --diff to view config difference and list of actions to be taken.

version_added: "2.1.0"

options:
  blkio_weight:
    description:
      - Block IO (relative weight), between 10 and 1000.
    default: null
    required: false
  capabilities:
    description:
      - List of capabilities to add to the container.
    default: null
    required: false
  cleanup:
    description:
      - Use with I(detach) to remove the container after successful execution.
    default: false
    required: false
    version_added: "2.2"
  command:
    description:
      - Command to execute when the container starts.
    default: null
    required: false
  cpu_period:
    description:
      - Limit CPU CFS (Completely Fair Scheduler) period
    default: 0
    required: false
  cpu_quota:
    description:
      - Limit CPU CFS (Completely Fair Scheduler) quota
    default: 0
    required: false
  cpuset_cpus:
    description:
      - CPUs in which to allow execution C(1,3) or C(1-3).
    default: null
    required: false
  cpuset_mems:
    description:
      - Memory nodes (MEMs) in which to allow execution C(0-3) or C(0,1)
    default: null
    required: false
  cpu_shares:
    description:
      - CPU shares (relative weight).
    default: null
    required: false
  detach:
    description:
      - Enable detached mode to leave the container running in background.
        If disabled, the task will reflect the status of the container run (failed if the command failed).
    default: true
    required: false
  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
    required: false
  dns_servers:
    description:
      - List of custom DNS servers.
    default: null
    required: false
  dns_search_domains:
    description:
      - List of custom DNS search domains.
    default: null
    required: false
  env:
    description:
      - Dictionary of key,value pairs.
    default: null
    required: false
  env_file:
    version_added: "2.2"
    description:
      - Path to a file containing environment variables I(FOO=BAR).
      - If variable also present in C(env), then C(env) value will override.
      - Requires docker-py >= 1.4.0.
    default: null
    required: false
  entrypoint:
    description:
      - Command that overwrites the default ENTRYPOINT of the image.
    default: null
    required: false
  etc_hosts:
    description:
      - Dict of host-to-IP mappings, where each host name is a key in the dictionary.
        Each host name will be added to the container's /etc/hosts file.
    default: null
    required: false
  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
    required: false
    aliases:
      - exposed
  force_kill:
    description:
      - Use the kill command when stopping a running container. 
    default: false
    required: false
  groups:
    description:
      - List of additional group names and/or IDs that the container process will run as.
    default: null
    required: false
  hostname:
    description:
      - Container hostname.
    default: null
    required: false
  ignore_image:
    description:
      - When C(state) is I(present) or I(started) the module compares the configuration of an existing
        container to requested configuration. The evaluation includes the image version. If
        the image version in the registry does not match the container, the container will be
        recreated. Stop this behavior by setting C(ignore_image) to I(True).
    default: false
    required: false
    version_added: "2.2"      
  image:
    description:
      - Repository path and tag used to create the container. If an image is not found or pull is true, the image
        will be pulled from the registry. If no tag is included, 'latest' will be used.
    default: null
    required: false
  interactive:
    description:
      - Keep stdin open after a container is launched, even if not attached.
    default: false
    required: 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
    required: false
  keep_volumes:
    description:
      - Retain volumes associated with a removed container.
    default: true
    required: false
  kill_signal:
    description:
      - Override default signal used to kill a running container.
    default null:
    required: false
  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
    required: false
  labels:
     description:
       - Dictionary of key value pairs.
     default: null
     required: false
  links:
    description:
      - List of name aliases for linked containers in the format C(container_name:alias)
    default: null
    required: false
  log_driver:
    description:
      - Specify the logging driver. Docker uses json-file by default.
    choices:
      - json-file
      - syslog
      - journald
      - gelf
      - fluentd
      - awslogs
      - splunk
    default: null
    required: false
  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
    required: false
  memory:
    description:
      - "Memory limit (format: <number>[<unit>]). Number is a positive integer.
        Unit can be one of b, k, m, or g"
    default: 0
    required: false
  memory_reservation:
    description:
      - "Memory soft limit (format: <number>[<unit>]). Number is a posit
ive integer.
        Unit can be one of b, k, m, or g"
    default: 0
    required: false
  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
    required: false
  memory_swappiness:
    description:
        - Tune a container's memory swappiness beh
avior. Accepts an integer between 0 and 100.
    default: 0
    required: false
  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
    required: false
  networks:
     description:
       - List of networks the container belongs to.
       - Each network is a dict with keys C(name), C(ipv4_address), C(ipv6_address), C(links), C(aliases).
       - 