Руководство по Docker

Ansible предлагает следующие модули для управления контейнерами Docker:

docker_compose

Используйте ваши существующие файлы Docker Compose для управления контейнерами на одном демоне Docker или в Swarm. Поддерживает версии Compose 1 и 2.

docker_container

Управляет жизненным циклом контейнера, предоставляя возможность создания, обновления, остановки, запуска и уничтожения контейнера.

docker_image

Предоставляет полный контроль над изображениями, включая: создание, загрузку, отправку, добавление тегов и удаление.

docker_image_info

Просматривает одно или несколько изображений в кэше изображений хоста Docker, предоставляя информацию для принятия решений или утверждений в плейбуке.

docker_login

Авторизуется на Docker Hub или любом реестре Docker и обновляет конфигурационный файл Docker Engine, что в свою очередь обеспечивает бесключевое отправление и загрузку изображений в и из реестра.

docker (динамический инвентарь)

Динамически создаёт инвентарь всех доступных контейнеров из набора одного или нескольких хостов Docker.

Ansible 2.1.0 включает значительные обновления модулей Docker, отмечая начало проекта по созданию комплексного и интегрированного набора инструментов для управления контейнерами. В дополнение к вышеперечисленным модулям мы также работаем над следующими:

Вы по-прежнему используете Dockerfile для создания изображений? Ознакомьтесь с ansible-bender и начните создавать изображения из ваших плейбуков Ansible.

Используйте Ansible Operator для запуска вашего файла docker-compose на OpenShift. Перейдите от приложения на вашем ноутбуке к полностью масштабируемому приложению в облаке с Kubernetes всего за несколько мгновений.

Планируется ещё много. Ознакомьтесь с последними идеями и мыслями в репозитории предложений Ansible.

Требования

Использование модулей docker требует установки Docker SDK для Python на хосте, на котором работает Ansible. Вам потребуется версия >= 1.7.0. Для Python 2.7 или Python 3 вы можете установить его следующим образом:

$ pip install docker

Для Python 2.6 вам нужна версия до 2.0. Для этих версий SDK назывался docker-py, поэтому вам нужно установить его следующим образом:

$ pip install 'docker-py>=1.7.0'

Обратите внимание, что должен быть установлен только один из docker и docker-py. Установка обоих приведёт к ошибочной установке. Если это произойдёт, Ansible обнаружит это и проинформирует вас:

Cannot have both the docker-py and docker python modules installed together as they use the same
namespace and cause a corrupt installation. Please uninstall both packages, and re-install only
the docker-py or docker python module. It is recommended to install the docker module if no support
for Python 2.6 is required. Please note that simply uninstalling one of the modules can leave the
other module in a broken state.

Модуль docker_compose также требует docker-compose

$ pip install 'docker-compose>=1.7.0'

Подключение к API Docker

Вы можете подключиться к локальному или удалённому API, используя параметры, передаваемые каждой задаче, или задавая переменные среды. Порядок приоритета: параметры командной строки, а затем переменные среды. Если ни параметр командной строки, ни переменная среды не найдены, будет использоваться значение по умолчанию. Значения по умолчанию приведены в разделе Параметры

Параметры

Управление подключением модулей к API Docker путём передачи следующих параметров:

docker_host

URL или путь к сокету Unix, используемый для подключения к API Docker. По умолчанию unix://var/run/docker.sock. Для подключения к удалённому хосту укажите строку TCP-соединения. Например: tcp://192.0.2.23:2376. Если для шифрования подключения к API используется TLS, модуль автоматически заменит «tcp» в URL соединения на «https».

api_version

Версия API Docker, работающего на хосте Docker. По умолчанию - последняя версия API, поддерживаемая docker-py.

timeout

Максимальное время ожидания ответа от API в секундах. По умолчанию 60 секунд.

tls

Защитите подключение к API с помощью TLS, не проверяя подлинность сервера хоста Docker. По умолчанию False.

tls_verify

Защитите подключение к API с помощью TLS и проверьте подлинность сервера хоста Docker. По умолчанию False.

cacert_path

Используйте сертификат CA при проверке сервера, указав путь к файлу сертификата CA.

cert_path

Путь к файлу TLS-сертификата клиента.

key_path

Путь к файлу TLS-ключа клиента.

tls_hostname

При проверке подлинности сервера хоста Docker укажите ожидаемое имя сервера. По умолчанию «localhost».

ssl_version

Укажите допустимый номер версии SSL. Значение по умолчанию определяется docker-py, на момент написания документации - 1.0

Переменные среды

Управление подключением модулей к API Docker путём установки следующих переменных в среде хоста, на котором работает Ansible:

DOCKER_HOST

