docker

Что такое ansible-docker?

Это Ansible роль, которая:

• Устанавливает Docker (поддерживаются различные версии и каналы)
• Устанавливает Docker Compose v2 и/или Docker Compose v1 (поддерживается указание версии)
• Устанавливает пакет docker через PIP для работы модулей Ansible docker_*
• Управляет учетными данными для доступа к Docker-реестру
• Настраивает одного или несколько пользователей для работы с Docker без прав суперпользователя
• Конфигурирует параметры демона Docker и переменные окружения
• Настраивает задачу cron для выполнения команд очистки Docker

Зачем использовать эту роль?

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

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

Поддерживаемые платформы

• Ubuntu 20.04 LTS (Focal Fossa)
• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Debian 11 (Bullseye)
• Debian 12 (Bookworm)

Предыдущие версии могут работать, но официально не поддерживаются.

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

Быстрый старт

Философия всех моих ролей — облегчить начало работы, при этом предоставить возможности для настройки практически всего.

Что настраивается по умолчанию?

Будет установлена последняя стабильная версия Docker CE и Docker Compose v2, очистка диска Docker будет выполняться раз в неделю, а логи контейнеров Docker будут отправляться в journald.

Пример плейбука

---

# docker.yml

- name: Пример
  hosts: "all"
  become: true

  roles:
    - role: "nickjj.docker"
      tags: ["docker"]

Используйте: ansible-playbook docker.yml

Установка

$ ansible-galaxy install nickjj.docker

Переменные роли по умолчанию

Установка Docker

Канал

Хотите использовать "stable" или "test" канал? Можно добавить несколько (важен порядок).

docker__channel: ["stable"]

Версия

• При установке "", будет установлена текущая последняя версия Docker.
• При установке конкретной версии будет установлена указанная версия Docker.

docker__version: ""

# Например, закрепить на 25.0.
docker__version: "25.0"

# Например, закрепить на более точной версии 25.0.
docker__version: "25.0.5"

Закрепления устанавливаются с * в конце версии пакета, поэтому вы получите незначительные и защищенные патчи, если не укажете точную версию.

Стратегия обновления

• При установке "present" повторный запуск этой роли в будущем не установит новые версии (если они доступны).
• При установке "latest" повторный запуск этой роли в будущем установит новые версии (если они доступны).

docker__state: "present"

Стратегия понижения версии

Самый простой способ понизить версию — вручную удалить пакет Docker, а затем снова запустить эту роль, указав нужную версию Docker.

# Ansible команда для остановки и удаления пакета Docker CE на всех хостах.
ansible all -m systemd -a "name=docker-ce state=stopped" \
  -m apt -a "name=docker-ce autoremove=true purge=true state=absent" -b

Установка Docker Compose v2

Docker Compose v2 будет установлен с помощью apt через официальный docker-compose-plugin, который управляется Docker.

Версия

• При установке "", будет установлена текущая последняя версия Docker Compose v2.
• При установке конкретной версии будет установлена указанная версия Docker Compose v2.

docker__compose_v2_version: ""

# Например, закрепить на 2.29.
docker__compose_v2_version: "2.29"

# Например, закрепить на более точной версии 2.29.1.
docker__compose_v2_version: "2.29.1"

Стратегия обновления

Будет использована та же переменная docker__state, описанная в разделе об установке Docker.

Стратегия понижения версии

Как и в случае с самим Docker, наиболее простой способ удалить Docker Compose v2 — это вручную запустить команду ниже, а затем закрепить конкретную версию Docker Compose v2.

# Ansible команда для удаления пакета Docker Compose Plugin на всех хостах.
ansible all -m apt -a "name=docker-compose-plugin autoremove=true purge=true state=absent" -b

Установка Docker Compose v1

По умолчанию эта роль не устанавливает Docker Compose v1, так как он официально устарел и больше не получает обновлений от Docker. Тем не менее, эта роль может его установить. Вам просто нужно установить docker__pip_docker_compose_state: "present", так как по умолчанию эта роль установлена на absent.

По сути, обе версии могут быть установлены вместе, так как v1 используется с docker-compose, а v2 — с docker compose (обратите внимание на отсутствие дефиса).

Я бы посоветовал не устанавливать v1, если это не требуется для работы со старыми системами. Если вы решите его установить, вы можете настроить, какая версия будет установлена ниже. Если не указано, эти версии остаются неиспользуемыми:

Версия

• При установке "", будет установлена текущая последняя версия Docker Compose v1.
• При установке конкретной версии будет установлена указанная версия Docker Compose v1.

docker__compose_version: ""

