Начало работы с Docker

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

docker_service

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

docker_container

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

docker_image

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

docker_image_facts

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

docker_login

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

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

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

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

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

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

Планируется еще больше. Ознакомьтесь с последними идеями и концепциями в репозитории предложений 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_service также требует 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 на один или несколько Docker API. Он динамичен, потому что инвентарь генерируется во время выполнения, а не считывается из статического файла. Сценарий генерирует инвентарь, подключаясь к одному или нескольким Docker API и просматривая обнаруженные контейнеры на каждом API. К каким API обращается сценарий, можно определить с помощью переменных окружения или файла конфигурации.

Группы

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

• идентификатор контейнера
• имя контейнера
• краткий идентификатор контейнера
• image_name (image_<имя изображения>)
• docker_host
• запущенные
• остановленные

Примеры

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

# 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, а затем переменные окружения.

Переменные окружения

Для подключения к одному Docker API можно определить следующие переменные окружения для управления параметрами подключения. Это те же переменные окружения, которые используются модулями 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'.

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

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

Имя файла по умолчанию получено из имени сценария инвентаризации. По умолчанию сценарий будет искать имя сценария (например, 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