Модуль community.docker.docker_image — Управление образами Docker

Примечание

Этот модуль входит в коллекцию community.docker (версия 5.2.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.docker. Для использования этого модуля требуются дополнительные компоненты; подробности см. в разделе Требования.

Чтобы использовать этот модуль в сценарии, укажите: community.docker.docker_image.

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Собирает, загружает или извлекает образ, делая его доступным для создания контейнеров. Также поддерживает присвоение образу тега, отправку образа и архивацию образа в файл .tar.
Рекомендуем вместо этого модуля использовать отдельные модули community.docker.docker_image_build, community.docker.docker_image_export, community.docker.docker_image_load, community.docker.docker_image_pull, community.docker.docker_image_push, community.docker.docker_image_remove и community.docker.docker_image_tag.

Требования

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

Docker API >= 1.25
paramiko (при использовании SSH с use_ssh_client=false)
pyOpenSSL (при использовании TLS)
pywin32 (при использовании именованных каналов в Windows 32)
requests

Параметры

Параметр	Комментарии
api_version aliases: docker_api_version string	Версия API Docker, используемая на узле Docker. По умолчанию используется последняя версия API, поддерживаемая этой коллекцией и демоном Docker. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_API_VERSION`. Если переменная окружения не задана, будет использоваться значение по умолчанию. По умолчанию: `"auto"`
archive_path path	Используется с `state=present` для сохранения образа в файл `.tar`.
build dictionary	Задает параметры, используемые для сборки образов.
args dictionary	Передает словарь аргументов сборки `key:value`, соответствующих директиве ARG в Dockerfile. Docker ожидает строковое значение. Для удобства любые значения, не являющиеся строками, будут преобразованы в строки.
cache_from list / elements=string	Список имен образов, которые следует рассматривать в качестве источника кэша.
container_limits dictionary	Словарь ограничений, применяемых к каждому контейнеру, созданному в процессе сборки.
cpusetcpus string	Процессоры, на которых разрешено выполнение. Например, `0-3` или `0,1`.
cpushares integer	Доли процессора (относительный вес).
memory string	Ограничение памяти для сборки в формате `<number>[<unit>]`. Число должно быть положительным целым числом. Единицей измерения может быть `B` (байт), `K` (кибибайт, 1024 Б), `M` (мебибайт), `G` (гибибайт), `T` (тебибайт) или `P` (пебибайт). Если единица измерения не указана, по умолчанию используются байты. До community.docker 3.6.0 единицы измерения не допускались.
memswap string	Общее ограничение памяти (память + подкачка) для сборки в формате `<number>[<unit>]` или специальные значения `unlimited` и `-1`, означающие неограниченное использование подкачки. Число должно быть положительным целым числом. Единицей измерения может быть `B` (байт), `K` (кибибайт, 1024 Б), `M` (мебибайт), `G` (гибибайт), `T` (тебибайт) или `P` (пебибайт). Если единица измерения не указана, по умолчанию используются байты. До community.docker 3.6.0 единицы измерения не допускались, как и специальное значение `unlimited`.
dockerfile string	Используется с `state=present` и `source=build` для указания альтернативного имени Dockerfile, который будет использоваться при сборке образа. Здесь также можно указать относительный путь (относительно `build.path`).
etc_hosts dictionary	Дополнительные узлы, добавляемые в `/etc/hosts` при сборке контейнеров, в виде сопоставления имени узла с IP-адресом. Вместо IP-адреса можно также использовать специальное значение `host-gateway`, которое разрешается в IP-адрес шлюза узла и позволяет собираемым контейнерам подключаться к службам, работающим на узле.
http_timeout integer	Тайм-аут HTTP-запросов во время сборки образа. Укажите положительное целое число секунд.
labels dictionary добавлено в community.docker 3.6.0	Словарь пар ключ-значение.
network string	Сеть, используемая для инструкций сборки `RUN`.
nocache boolean	Не использовать кэш при сборке образа. Варианты: `false` ← (по умолчанию) `true`
path path / обязательный	Используется со state «present» для сборки образа. Путь к каталогу, содержащему контекст и Dockerfile для сборки образа.
platform string добавлено в community.docker 1.1.0	Платформа в формате `os[/arch[/variant]]`.
pull boolean	При сборке образа загружать все обновления образа FROM, указанного в Dockerfile. Варианты: `false` ← (по умолчанию) `true`
rm boolean	Удалять промежуточные контейнеры после сборки. Варианты: `false` `true` ← (по умолчанию)
shm_size string добавлено в community.docker 3.6.0	Размер `/dev/shm` в формате `<number>[<unit>]`. Число должно быть положительным целым числом. Единицей измерения может быть `B` (байт), `K` (кибибайт, 1024 Б), `M` (мебибайт), `G` (гибибайт), `T` (тебибайт) или `P` (пебибайт). Если единица измерения не указана, по умолчанию используются байты. Если размер не указан, демон Docker использует `64M`.
target string	При сборке образа задает по имени промежуточный этап сборки, который будет последним этапом результирующего образа.
use_config_proxy boolean	Если установлено значение `true` и в конфигурации клиента Docker указаны настройки прокси (по умолчанию `$HOME/.docker/config.json`), соответствующие переменные окружения будут заданы в собираемом контейнере. Варианты: `false` `true`
ca_path aliases: ca_cert, tls_ca_cert, cacert_path path	Для проверки подлинности сервера используйте сертификат CA, указав путь к его файлу. Если значение не указано в задаче, а переменная окружения `DOCKER_CERT_PATH` задана, будет использован файл `ca.pem` из каталога, указанного в переменной окружения `DOCKER_CERT_PATH`. Ранее этот параметр назывался `ca_cert`; в community.docker 3.6.0 он был переименован в `ca_path`. Старое имя добавлено как псевдоним и по-прежнему может использоваться.
client_cert aliases: tls_client_cert, cert_path path	Путь к файлу TLS-сертификата клиента. Если значение не указано в задаче, а переменная окружения `DOCKER_CERT_PATH` задана, будет использован файл `cert.pem` из каталога, указанного в переменной окружения `DOCKER_CERT_PATH`.
client_key aliases: tls_client_key, key_path path	Путь к файлу TLS-ключа клиента. Если значение не указано в задаче, а переменная окружения `DOCKER_CERT_PATH` задана, будет использован файл `key.pem` из каталога, указанного в переменной окружения `DOCKER_CERT_PATH`.
debug boolean	Режим отладки Варианты: `false` ← (по умолчанию) `true`
docker_host aliases: docker_url string	URL или путь к сокету Unix, используемый для подключения к API Docker. Для подключения к удаленному узлу укажите строку TCP-подключения. Например, `tcp://192.0.2.23:2376`. Если для шифрования подключения используется TLS, модуль автоматически заменит `tcp` в URL подключения на `https`. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_HOST`. Если переменная окружения не задана, будет использоваться значение по умолчанию. По умолчанию: `"unix:///var/run/docker.sock"`
force_absent boolean	Используется с `state=absent` для снятия тегов и удаления всех образов, соответствующих указанному имени. Варианты: `false` ← (по умолчанию) `true`
force_source boolean	Используется с `state=present` для сборки, загрузки или получения образа (в зависимости от значения параметра `source`), если образ уже существует. Варианты: `false` ← (по умолчанию) `true`
force_tag boolean	Используется с `state=present` для принудительного присвоения образу тега. Варианты: `false` ← (по умолчанию) `true`
load_path path	Используется с `state=present` для загрузки образа из файла `.tar`. Установите `source=load`, если хотите загрузить образ.
name string / обязательный	Имя образа. Формат имени должен быть одним из следующих: `name`, `repository/name`, `registry_server:port/name`. При отправке или получении образа к имени можно добавить тег, дописав `:tag_name`. Обратите внимание, что идентификаторы образов (хеши) поддерживаются только для `state=absent`, для `state=present` с `source=load` и для `state=present` с `source=local`.
pull dictionary добавлено в community.docker 1.3.0	Задает параметры, используемые для получения образов.
platform string	При получении образа запросить именно эту платформу. Обратите внимание, что это значение не используется для определения необходимости получения образа. Однако в будущем это может измениться в одном из минорных выпусков.
push boolean	Отправить образ в реестр. Укажите реестр в параметре `name` или `repository`. Варианты: `false` ← (по умолчанию) `true`
repository string	Используется с `state=present` для присвоения образу тега. Ожидается формат `repository:tag`. Если тег не указан, будет использовано значение параметра `tag` или `latest`. Если `push=true`, `repository` должен содержать реестр, иначе предполагается, что он относится к реестру по умолчанию (Docker Hub).
source string	Определяет источник, из которого модуль будет пытаться получить образ. Используйте `build` для сборки образа из `Dockerfile`. При использовании этого значения необходимо указать `build.path`. Используйте `load` для загрузки образа из файла `.tar`. При использовании этого значения необходимо указать `load_path`. Используйте `pull` для получения образа из реестра. Используйте `local`, чтобы убедиться, что образ уже доступен в локальном демоне Docker. В этом случае модуль не будет пытаться собрать, получить или загрузить образ. Варианты: `"build"` `"load"` `"pull"` `"local"`
state string	Проверяет состояние образа. Если задано `absent`, образ будет удален. Используйте параметр force, чтобы снять теги и удалить все образы, соответствующие указанному имени. Если задано `present`, проверяется наличие образа с указанными именем и тегом. Если образ не найден или используется параметр force, образ будет получен, собран или загружен в зависимости от значения параметра `source`. Варианты: `"absent"` `"present"` ← (по умолчанию)
tag string	Используется для выбора образа при получении. Будет добавлен к образу при отправке, присвоении тега или сборке. По умолчанию используется `latest`. Если формат параметра `name` — `name:tag`, приоритет будет иметь значение тега из `name`. По умолчанию: `"latest"`
timeout integer	Максимальное время ожидания ответа API в секундах. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TIMEOUT`. Если переменная окружения не задана, будет использоваться значение по умолчанию. По умолчанию: `60`
tls boolean	Защитить подключение к API с помощью TLS, не проверяя подлинность сервера узла Docker. Обратите внимание: если для `validate_certs` также задано значение `true`, этот параметр имеет приоритет. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TLS`. Если переменная окружения не задана, будет использоваться значение по умолчанию. Варианты: `false` ← (по умолчанию) `true`
tls_hostname string	При проверке подлинности сервера узла Docker укажите ожидаемое имя сервера. Если значение не указано в задаче, вместо него будет использоваться значение переменной окружения `DOCKER_TLS_HOSTNAME`. Если переменная окружения не задана, будет использоваться значение по умолчанию. Обратите внимание, что в старых версиях для этого параметра использовалось значение по умолчанию `localhost`. Оно было удалено в community.docker 3.0.0.

use_ssh_client

boolean

добавлено в community.docker 1.5.0

Для SSH-транспорта используйте инструмент CLI ssh вместо paramiko.

Варианты:

false ← (по умолчанию)
true

validate_certs

псевдонимы: tls_verify

boolean

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

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

Варианты:

false ← (по умолчанию)
true

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группы действий: community.docker.docker, docker	Используйте `group/docker` или `group/community.docker.docker` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: частичная При попытке получить образ модуль в режиме проверки всегда считает, что состояние изменилось.	Может работать в `check_mode` и возвращать прогноз изменения состояния, не изменяя целевой объект.
diff_mode	Поддержка: отсутствует	В режиме diff возвращает сведения об изменениях (или о том, что, возможно, нужно изменить в `check_mode`).
idempotent	Поддержка: частичная Идемпотентность модуля зависит от конкретных параметров, в частности от `force_source` и `force_tag`.	При повторном запуске с теми же аргументами вне режима проверки второй вызов сообщает, что изменений нет. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.

Примечания

Примечание

Сборка образов выполняется с использованием API демона Docker. Таким способом нельзя использовать BuildKit / buildx. Для сборки образов с помощью BuildKit используйте community.docker.docker_image_build.
Экспорт образов, как правило, не является идемпотентным. Это зависит от того, совпадает ли идентификатор образа с идентификаторами, указанными в manifest.json созданного tar-архива. Так было при использовании серверной части хранилища по умолчанию вплоть до Docker 28, но, похоже, в Docker 29 это изменилось.
Подключайтесь к демону Docker, указывая параметры в каждой задаче или задавая переменные окружения. Можно задать DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS, DOCKER_TLS_VERIFY и DOCKER_TIMEOUT. Если вы используете docker machine, запустите поставляемый с продуктом скрипт, который настраивает окружение. Он задаст эти переменные. Подробнее см. на странице https://docs.docker.com/machine/reference/env/.
Этот модуль не использует Docker SDK for Python для взаимодействия с демоном Docker. Он использует код, производный от Docker SDK или Python, включённый в эту коллекцию.

См. также

community.docker.docker_image_build: Сборка образов Docker с помощью Docker buildx.
community.docker.docker_image_export: Экспорт (архивирование) образов Docker.
community.docker.docker_image_info: Проверка образов Docker.
community.docker.docker_image_load: Загрузка образов Docker из архивов.
community.docker.docker_image_pull: Получение образов Docker из реестров.
community.docker.docker_image_push: Отправка образов Docker в реестры.
community.docker.docker_image_remove: Удаление образов Docker.
community.docker.docker_image_tag: Назначение образам Docker новых имён и/или тегов.

Примеры

---
- name: Pull an image
  community.docker.docker_image:
    name: pacur/centos-7
    source: pull
  # Select platform for pulling. If not specified, will pull whatever docker prefers.
    pull:
      platform: amd64

- name: Tag and push to docker hub
  community.docker.docker_image:
    name: pacur/centos-7:56
    repository: dcoppenhagan/myimage:7.56
    push: true
    source: local

- name: Tag and push to local registry
  community.docker.docker_image:
  # Image will be centos:7
    name: centos
  # Will be pushed to localhost:5000/centos:7
    repository: localhost:5000/centos
    tag: 7
    push: true
    source: local

- name: Add tag latest to image
  community.docker.docker_image:
    name: myimage:7.1.2
    repository: myimage:latest
  # As 'latest' usually already is present, we need to enable overwriting of existing tags:
    force_tag: true
    source: local

- name: Remove image
  community.docker.docker_image:
    state: absent
    name: registry.ansible.com/chouseknecht/sinatra
    tag: v1

- name: Build an image and push it to a private repo
  community.docker.docker_image:
    build:
      path: ./sinatra
    name: registry.ansible.com/chouseknecht/sinatra
    tag: v1
    push: true
    source: build

- name: Archive image
  community.docker.docker_image:
    name: registry.ansible.com/chouseknecht/sinatra
    tag: v1
    archive_path: my_sinatra.tar
    source: local

- name: Load image from archive and push to a private registry
  community.docker.docker_image:
    name: localhost:5000/myimages/sinatra
    tag: v1
    push: true
    load_path: my_sinatra.tar
    source: load

- name: Build image and with build args
  community.docker.docker_image:
    name: myimage
    build:
      path: /path/to/build/dir
      args:
        log_volume: /var/log/myapp
        listen_port: 8080
    source: build

- name: Build image using cache source
  community.docker.docker_image:
    name: myimage:latest
    build:
      path: /path/to/build/dir
    # Use as cache source for building myimage
      cache_from:
        - nginx:latest
        - alpine:3.8
    source: build

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
image словарь	Результаты проверки затронутого образа. Возвращается: при успешном выполнении Пример: `{}`
stdout строка добавлено в community.docker 1.0.0	Вывод сборки Docker при создании образа. Возвращается: при успешном выполнении Пример: `""`

Авторы

Pavel Antonov (@softzilla)
Chris Houseknecht (@chouseknecht)
Sorin Sbarnea (@ssbarnea)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/docker/docker_image_module.html