From 07f6df36249bc5c86c1042d0923d3f763e2dd490 Mon Sep 17 00:00:00 2001 From: chouseknecht Date: Wed, 27 Apr 2016 03:09:59 -0400 Subject: [PATCH 1/3] Adding getting started guide for Docker --- docsite/rst/guide_docker.rst | 297 +++++++++++++++++++++++++++++++++++ docsite/rst/guides.rst | 3 +- 2 files changed, 299 insertions(+), 1 deletion(-) create mode 100644 docsite/rst/guide_docker.rst diff --git a/docsite/rst/guide_docker.rst b/docsite/rst/guide_docker.rst new file mode 100644 index 0000000000..3ab86fb308 --- /dev/null +++ b/docsite/rst/guide_docker.rst @@ -0,0 +1,297 @@ +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 `_ +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 command line 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 +`Command Line Parameters`_ + + +Command Line Parameters +....................... + +Control how modules connect to the Docker API by passing the following options to a task: + + 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 'tcp' in the connection URL will be replace 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 clients 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_) + - 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 + + + + diff --git a/docsite/rst/guides.rst b/docsite/rst/guides.rst index 3a0178b4d2..7398a880f3 100644 --- a/docsite/rst/guides.rst +++ b/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. From 20c2c1a771eb7b0e715c6f1aa5d4ff3dda056519 Mon Sep 17 00:00:00 2001 From: chouseknecht Date: Wed, 27 Apr 2016 03:34:20 -0400 Subject: [PATCH 2/3] Change command line parameters to parameters. --- docsite/rst/guide_docker.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docsite/rst/guide_docker.rst b/docsite/rst/guide_docker.rst index 3ab86fb308..22ba63d0e6 100644 --- a/docsite/rst/guide_docker.rst +++ b/docsite/rst/guide_docker.rst @@ -42,16 +42,16 @@ installed on the host running Ansible. You will need to have >= 1.7.0 installed. Connecting to the Docker API ---------------------------- -You can connect to a local or remote API using command line 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 +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 -`Command Line Parameters`_ +`Parameters`_ -Command Line Parameters -....................... +Parameters +.......... -Control how modules connect to the Docker API by passing the following options to a task: +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``. @@ -167,7 +167,7 @@ examples to get you started: - 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. @@ -233,10 +233,12 @@ You can also override the default name of the script by defining DOCKER_CONFIG_F 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. + 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. + 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: From fb19d064b19f56f7f1dc10c6b84b9cb86f60cf23 Mon Sep 17 00:00:00 2001 From: chouseknecht Date: Wed, 27 Apr 2016 04:04:40 -0400 Subject: [PATCH 3/3] Fixed docker_host definition. --- docsite/rst/guide_docker.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docsite/rst/guide_docker.rst b/docsite/rst/guide_docker.rst index 22ba63d0e6..88d39ad0a5 100644 --- a/docsite/rst/guide_docker.rst +++ b/docsite/rst/guide_docker.rst @@ -56,7 +56,8 @@ Control how modules connect to the Docker API by passing the following parameter 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 'tcp' in the connection URL will be replace with 'https'. + 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 @@ -80,7 +81,7 @@ Control how modules connect to the Docker API by passing the following parameter Path to the client's TLS certificate file. key_path - Path to the clients TLS key file. + 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