community.docker.docker_volume 模块 – 管理 Docker 卷

注意

此模块是 community.docker 集合 (版本 4.1.0) 的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install community.docker。您需要进一步的要求才能使用此模块，请参阅 要求 了解详细信息。

要在 playbook 中使用它，请指定： community.docker.docker_volume。

概要

  • 创建/删除 Docker 卷。

  • 执行的功能与 docker volume CLI 子命令基本相同。

要求

在执行此模块的主机上需要以下要求。

  • Docker API >= 1.25

  • backports.ssl_match_hostname (在 Python 2 上使用 TLS 时)

  • paramiko (当使用 SSH 时，且 use_ssh_client=false)

  • pyOpenSSL (使用 TLS 时)

  • pywin32 (在 Windows 32 上使用命名管道时)

  • requests

参数

参数

注释

api_version

别名: docker_api_version

字符串

Docker 主机上运行的 Docker API 的版本。

默认为此集合和 docker 守护程序支持的最新 API 版本。

如果未在任务中指定该值，则将使用环境变量 DOCKER_API_VERSION 的值。如果未设置环境变量，则将使用默认值。

默认: "auto"

ca_path

别名: ca_cert, tls_ca_cert, cacert_path

路径

通过提供 CA 证书文件的路径，在执行服务器验证时使用 CA 证书。

如果未在任务中指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定的目录中的文件 ca.pem。

此选项曾被称为 ca_cert，并在 community.docker 3.6.0 中重命名为 ca_path。旧名称已添加为别名，仍然可以使用。

client_cert

别名: tls_client_cert, cert_path

路径

客户端 TLS 证书文件的路径。

如果未在任务中指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定的目录中的文件 cert.pem。

client_key

别名: tls_client_key, key_path

路径

客户端 TLS 密钥文件的路径。

如果未在任务中指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定的目录中的文件 key.pem。

debug

布尔值

调试模式

选项

  • false ← (默认)

  • true

docker_host

别名: docker_url

字符串

用于连接 Docker API 的 URL 或 Unix 套接字路径。要连接到远程主机，请提供 TCP 连接字符串。例如，tcp://192.0.2.23:2376。如果使用 TLS 加密连接，模块将自动将连接 URL 中的 tcp 替换为 https。

如果任务中未指定该值，则将使用环境变量 DOCKER_HOST 的值。如果未设置环境变量，则将使用默认值。

默认值： "unix:///var/run/docker.sock"

driver

字符串

指定卷的类型。Docker 提供了 local 驱动程序，但也可以使用第三方驱动程序。

默认值： "local"

driver_options

字典

卷设置的字典。有关有效选项和值，请参阅 Docker 文档：https://docs.dockerd.com.cn/engine/reference/commandline/volume_create/#driver-specific-options。

默认值： {}

labels

字典

要为卷设置的标签键/值字典

recreate

字符串

控制何时在 state=present 时重新创建卷。请注意，重新创建现有卷将导致现有卷中的任何数据丢失！ 卷将被删除，并创建一个同名的新卷。

值 always 强制始终重新创建卷。

值 never 确保不会重新创建卷。

值 options-changed 确保在卷已存在且驱动程序、驱动程序选项或标签不同时重新创建卷。

选项

  • "always"

  • "never" ← (默认)

  • "options-changed"

state

字符串

absent 删除卷。

present 创建卷（如果它尚不存在）。

选项

  • "absent"

  • "present" ← (默认)

timeout

整数

等待 API 响应的最长时间（以秒为单位）。

如果任务中未指定该值，则将使用环境变量 DOCKER_TIMEOUT 的值。如果未设置环境变量，则将使用默认值。

默认值： 60

tls

布尔值

通过使用 TLS 而不验证 Docker 主机服务器的真实性来保护与 API 的连接。请注意，如果还将 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

别名：tls_verify

布尔值

通过使用 TLS 并验证 Docker 主机服务器的真实性来保护与 API 的连接。

如果任务中未指定该值，则将使用环境变量 DOCKER_TLS_VERIFY 的值。如果未设置环境变量，则将使用默认值。

选项

  • false ← (默认)

  • true

volume_name

别名：name

字符串 / 必需

要操作的卷的名称。

属性

属性

支持

描述

action_group

操作组： community.docker.docker，docker

在 module_defaults 中使用 group/docker 或 group/community.docker.docker 为此模块设置默认值。

check_mode

支持： 完整

可以在 check_mode 中运行，并返回更改的状态预测，而无需修改目标。

diff_mode

支持： 完整

在 diff 模式下，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

说明

注意

示例

- name: Create a volume
  community.docker.docker_volume:
    name: volume_one

- name: Remove a volume
  community.docker.docker_volume:
    name: volume_one
    state: absent

- name: Create a volume with options
  community.docker.docker_volume:
    name: volume_two
    driver_options:
      type: btrfs
      device: /dev/sda2

返回值

常用返回值记录在此处，以下是此模块独有的字段

键

描述

volume

字典

受影响卷的卷检查结果。

返回：成功

示例： {}

作者

  • Alex Grönholm (@agronholm)