Adding getting started guide for Docker
This commit is contained in:
chouseknecht
parent
8f31634977
commit
5e7e55830f
297
docsite/rst/guide_docker.rst
Normal file
297
docsite/rst/guide_docker.rst
Normal file
|
|
@ -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 <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 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_<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
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue