Merge pull request #15615 from chouseknecht/docker_guide

Adding getting started guide for Docker

docsite/rst/guide_docker.rst

@@ -0,0 +1,300 @@
+Getting Started with Docker
+===========================
+
+Ansible offers the following modules for orchestrating Docker containers:
+
+    docker_container
+        Manages the container lifecycle by providing the ability to create, update, stop, start and destroy a
+        container.
+
+    docker_image
+        Provides full control over images, including: build, pull, push, tag and remove.
+
+    docker_image_facts
+        Inspects one or more images in the Docker host's image cache, providing the information as facts for making
+        decision or assertions in a playbook.
+
+    docker_login
+        Authenticates with Docker Hub or any Docker registry and updates the Docker Engine config file, which
+        in turn provides password-free pushing and pulling of images to and from the registry.
+
+    docker (dynamic inventory)
+        Dynamically builds an inventory of all the available containers from a set of one or more Docker hosts.
+
+
+Ansible 2.1.0 includes major updates to the Docker modules, marking the start of a project to create a complete and
+integrated set of tools for orchestrating containers. The docker_image and docker_login modules as well as the dynamic
+inventory script were refactored to use a common set of parameters and environment variables for shaping Docker API
+connections. The docker_container and docker_image_facts modules are new.
+
+
+Requirements
+------------
+
+Using the docker modules requires having `docker-py <https://docker-py.readthedocs.org/en/stable/>`_
+installed on the host running Ansible. You will need to have >= 1.7.0 installed.
+
+.. code-block:: bash
+
+    $ pip install docker-py>=1.7.0
+
+
+Connecting to the Docker API
+----------------------------
+
+You can connect to a local or remote API using parameters passed to each task or by setting environment variables.
+The order of precedence is command line parameters and then environment variables. If neither a command line
+option for a environment variable is found, then a default value will be used. The default values are provided under
+`Parameters`_
+
+
+Parameters
+..........
+
+Control how modules connect to the Docker API by passing the following parameters:
+
+    docker_host
+        The URL or Unix socket path used to connect to the Docker API. Defaults to ``unix://var/run/docker.sock``.
+        To connect to a remote host, provide the TCP connection string. For example: ``tcp://192.168.99.100:2376``. If
+        TLS is used to encrypt the connection to the API, then the module will automatically replace 'tcp' in the
+        connection URL with 'https'.
+
+    api_version
+        The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported
+        by docker-py.
+
+    timeout
+        The maximum amount of time in seconds to wait on a response from the API. Defaults to 60 seconds.
+
+    tls
+        Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server.
+        Defaults to False.
+
+    tls_verify
+        Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
+        Default is False.
+
+    cacert_path
+        Use a CA certificate when performing server verification by providing the path to a CA certificate file.
+
+    cert_path
+        Path to the client's TLS certificate file.
+
+    key_path
+        Path to the client's TLS key file.
+
+    tls_hostname
+        When verifying the authenticity of the Docker Host server, provide the expected name of the server. Defaults
+        to 'localhost'.
+
+    ssl_version
+        Provide a valid SSL version number. Default value determined by docker-py, which at the time of this writing
+        was 1.0
+
+
+Environment Variables
+.....................
+
+Control how the modules connect to the Docker API by setting the following variables in the environment of the host
+running Ansible:
+
+    DOCKER_HOST
+        The URL or Unix socket path used to connect to the Docker API.
+
+    DOCKER_API_VERSION
+        The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported
+        by docker-py.
+
+    DOCKER_TIMEOUT
+        The maximum amount of time in seconds to wait on a response from the API.
+
+    DOCKER_CERT_PATH
+        Path to the directory containing the client certificate, client key and CA certificate.
+
+    DOCKER_SSL_VERSION
+        Provide a valid SSL version number.
+
+    DOCKER_TLS
+        Secure the connection to the API by using TLS without verifying the authenticity of the Docker Host.
+
+    DOCKER_TLS_VERIFY
+        Secure the connection to the API by using TLS and verify the authenticity of the Docker Host.
+
+
+Dynamic Inventory Script
+------------------------
+The inventory script generates dynamic inventory by making API requests to one or more Docker APIs. It's dynamic
+because the inventory is generated at run-time rather than being read from a static file. The script generates the
+inventory by connecting to one or many Docker APIs and inspecting the containers it finds at each API. Which APIs the
+script contacts can be defined using environment variables or a configuration file.
+
+Groups
+......
+The script will create the following host groups:
+
+ - container id
+ - container name
+ - container short id
+ - image_name  (image_<image name>)
+ - docker_host
+ - running
+ - stopped
+
+Examples
+........
+
+You can run the script interactively from the command line or pass it as the inventory to a playbook. Here are few
+examples to get you started:
+
+.. code-block:: bash
+
+    # Connect to the Docker API on localhost port 4243 and format the JSON output
+    DOCKER_HOST=tcp://localhost:4243 ./docker.py --pretty
+
+    # Any container's ssh port exposed on 0.0.0.0 will be mapped to
+    # another IP address (where Ansible will attempt to connect via SSH)
+    DOCKER_DEFAULT_IP=1.2.3.4 ./docker.py --pretty
+
+    # Run as input to a playbook:
+    ansible-playbook -i ~/projects/ansible/contrib/inventory/docker.py docker_inventory_test.yml
+
+    # Simple playbook to invoke with the above example:
+
+        - name: Test docker_inventory
+          hosts: all
+          connection: local
+          gather_facts: no
+          tasks:
+            - debug: msg="Container - {{ inventory_hostname }}"
+
+Configuration
+.............
+You can control the behavior of the inventory script by defining environment variables, or
+creating a docker.yml file (sample provided in ansible/contrib/inventory). The order of precedence is the docker.yml
+file and then environment variables.
+
+
+Environment Variables
+;;;;;;;;;;;;;;;;;;;;;;
+
+To connect to a single Docker API the following variables can be defined in the environment to control the connection
+options. These are the same environment variables used by the Docker modules.
+
+    DOCKER_HOST
+        The URL or Unix socket path used to connect to the Docker API. Defaults to unix://var/run/docker.sock.
+
+    DOCKER_API_VERSION:
+        The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported
+        by docker-py.
+
+    DOCKER_TIMEOUT:
+        The maximum amount of time in seconds to wait on a response fromm the API. Defaults to 60 seconds.
+
+    DOCKER_TLS:
+        Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server.
+        Defaults to False.
+
+    DOCKER_TLS_VERIFY:
+        Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
+        Default is False
+
+    DOCKER_TLS_HOSTNAME:
+        When verifying the authenticity of the Docker Host server, provide the expected name of the server. Defaults
+        to localhost.
+
+    DOCKER_CERT_PATH:
+        Path to the directory containing the client certificate, client key and CA certificate.
+
+    DOCKER_SSL_VERSION:
+        Provide a valid SSL version number. Default value determined by docker-py, which at the time of this writing
+        was 1.0
+
+In addition to the connection variables there are a couple variables used to control the execution and output of the
+script:
+
+    DOCKER_CONFIG_FILE
+        Path to the configuration file. Defaults to ./docker.yml.
+
+    DOCKER_PRIVATE_SSH_PORT:
+        The private port (container port) on which SSH is listening for connections. Defaults to 22.
+
+    DOCKER_DEFAULT_IP:
+        The IP address to assign to ansible_host when the container's SSH port is mapped to interface '0.0.0.0'.
+
+
+Configuration File
+;;;;;;;;;;;;;;;;;;
+
+Using a configuration file provides a means for defining a set of Docker APIs from which to build an inventory.
+
+The default name of the file is derived from the name of the inventory script. By default the script will look for
+basename of the script (i.e. docker) with an extension of '.yml'.
+
+You can also override the default name of the script by defining DOCKER_CONFIG_FILE in the environment.
+
+Here's what you can define in docker_inventory.yml:
+
+    defaults
+        Defines a default connection. Defaults will be taken from this and applied to any values not provided
+        for a host defined in the hosts list.
+
+    hosts
+        If you wish to get inventory from more than one Docker host, define a hosts list.
+
+For the default host and each host in the hosts list define the following attributes:
+
+.. code-block:: yaml
+
+  host:
+      description: The URL or Unix socket path used to connect to the Docker API.
+      required: yes
+
+  tls:
+     description: Connect using TLS without verifying the authenticity of the Docker host server.
+     default: false
+     required: false
+
+  tls_verify:
+     description: Connect using TLS without verifying the authenticity of the Docker host server.
+     default: false
+     required: false
+
+  cert_path:
+     description: Path to the client's TLS certificate file.
+     default: null
+     required: false
+
+  cacert_path:
+     description: Use a CA certificate when performing server verification by providing the path to a CA certificate file.
+     default: null
+     required: false
+
+  key_path:
+     description: Path to the client's TLS key file.
+     default: null
+     required: false
+
+  version:
+     description: The Docker API version.
+     required: false
+     default: will be supplied by the docker-py module.
+
+  timeout:
+     description: The amount of time in seconds to wait on an API response.
+     required: false
+     default: 60
+
+  default_ip:
+     description: The IP address to assign to ansible_host when the container's SSH port is mapped to interface
+     '0.0.0.0'.
+     required: false
+     default: 127.0.0.1
+
+  private_ssh_port:
+     description: The port containers use for SSH
+     required: false
+     default: 22
+
+
+
+

docsite/rst/guides.rst

@@ -1,7 +1,7 @@
 Detailed Guides
 ```````````````
 
-This section is new and evolving.  The idea here is explore particular use cases in greater depth and provide a more "top down" explanation of some basic features.
+This section is new and evolving.  The idea here is to explore particular use cases in greater depth and provide a more "top down" explanation of some basic features.
 
 .. toctree::
    :maxdepth: 1
@@ -13,5 +13,6 @@ This section is new and evolving.  The idea here is explore particular use cases
    guide_cloudstack
    guide_vagrant
    guide_rolling_upgrade
+   guide_docker
 
 Pending topics may include: Docker, Jenkins, Google Compute Engine, Linode/DigitalOcean, Continuous Deployment, and more.