URL или путь к сокету Unix, используемый для подключения к API Docker.

DOCKER_API_VERSION

Версия API Docker, работающего на хосте Docker. По умолчанию - последняя версия API, поддерживаемая docker-py.

DOCKER_TIMEOUT

Максимальное время ожидания ответа от API в секундах.

DOCKER_CERT_PATH

Путь к каталогу, содержащему клиентский сертификат, ключ клиента и сертификат CA.

DOCKER_SSL_VERSION

Укажите допустимый номер версии SSL.

DOCKER_TLS

Защитите подключение к API с помощью TLS, не проверяя подлинность сервера хоста Docker.

DOCKER_TLS_VERIFY

Защитите подключение к API с помощью TLS и проверьте подлинность сервера хоста Docker.

Сценарий динамического инвентаря

Сценарий инвентаря генерирует динамический инвентарь путём отправки запросов API к одному или нескольким API Docker. Он динамичен, так как инвентарь генерируется во время выполнения, а не считывается из статического файла. Сценарий генерирует инвентарь путём подключения к одному или нескольким API Docker и проверки контейнеров, которые он находит в каждом API. С какими API сценарий связывается, может быть определено с помощью переменных среды или файла конфигурации.

Группы

Сценарий создаст следующие группы хостов:

• идентификатор контейнера
• имя контейнера
• короткая форма идентификатора контейнера
• image_name (image_<имя изображения>)
• docker_host
• running
• stopped

Примеры

Вы можете запустить сценарий интерактивно из командной строки или передать его как инвентарь в плейбук. Вот несколько примеров для начала работы:

# 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=192.0.2.5 ./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, this will not connect to any hosts
      hosts: all
      gather_facts: no
      tasks:
        - debug: msg="Container - {{ inventory_hostname }}"

Конфигурация

Вы можете управлять поведением сценария инвентаря, задавая переменные среды или создавая файл docker.yml (пример приведен в ansible/contrib/inventory). Порядок приоритета: файл docker.yml, а затем переменные среды.

Переменные среды

Для подключения к одному API Docker можно задать следующие переменные среды для управления параметрами подключения. Это те же переменные среды, которые используются модулями Docker.

DOCKER_HOST

URL или путь к сокету Unix, используемый для подключения к API Docker. По умолчанию unix://var/run/docker.sock.

DOCKER_API_VERSION:

Версия API Docker, работающего на хосте Docker. По умолчанию - последняя версия API, поддерживаемая docker-py.

DOCKER_TIMEOUT:

Максимальное время ожидания ответа от API в секундах. По умолчанию 60 секунд.

DOCKER_TLS:

Защитите подключение к API с помощью TLS, не проверяя подлинность сервера хоста Docker. По умолчанию False.

DOCKER_TLS_VERIFY:

Защитите подключение к API с помощью TLS и проверьте подлинность сервера хоста Docker. По умолчанию False

DOCKER_TLS_HOSTNAME:

При проверке подлинности сервера хоста Docker укажите ожидаемое имя сервера. По умолчанию localhost.

DOCKER_CERT_PATH:

Путь к каталогу, содержащему клиентский сертификат, ключ клиента и сертификат CA.

DOCKER_SSL_VERSION:

Укажите допустимый номер версии SSL. Значение по умолчанию определяется docker-py, на момент написания документации - 1.0

В дополнение к переменным подключения есть несколько переменных, используемых для управления выполнением и выводом сценария:

DOCKER_CONFIG_FILE

Путь к файлу конфигурации. По умолчанию ./docker.yml.

DOCKER_PRIVATE_SSH_PORT:

Приватный порт (порт контейнера), на котором SSH слушает подключения. По умолчанию 22.

DOCKER_DEFAULT_IP:

IP-адрес, который нужно назначить ansible_host, когда SSH-порт контейнера отображается на интерфейсе «0.0.0.0».

Файл конфигурации

Использование файла конфигурации позволяет определить набор API Docker, с помощью которого создаётся инвентарь.

Имя файла по умолчанию выводится из имени скрипта инвентаря. По умолчанию сценарий будет искать имя скрипта (например, docker) с расширением «.yml».

Вы также можете переопределить имя скрипта по умолчанию, задав DOCKER_CONFIG_FILE в среде.

Вот что вы можете определить в docker_inventory.yml:

defaults

Определяет подключение по умолчанию. Значения по умолчанию будут взяты из этого и применены ко всем значениям, не предоставленным для хоста, определённого в списке хостов.

hosts

Если вы хотите получить инвентарь с нескольких хостов Docker, определите список хостов.

Для хоста по умолчанию и каждого хоста в списке хостов определите следующие атрибуты:

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