community.docker.docker_swarm 模块 – 管理 Swarm 集群

注意

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

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

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

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

概要

• 创建一个新的 Swarm 集群。

• 向现有集群添加/删除节点或管理器。

要求

执行此模块的主机需要满足以下要求。

• Docker API >= 1.25

• Docker SDK for Python：请注意，docker-py Python 模块已被 docker 取代（有关详细信息，请参见 此处）。请注意，这两个模块*不应*同时安装。另请注意，当两个模块都已安装并且其中一个被卸载时，另一个可能不再起作用，并且需要重新安装它。

• Docker SDK for Python >= 1.10.0

参数

参数	注释
advertise_addr 字符串	外部可访问的地址，向其他节点广播。 这可以是 192.168.1.1:4567 形式的地址/端口组合，也可以是接口后跟端口号，例如 eth0:4567。 如果省略端口号，则使用侦听地址中的端口号。 如果未指定 advertise_addr，则在可能的情况下会自动检测到。 仅在初始化或加入 swarm 时使用。因此，不考虑进行幂等性检查。
api_version 别名：docker_api_version 字符串	在 Docker 主机上运行的 Docker API 版本。 默认为 Docker SDK for Python 和 docker 守护进程支持的最新版本的 API。 如果未在任务中指定该值，则将使用环境变量 DOCKER_API_VERSION 的值。如果未设置环境变量，则将使用默认值。 默认值： "auto"
autolock_managers 布尔值	如果设置，则生成一个密钥并使用它来锁定存储在管理器上的数据。 Docker 默认值为 false。 community.docker.docker_swarm_info 可用于检索解锁密钥。 选择 false true
ca_force_rotate 整数	一个整数，其目的是强制 swarm 生成新的签名 CA 证书和密钥（如果未指定）。 Docker 默认值为 0。 需要 API 版本 >= 1.30。
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。
data_path_addr 字符串 在 community.docker 2.5.0 中添加	用于数据路径流量的地址或接口。 这可以是一个形如 192.168.1.1 的地址，也可以是一个接口，如 eth0。 仅在初始化或加入 swarm 时使用。因此，不考虑其幂等性检查。 需要 API 版本 >= 1.30。
data_path_port 整数 在 community.docker 3.1.0 中添加	用于数据路径流量的端口。 这需要是一个端口号，如 9789。 仅在初始化 swarm 时使用。因此，不考虑其幂等性检查。 需要 API 版本 >= 1.40。
debug 布尔值	调试模式 选择 false ← (默认) true
default_addr_pool list / elements=string	CIDR 格式的默认地址池。 仅在初始化 swarm 时使用。因此，不考虑其幂等性检查。 需要 API 版本 >= 1.39。
dispatcher_heartbeat_period 整数	代理向调度器发送心跳的延迟（以纳秒为单位）。 Docker 默认值为 5 秒，对应的值为 5000000000。
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"
election_tick 整数	在没有领导者的情况下触发新选举所需的 ticks 数（以秒为单位）。 Docker 默认值为 10 秒。
force 布尔值	与状态 present 一起使用，以强制创建新的 Swarm，即使已经是一个 Swarm 的一部分。 与状态 absent 一起使用，即使此节点是管理器，也要离开 swarm。 选择 false ← (默认) true
heartbeat_tick 整数	每次心跳之间的 ticks 数（以秒为单位）。 Docker 默认值为 1 秒。
join_token 字符串	用于加入 swarm 集群的 Swarm 令牌。 与 state=join 一起使用。 如果指定此值，则 Ansible 将审查返回值中的相应值。这是由于该值未被记录的副作用。
keep_old_snapshots 整数	要保留的快照数量，超出当前快照。 Docker 默认值为 0。
labels 字典	用户定义的键/值元数据。 此模块中的标签操作应用于 docker swarm 集群。使用 community.docker.docker_node 模块添加/修改/删除 swarm 节点标签。 需要 API 版本 >= 1.32。
listen_addr 字符串	用于管理器间通信的监听地址。 这可以是 192.168.1.1:4567 形式的地址/端口组合，也可以是接口后跟端口号，例如 eth0:4567。 如果省略端口号，则使用默认的 swarm 监听端口。 仅在初始化或加入 swarm 时使用。因此，不考虑进行幂等性检查。 默认值: "0.0.0.0:2377"
log_entries_for_slow_followers 整数	在创建快照后，要保留的日志条目数量，以便同步慢速追随者。
name 字符串	swarm 的名称。
node_cert_expiry 整数	节点证书的自动过期时间，以纳秒为单位。 Docker 默认值为 90 天，对应的值为 7776000000000000。
node_id 字符串	要删除的节点的 Swarm ID。 与 state=remove 一起使用。
remote_addrs list / elements=string	要连接的现有 Swarm 的一个或多个管理器节点的远程地址。 与 state=join 一起使用。
rotate_manager_token 布尔值	轮换管理器加入令牌。 选择 false ← (默认) true
rotate_worker_token 布尔值	轮换工作节点加入令牌。 选择 false ← (默认) true
signing_ca_cert 字符串	所有 swarm 节点 TLS 叶证书所需的签名 CA 证书，采用 PEM 格式。 这必须不是证书的路径，而是证书的内容。 需要 API 版本 >= 1.30。
signing_ca_key 字符串	所有 swarm 节点 TLS 叶证书所需的签名 CA 密钥，采用 PEM 格式。 这必须不是密钥的路径，而是密钥的内容。 需要 API 版本 >= 1.30。
snapshot_interval 整数	快照之间的日志条目数。 Docker 默认值为 10000。
state 字符串	设置为 present，以创建/更新新的集群。 设置为 join，以加入现有的集群。 设置为 absent，以离开现有的集群。 设置为 remove，以从集群中删除一个不存在的节点。请注意，删除需要 Docker SDK for Python >= 2.4.0。 community.docker.docker_node 可用于在删除前降级管理器。 选择 "present" ← (默认) "join" "absent" "remove"
subnet_size 整数	默认地址池子网掩码长度。 仅在初始化 swarm 时使用。因此，不考虑其幂等性检查。 需要 API 版本 >= 1.39。
task_history_retention_limit 整数	存储的最大任务历史记录数。 Docker 默认值为 5。
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 中被删除。 注意：对于 Docker SDK for Python 7.0.0+，不再支持此选项。使用 Docker SDK for Python 7.0.0 或更高版本指定它会导致错误。
use_ssh_client 布尔值 在 community.docker 1.5.0 中添加	对于 SSH 传输，使用 ssh CLI 工具而不是 paramiko。 需要 Docker SDK for Python 4.4.0 或更高版本。 选择 false ← (默认) true
validate_certs 别名: tls_verify 布尔值	通过使用 TLS 并验证 Docker 主机服务器的真实性来保护与 API 的连接。 如果任务中未指定该值，则将使用环境变量 DOCKER_TLS_VERIFY 的值。如果未设置环境变量，则将使用默认值。 选择 false ← (默认) true

