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

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

• Python 的 Docker SDK >= 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 列表 / 元素=字符串	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 整数	在没有领导者的情况下触发新选举所需的滴答次数（以秒为单位）。 Docker 默认值为 10 秒。
force 布尔值	与状态 present 一起使用，即使已经加入 Swarm，也能强制创建新的 Swarm。 与状态 absent 一起使用，即使此节点是管理器，也能离开 Swarm。 选项 false ← (默认) true
heartbeat_tick 整数	每次心跳之间的滴答次数（以秒为单位）。 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 列表 / 元素=字符串	要连接到的现有 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 来保护与 API 的连接，而无需验证 Docker 主机服务器的真实性。请注意，如果 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	支持：完全支持	在差异模式下，将返回有关已更改内容（或在 check_mode 中可能需要更改的内容）的详细信息。

备注

注意

• 通过为每个任务提供参数或定义环境变量来连接到 Docker daemon。您可以定义 DOCKER_HOST、DOCKER_TLS_HOSTNAME、DOCKER_API_VERSION、DOCKER_CERT_PATH、DOCKER_TLS、DOCKER_TLS_VERIFY 和 DOCKER_TIMEOUT。如果您使用的是 docker machine，请运行产品附带的设置环境的脚本。它将为您设置这些变量。更多详情，请参见 https://docs.docker.net.cn/machine/reference/env/。

• 当使用 TLS 连接到 Docker daemon 时，您可能需要安装额外的 Python 包。对于 Python 版 Docker SDK 2.4 或更高版本，可以使用 ansible.builtin.pip 安装 docker[tls]。

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

• 此模块使用 Python 版 Docker SDK 与 Docker daemon 通信。

示例

- 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 列表 / 元素=字符串	提供在 swarm 上执行的操作。 返回值：操作失败时。 示例： ["This cluster is already a swarm cluster"]
swarm_facts 字典	关于 swarm 的信息。 返回值：成功
JoinTokens 字典	连接到 Swarm 的令牌。 返回值：成功
Manager 字符串	以新的 *manager* 节点加入集群的令牌。 注意：如果此值已指定为 join_token，则此处的值将不是令牌，而是 VALUE_SPECIFIED_IN_NO_LOG_PARAMETER。如果您传递 join_token，请确保您的 playbook/role 不依赖于此返回值！ 返回值：成功 示例： "SWMTKN-1--xxxxx"
Worker 字符串	以新的 *worker* 节点加入集群的令牌。 注意：如果此值已指定为 join_token，则此处的值将不是令牌，而是 VALUE_SPECIFIED_IN_NO_LOG_PARAMETER。如果您传递 join_token，请确保您的 playbook/role 不依赖于此返回值！ 返回值：成功 示例： "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)
• 提交错误报告
• 请求功能
• 沟通