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

Примечание

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

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

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

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

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

Описание

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

Требования

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

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

Параметры

Параметр	Комментарии
api_version aliases: docker_api_version string	Версия Docker API, работающего на Docker Host. По умолчанию используется последняя версия API, поддерживаемая этой коллекцией и демоном docker. Если значение не указано в задаче, вместо него будет использовано значение переменной среды `DOCKER_API_VERSION`. Если переменная среды не установлена, будет использовано значение по умолчанию. Default: `"auto"`
archive_path path	Используется с `state=present` для архивирования образа в файл `.tar`.
build dictionary	Указывает параметры, используемые для сборки образов.
args dictionary	Предоставьте словарь аргументов сборки `key:value`, которые соответствуют директиве Dockerfile ARG. Docker ожидает, что значение будет строкой. Для удобства любые нестроковые значения будут преобразованы в строки.
cache_from list / elements=string	Список имен образов, которые следует рассматривать как источник кэша.
container_limits dictionary	Словарь ограничений, применяемых к каждому контейнеру, созданному в процессе сборки.
cpusetcpus string	Процессоры, на которых разрешено выполнение. Например, `0-3` или `0,1`.
cpushares integer	Доля процессора (относительный вес).
memory string	Ограничение памяти для сборки в формате `<number>[<unit>]`. Число — положительное целое число. Единица измерения может быть `B` (байт), `K` (кибибайт, 1024B), `M` (мебибайт), `G` (гибибайт), `T` (тебибайт) или `P` (пебибайт). Без указания единицы измерения по умолчанию используются байты. До community.docker 3.6.0 единицы измерения не допускались.
memswap string	Общее ограничение памяти (память + своп) для сборки в формате `<number>[<unit>]`, или специальные значения `unlimited` или `-1` для неограниченного использования свопа. Число — положительное целое число. Единица измерения может быть `B` (байт), `K` (кибибайт, 1024B), `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 added in community.docker 3.6.0	Словарь пар «ключ-значение».
network string	Сеть, которая будет использоваться для инструкций сборки `RUN`.
nocache boolean	Не использовать кэш при сборке образа. Choices: `false` ← (default) `true`
path path / required	Используется с состоянием ‘present’ для сборки образа. Будет путем к каталогу, содержащему контекст и Dockerfile для сборки образа.
platform string added in community.docker 1.1.0	Платформа в формате `os[/arch[/variant]]`.
pull boolean	При сборке образа загружает любые обновления образа FROM в Dockerfile. Choices: `false` ← (default) `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	Использование сертификата центра сертификации при проверке сервера путем указания пути к файлу сертификата центра сертификации. Если значение не указано в задании, и переменная среды `DOCKER_CERT_PATH` установлена, будет использован файл `ca.pem` из каталога, указанного в переменной среды `DOCKER_CERT_PATH`. Этот параметр назывался `ca_cert` и был переименован в `ca_path` в community.docker 3.6.0. Старое имя добавлено в качестве псевдонима и по-прежнему может использоваться.
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 словарь добавлено в community.docker 1.3.0	Указывает параметры, используемые для загрузки изображений.
platform строка	При загрузке изображения запрашивается этот конкретный платформенный профиль. Обратите внимание, что это значение не используется для определения необходимости загрузки изображения. Возможно, это изменится в будущем в рамках мажорного выпуска.
push булево	Опубликовать изображение в реестре. Укажите реестр в параметре `name` или `repository`. Варианты: `false` ← (по умолчанию) `true`
repository строка	Используется с `state=present`, чтобы пометить изображение. Ожидается формат `repository:tag`. Если метка не указана, будет использовано значение параметра `tag` или `latest`. Если `push=true`, `repository` должен содержать реестр или будет предполагаться, что он относится к общедоступному реестру (Docker Hub).
source строка	Определяет, откуда модуль попытается извлечь изображение. Используйте `build`, чтобы собрать изображение из `Dockerfile`. `build.path` должно быть указано, когда используется это значение. Используйте `load`, чтобы загрузить изображение из файла `.tar`. `load_path` должно быть указано, когда используется это значение. Используйте `pull`, чтобы загрузить изображение из реестра. Используйте `local`, чтобы убедиться, что изображение уже доступно в локальном демоне Docker. Это означает, что модуль не пытается собрать, загрузить или загрузить изображение. Варианты: `"build"` `"load"` `"pull"` `"local"`
ssl_version строка	Укажите допустимый номер версии SSL. Значение по умолчанию определяется модулем SSL Python. Если значение не указано в задаче, будет использовано значение переменной окружения `DOCKER_SSL_VERSION`.
state строка	Утверждения о состоянии изображения. При значении `absent` изображение будет удалено. Используйте параметр force, чтобы удалить все изображения, соответствующие указанному имени. При значении `present` проверяется наличие изображения с указанным именем и меткой. Если изображение не найдено или используется параметр force, изображение будет загружено, собрано или загружено в зависимости от параметра `source`. Варианты: `"absent"` `"present"` ← (по умолчанию)
tag строка	Используется для выбора изображения при загрузке. Будет добавлен к изображению при публикации, маркировке или сборке. По умолчанию `latest`. Если формат параметра `name` - `name:tag`, тогда значение метки из `name` будет иметь приоритет. По умолчанию: `"latest"`
timeout целое число	Максимальное время ожидания ответа от API в секундах. Если значение не указано в задаче, будет использовано значение переменной окружения `DOCKER_TIMEOUT`. Если переменная окружения не задана, будет использовано значение по умолчанию. По умолчанию: `60`
tls булево	Защитить подключение к API с помощью TLS без проверки подлинности сервера Docker. Обратите внимание, что если `validate_certs` также установлено в `true`, оно будет иметь приоритет. Если значение не указано в задаче, будет использовано значение переменной окружения `DOCKER_TLS`. Варианты: `false` ← (по умолчанию) `true`
tls_hostname строка	При проверке подлинности сервера Docker укажите ожидаемое имя сервера. Если значение не указано в задаче, будет использовано значение переменной окружения `DOCKER_TLS_HOSTNAME`. Обратите внимание, что этот параметр имел значение по умолчанию `localhost` в более ранних версиях. Он был удалён в версии community.docker 3.0.0.
use_ssh_client булево добавлено в community.docker 1.5.0	Для SSH-транспортов используйте инструмент `ssh` CLI вместо paramiko. Варианты: `false` ← (по умолчанию) `true`
validate_certs aliases: tls_verify булево	Защитить подключение к 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	Поддержка: отсутствует	В режиме сравнения будет возвращена информация о том, что изменилось (или, возможно, нуждается в изменении в `check_mode`).

Примечания

Примечание

Создание изображений выполняется с помощью API демона Docker. Использование BuildKit / buildx таким образом невозможно. Используйте community.docker.docker_image_build для создания изображений с помощью BuildKit.
Подключение к демону Docker, предоставляя параметры с каждой задачей или определяя переменные окружения. Вы можете определить DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, 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 при создании изображения. Возвращаемое значение: успех Пример: `""`

Авторы

Павел Антонов (@softzilla)
Крис Хаускнехт (@chouseknecht)
Сорин Сбарнеа (@ssbarnea)

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

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