属性

属性	支持	描述
action_group	操作组: community.docker.docker, docker	在 module_defaults 中使用 group/docker 或 group/community.docker.docker 来为此模块设置默认值。
check_mode	支持: 完整	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标。
diff_mode	支持: 完整	当处于 diff 模式时，将返回有关已更改（或可能需要在 check_mode 中更改）的详细信息。

注释

注意

• 可以通过在每个任务中提供参数或定义环境变量来连接 Docker 守护进程。您可以定义 DOCKER_HOST、 DOCKER_TLS_HOSTNAME、 DOCKER_API_VERSION、 DOCKER_CERT_PATH、 DOCKER_TLS、 DOCKER_TLS_VERIFY 和 DOCKER_TIMEOUT。如果您正在使用 docker machine，请运行产品附带的脚本来设置环境。它会为您设置这些变量。有关更多详细信息，请参阅 https://docs.dockerd.com.cn/machine/reference/env/。

• 当使用 TLS 连接到 Docker 守护进程时，您可能需要安装额外的 Python 包。对于 Docker SDK for Python，版本 2.4 或更高版本，可以通过使用 ansible.builtin.pip 安装 docker[tls] 来完成。

• 请注意，Docker SDK for Python 仅允许为极少数函数指定 Docker 配置的路径。一般来说，如果未指定 DOCKER_CONFIG 环境变量，它将使用 $HOME/.docker/config.json，否则使用 $DOCKER_CONFIG/config.json。

• 此模块使用 Docker SDK for Python 与 Docker 守护进程通信。

示例

- name: Init a new swarm with default parameters
  community.docker.docker_swarm:
    state: present

- name: Update swarm configuration
  community.docker.docker_swarm:
    state: present
    election_tick: 5

- name: Add nodes
  community.docker.docker_swarm:
    state: join
    advertise_addr: 192.168.1.2
    join_token: SWMTKN-1--xxxxx
    remote_addrs: [ '192.168.1.1:2377' ]

- name: Leave swarm for a node
  community.docker.docker_swarm:
    state: absent

- name: Remove a swarm manager
  community.docker.docker_swarm:
    state: absent
    force: true

- name: Remove node from swarm
  community.docker.docker_swarm:
    state: remove
    node_id: mynode

- name: Init a new swarm with different data path interface
  community.docker.docker_swarm:
    state: present
    advertise_addr: eth0
    data_path_addr: ens10

- name: Init a new swarm with a different data path port
  community.docker.docker_swarm:
    state: present
    data_path_port: 9789

返回值

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

键	描述
actions list / elements=string	提供在 swarm 上执行的操作。 返回： 当操作失败时。 示例： ["此集群已是swarm集群"]
swarm_facts 字典	有关 swarm 的信息。 返回： 成功
JoinTokens 字典	用于连接到 Swarm 的令牌。 返回： 成功
Manager 字符串	以新的 *manager* 节点身份加入集群的令牌。 注意： 如果此值已指定为 join_token，则此处的值将不是令牌，而是 VALUE_SPECIFIED_IN_NO_LOG_PARAMETER。如果您传递 join_token，请确保您的 playbook/角色不依赖于此返回值！ 返回： 成功 示例： "SWMTKN-1--xxxxx"
Worker 字符串	以新的 *worker* 节点身份加入集群的令牌。 注意： 如果此值已指定为 join_token，则此处的值将不是令牌，而是 VALUE_SPECIFIED_IN_NO_LOG_PARAMETER。如果您传递 join_token，请确保您的 playbook/角色不依赖于此返回值！ 返回： 成功 示例： "SWMTKN-1--xxxxx"
UnlockKey 字符串	如果 autolock_managers=true，则为 swarm 的解锁密钥。 返回： 如果 autolock_managers=true 且 swarm 已初始化，或如果 autolock_managers 已更改，则返回成功。 示例： "SWMKEY-1-xxx"

作者

• Thierry Bouvet (@tbouvet)

• Piotr Wojciechowski (@WojciechowskiPiotr)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助 (Docker)
• 寻求帮助 (Docker Compose)
• 寻求帮助 (Docker Swarm)
• 提交错误报告
• 请求功能
• 通信