Руководство по 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 Host. По умолчанию используется последняя версия API, поддерживаемая docker-py.

DOCKER_TIMEOUT

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

DOCKER_CERT_PATH

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

DOCKER_SSL_VERSION

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

DOCKER_TLS

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

DOCKER_TLS_VERIFY

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

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

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

Группы

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

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

Примеры

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

# 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 Host. По умолчанию используется последняя версия API, поддерживаемая docker-py.

DOCKER_TIMEOUT:

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

DOCKER_TLS:

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

DOCKER_TLS_VERIFY:

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

DOCKER_TLS_HOSTNAME:

При проверке подлинности сервера Docker Host укажите ожидаемое имя сервера. По умолчанию 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.

hosts

Если вы хотите получить инвентаризацию от более чем одного хоста Docker, определите список hosts.

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

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