Merge pull request #14644 from chouseknecht/docker_one

Add docker_container module proposal.

docs/proposals/docker/docker_container_moduler.md

@@ -0,0 +1,525 @@
+# 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 to 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 related to connecting to the API are not listed here.
+
+```
+blkio_weight:
+  description:
+    - Block IO weight
+  default: null
+
+blkio_weight_devices:
+  description:
+    - List of C(DEVICE_NAME:WEIGHT) pairs
+  default: null
+
+capabilities:
+  description:
+    - List of capabilities to add to the container.
+  default: null
+
+capabilities_drop:
+  description:
+    - List of capabilities to remove from the container
+  default: null
+
+cgroup_parent:
+  description:
+    - Optional parent cgroup for the container
+  default: null
+
+command:
+  description:
+    - Command executed in the container when it starts.
+  default: null
+
+cpu_period:
+  description:
+    - Limit CPU CFS (Completely Fair Scheduler) period. Expressed in milliseconds.
+  default: 0
+
+cpu_quota:
+  description:
+    - Limit CPU CFS (Completely Fair Scheduler) quota. Expressed in milliseconds.
+  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. Integer value.
+  default: 0
+
+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 devices to add to the container
+  default: null
+
+device_read_bps
+  description:
+    - List. Limit read rate (bytes per second) from a device in the format C(/dev/sda:1mb)
+  default: null
+
+device_read_iops:
+  description:
+    - List. Limit read rate (IO per second) from a device in the format C(/dev/sda:1000)
+  default: null
+
+device_write_bps:
+  description:
+    - List. Limit write rate (bytes per second) to a device in the foramt C(/dev/sda:1mb)
+  default: null
+
+device_write_iops:
+  description:
+    - List. Limit write rate (IO per second) to a device C(/dev/sda:1000)
+  default: null
+
+dns_servers:
+  description:
+    - List of custom DNS servers.
+  default: null
+
+dns_opts:
+  description:
+    - List of custom DNS options. Each option is written as an options line
+      into the container's /etc/resolv.conf.
+  default: null
+
+dns_search_domains:
+  description:
+    - List of custom DNS search domains.
+  default: null
+
+env_vars:
+  description:
+    - Dictionary of key,value pairs.
+  default: null
+
+entrypoint:
+  description:
+    - Overwrite the default ENTRYPOINT of the image.
+  default: null
+
+etc_hosts:
+  description:
+    - List of custom host-to-IP mappings, with each mapping in the format C(host:ip), to 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
+
+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 groups to join.
+  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
+
+ip_address:
+  description:
+    - Container IPv4 address.
+  default: null
+
+ipv6_address:
+  description:
+    - Container IPv6 address.
+  default: null
+
+ipc_namespace:
+  description:
+    - Container IPC namespace.
+  default: null
+
+keep_volumes:
+  description:
+    - Retain volumes associated with a removed container.
+  default: false
+
+kill_signal:
+  description:
+    - Signal used to kill a running container when state is absent.
+  default: KILL
+
+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:
+     - Set meta data on the cotnainer. Dictionary of key value paris:
+   default: null
+
+links:
+  description:
+    - List of name aliases for linked containers in the format C(redis:myredis)
+  default: null
+
+log_driver:
+  description:
+    - Specify the logging driver.
+  choices:
+    - json-file
+    - syslog
+    - journald
+    - gelf
+    - fluentd
+    - awslogs
+    - splunk
+  defult: json-file
+
+log_opt:
+  description:
+    - Additional options to pass to the logging driver selected above. See Docker `log-driver
+      <https://docs.docker.com/reference/logging/overview/>` documentation for more information.
+  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_swapiness:
+    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
+
+net:
+  description:
+    - Connect the container to a network.
+  choices:
+    - bridge
+    - container:<name|id>
+    - host
+  default: null
+
+net_alias:
+  description:
+    - Add network scoped alias to the container.
+  default: null
+
+paused:
+  description:
+    - Use with the started state to pause running processes inside the container.
+  default: false
+
+pid:
+  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.
+
+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:
+    - no
+    - on-failure
+    - always
+    - unless-stopped
+  default: no
+
+restart_policy_retry:
+   description:
+     - When C(restart_policy) is on-failure sets the max number of retries.
+   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:
+    - Signal used to stop the container.
+  default: SIGINT
+
+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
+
+ulimit:
+  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).
+      Starting at version 2.1, SELinux hosts can additionally use C(z) or C(Z)
+      mount options to use a shared or private label for the volume.
+default: null
+
+volumes_from:
+  description:
+    - List of container names to mount 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,
+    results: {
+        < the results of `docker inspect` >
+    }
+}
+```
+
+## Contributors
+
+[chouseknecht](http://twitter.com/chouseknecht)
+
+*Last Updated:* 2016-02-24