# Например, закрепить на 1.29.
docker__compose_version: "1.29"

# Например, закрепить на более точной версии 1.29.
docker__compose_version: "1.29.2"

Стратегии обновления и понижения будут объяснены в другом разделе этого README.

Настройка пользователей для работы с Docker без root

Список пользователей, которых нужно добавить в группу docker.

Имейте в виду, что этот пользователь должен уже существовать; эта роль не создаст его. Если вы хотите создать пользователей, посмотрите мою роль пользователя.

Эта роль по умолчанию не настраивает пространства имен пользователей или другие функции безопасности. Если у добавленного здесь пользователя есть SSH-доступ к вашему серверу, вы фактически предоставляете ему доступ root, так как он может запускать Docker без sudo и подключать объемы к любому пути в вашей файловой системе.

В контролируемой среде это безопасно, но, как и с любыми вопросами безопасности, это стоит знать заранее. Вы можете активировать пространства имен пользователей и любые другие опции с помощью переменной docker__daemon_json, которая будет описана позже.

# Попробуйте использовать пользователя sudo по умолчанию, но вернуться к root, если его нет.
docker__users: ["{{ ansible_env.SUDO_USER | d('root') }}"]

# Например, если нужный вам пользователь отличается от пользователя sudo.
docker__users: ["admin"]

Настройка логинов для Docker-реестра

Вход в один или несколько Docker-реестров (например, на Docker Hub).

# Ваши учетные данные войдут в домашний каталог этого пользователя.
docker__login_become_user: "{{ docker__users | first | d('root') }}"

# 0 или более реестров для входа.
docker__registries:
  - #registry_url: "https://index.docker.io/v1/"
    username: "ваше_имя_пользователя_на_docker_hub"
    password: "ваш_пароль_на_docker_hub"
    #email: "ваш_email_на_docker_hub"
    #reauthorize: false
    #config_path: "$HOME/.docker/config.json"
    #state: "present"
docker__registries: []

Свойства, начинающиеся с *, обязательны для заполнения.

• registry_url по умолчанию равен https://index.docker.io/v1/
• *username — ваше имя пользователя в реестре Docker
• *password — ваш пароль в реестре Docker
• email по умолчанию не используется (не все реестры требуют его)
• reauthorize по умолчанию false, когда true, обновляет ваши учетные данные
• config_path по умолчанию — это домашний каталог пользователя docker__login_become_user
• state по умолчанию равен "present", когда "absent", вход будет удален

Настройка параметров демона Docker (json)

Параметры демона Docker по умолчанию, как они будут выглядеть в /etc/docker/daemon.json.

docker__default_daemon_json: |
  "log-driver": "journald",
  "features": {
    "buildkit": true
  }

# Добавьте свои дополнительные параметры демона, не переопределяя параметры по умолчанию.
# Они следуют тому же формату, что и параметры по умолчанию, и не беспокойтесь о
# необходимости начинать с запятой. Шаблон добавит запятую при необходимости.
docker__daemon_json: ""

Конфигурирование параметров демона Docker (флаги)

Флаги, которые устанавливаются при запуске демона Docker, не могут быть изменены в файле daemon.json. По умолчанию Docker устанавливает -H unix://, что означает, что это параметр не может быть изменен через json параметры.

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

# Каждый флаг командной строки должен быть отдельным элементом в списке.
#
# Используете Docker версии до 18.09?
#   Вам нужно установить `-H fd://`, а не `-H unix://`.
docker__daemon_flags:
  - "-H unix://"

Если вы не укажете какой-либо тип флага -H, Docker не запустится.

Настройка переменных окружения демона Docker

docker__daemon_environment: []

# Например, вот как установить несколько переменных окружения для прокси.
docker__daemon_environment:
  - "HTTP_PROXY=http://proxy.example.com:80"
  - "HTTPS_PROXY=https://proxy.example.com:443"

Настройка расширенных директив systemd

Эта роль позволяет пакету Docker управлять собственным файлом юнита systemd и регулировать такие вещи, как флаги и переменные среды демона Docker, используя шаблон переопределений systemd.

Если вы знаете, что делаете, вы можете переопределить или добавить любые директивы systemd Docker, установив эту переменную. Все, что вы поместите в эту строку, будет записано в /etc/systemd/system/docker.service.d/custom.conf без изменений.

docker__systemd_override: ""

Настройка задач cron для связанных с Docker

По умолчанию это будет безопасно очищать место на диске, используемое Docker, каждое воскресенье в полночь.

# `a` удаляет неиспользуемые образы (полезно в производстве).
# `f` заставляет это происходить без запроса вашего согласия.
docker__cron_jobs_prune_flags: "af"

# Управление расписанием очистки системы Docker.
docker__cron_jobs_prune_schedule: ["0", "0", "*", "*", "0"]

docker__cron_jobs:
  - name: "Очистка диска Docker"
    job: "docker system prune -{{ docker__cron_jobs_prune_flags }} > /dev/null 2>&1"
    schedule: "{{ docker__cron_jobs_prune_schedule }}"
    cron_file: "docker-disk-clean-up"
    #user: "{{ (docker__users | first) | d('root') }}"
    #state: "present"

Свойства, начинающиеся с *, обязательны для заполнения.

• *name — описание задачи cron
• *job — команда, которую нужно выполнить в задаче cron
• *schedule — формат стандартной задачи cron для каждого воскресенья в полночь
• *cron_file записывает файл cron в /etc/cron.d, а не в индивидуальный crontab пользователя
• user по умолчанию равен первому пользователю из docker__users или root, если его нет
• state по умолчанию равен "present", когда "absent", файл cron будет удален

Настройка менеджера пакетов APT

Docker требует установки нескольких зависимостей для своей работы. Вам не нужно редактировать ни одну из этих переменных.

# Список пакетов для установки.
docker__package_dependencies:
  - "apt-transport-https"
  - "ca-certificates"
  - "cron"
  - "gnupg2"
  - "software-properties-common"

# Ansible определяет архитектуры ЦП иначе, чем Docker.
docker__architecture_map:
  "x86_64": "amd64"
  "aarch64": "arm64"
  "aarch": "arm64"
  "armhf": "armhf"
  "armv7l": "armhf"

# URL GPG-ключа Docker.
docker__apt_repository_url: "https://download.docker.com/linux/{{ ansible_distribution | lower }}"

# Контрольное значение GPG-ключа Docker.
docker__apt_key_checksum: "sha256:1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570"

# Исходный APT-репозиторий Docker.
docker__apt_repository: >
  deb [arch={{ docker__architecture_map[ansible_architecture] }}
  signed-by=/etc/apt/keyrings/docker.asc]
  {{ docker__apt_repository_url }}
  {{ ansible_distribution_release }} {{ docker__channel | join(' ') }}

Установка Python-пакетов с помощью Virtualenv и PIP

Настройка Virtualenv

Чтобы не загрязнять версию Python на вашем сервере, все пакеты PIP устанавливаются в Virtualenv по вашему выбору.

docker__pip_virtualenv: "/usr/local/lib/docker/virtualenv"

Установка PIP и его зависимостей

Эта роль устанавливает PIP, потому что Docker Compose v1 устанавливается с помощью пакета docker-compose из PIP, а модули Ansible docker_* используют пакет docker из PIP.

docker__pip_dependencies:
  - "gcc"
  - "python3-setuptools"
  - "python3-dev"
  - "python3-pip"
  - "virtualenv"

Установка пакетов PIP

docker__default_pip_packages:
  - name: "docker"
    state: "{{ docker__pip_docker_state }}"
  - name: "docker-compose"
    version: "{{ docker__compose_version }}"
    path: "/usr/local/bin/docker-compose"
    src: "{{ docker__pip_virtualenv + '/bin/docker-compose' }}"
    state: "{{ docker__pip_docker_compose_state }}"

# Добавьте свои пакеты PIP с теми же свойствами, что и выше.
docker__pip_packages: []

Свойства, начинающиеся с *, обязательны для заполнения.

• *name — название пакета
• version — версия пакета для установки (или "" если это не задано)
• path — целевой путь для символической ссылки
• src — исходный путь для символической ссылки
• state по умолчанию равен "present", другие значения могут быть "forcereinstall" или "absent"

Состояние пакета PIP

• При установке "present" пакет будет установлен, но не обновлен при будущих записях.
• При установке "forcereinstall" пакет всегда будет (пере)устанавливаться и обновляться при будущих записях.
• При установке "absent" пакет пропускается или удаляется.

docker__pip_docker_state: "present"
docker__pip_docker_compose_state: "absent"

Работа с модулями Ansible docker_*

Эта роль использует docker_login для входа в реестр Docker, но вы также можете использовать другие модули docker_* в своих собственных ролях. Они не будут работать, если вы не укажете Ansible использовать Virtualenv этой роли.

На уровне инвентаря, плейбука или задачи вам нужно установить ansible_python_interpreter: "/usr/local/bin/python3-docker". Это работает потому, что эта роль создает прокси-скрипт из бинарного файла Python Virtualenv в python3-docker.

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

Лицензия

MIT