community.docker.docker_swarm_service 模块 – docker swarm 服务
注意
此模块是 community.docker 集合(版本 4.1.0)的一部分。
如果您正在使用 ansible
包,则可能已经安装了此集合。它不包含在 ansible-core
中。要检查是否已安装,请运行 ansible-galaxy collection list
。
要安装它,请使用:ansible-galaxy collection install community.docker
。您需要其他要求才能使用此模块,有关详细信息,请参阅要求。
要在 playbook 中使用它,请指定:community.docker.docker_swarm_service
。
概要
通过 swarm 管理器节点管理 docker 服务。
此模块不支持更新堆栈中的服务。
要求
执行此模块的主机上需要以下要求。
Docker API >= 1.25
Docker SDK for Python:请注意,docker-py Python 模块已被 docker 取代(有关详细信息,请参阅此处)。此模块 *不* 适用于 docker-py。
Docker SDK for Python >= 2.0.2
Python >= 2.7
参数
参数 |
注释 |
---|---|
在 Docker 主机上运行的 Docker API 的版本。 默认为 Docker SDK for Python 和 docker 守护程序支持的最新版本的 API。 如果未在任务中指定该值,则将使用环境变量 默认值: |
|
要传递给容器的参数列表。 对应于 |
|
通过提供 CA 证书文件的路径,在执行服务器验证时使用 CA 证书。 如果未在任务中指定该值,并且设置了环境变量 此选项之前称为 |
|
要添加到容器的功能列表。 需要 API 版本 >= 1.41。 |
|
要从容器中删除的功能列表。 需要 API 版本 >= 1.41。 |
|
客户端 TLS 证书文件的路径。 如果未在任务中指定该值,并且设置了环境变量 |
|
客户端 TLS 密钥文件的路径。 如果未在任务中指定该值,并且设置了环境变量 |
|
容器启动时要执行的命令。 命令可以是字符串、列表或字符串列表。 对应于 |
|
描述服务配置的字典列表。 对应于 需要 API 版本 >= 1.30。 |
|
配置的 ID。 |
|
配置在创建时定义的名称。 |
|
包含配置的文件名。如果未指定,则默认为 |
|
配置文件组的 GID。 |
|
容器内的文件访问模式。必须是八进制数(如 |
|
配置文件的所有者的 UID。 |
|
键值对字典。 对应于 |
|
调试模式 选项
|
|
自定义 DNS 服务器列表。 对应于 |
|
自定义 DNS 选项列表。 对应于 |
|
自定义 DNS 搜索域列表。 对应于 |
|
用于连接 Docker API 的 URL 或 Unix 套接字路径。 要连接到远程主机,请提供 TCP 连接字符串。 例如, 如果任务中未指定该值,则将使用环境变量 默认值: |
|
服务端点模式。 对应于 选项
|
|
服务环境变量的列表或字典。 如果传递列表,则每个项目都需要采用 如果传递字典,则 YAML 解析器可能会将值解析为数字、布尔值或其他类型,必须用引号引起来(例如 对应于 |
|
即使不需要更改,也强制更新。 对应于 选项
|
|
容器进程将作为其运行的附加组名称和/或 ID 的列表。 对应于 |
|
配置一个检查,该检查用于确定此服务的容器是否“健康”。有关健康检查如何工作的详细信息,请参阅 HEALTHCHECK Dockerfile 指令的文档。
|
|
运行检查的时间间隔。 |
|
报告不健康所需的连续失败次数。它接受整数值。 |
|
容器在开始健康重试倒计时之前进行初始化的开始时间。 |
|
用于检查健康的命令。 必须是字符串或列表。如果它是列表,则第一项必须是 |
|
允许运行一次检查的最大时间。 |
|
容器主机名。 对应于 |
|
主机到 IP 映射的字典,其中每个主机名是字典中的一个键。每个主机名都将添加到容器的 /etc/hosts 文件中。 对应于 |
|
服务镜像路径和标签。 对应于 |
|
在每个服务容器内使用 init 来转发信号和回收进程。 对应于 需要 API 版本 >= 1.37。 选项
|
|
键值对字典。 对应于 |
|
配置服务资源限制。 |
|
服务 CPU 限制。 对应于 |
|
服务内存限制,格式为
省略单位则默认为字节。 对应于 |
|
服务的日志记录配置。 |
|
配置服务的日志驱动程序。 对应于 |
|
服务日志驱动程序的选项。 对应于 |
|
服务复制模式。 更改时将删除并重新创建服务。 对应于 选项
|
|
描述服务挂载的字典列表。 对应于 |
|
卷驱动程序配置。 仅当 |
|
用于卷的卷驱动程序插件的名称。 |
|
作为键值对传递给此卷驱动程序的选项。 |
|
要应用的卷标签。 |
|
挂载是否应为只读。 选项
|
|
挂载源(例如,卷名或主机路径)。 如果 |
|
容器路径。 |
|
tmpfs 的文件模式,用八进制表示。 仅当 |
|
tmpfs 挂载的大小,格式为 仅当 |
|
挂载类型。 请注意, 选项
|
|
服务名称。 对应于 |
|
服务网络名称或字典的列表。 当传递字典时,有效的子选项为 在 API 版本 1.29 之前,不支持更新和删除网络。如果进行了更改,则将删除并重新创建服务。 对应于 |
|
配置服务放置首选项和约束。 |
|
服务约束列表。 对应于 |
|
作为键值对的放置首选项列表。 对应于 需要 API 版本 >= 1.27。 |
|
每个节点的最大任务数。 对应于 需要 API 版本 >= 1.40 |
|
描述服务发布的端口的字典列表。 对应于 |
|
要使用的发布模式。 需要 API 版本 >= 1.32。 选项
|
|
要使用的协议。 选项
|
|
要外部可用的端口。 |
|
容器内要公开的端口。 |
|
将容器的根文件系统挂载为只读。 对应于 选项
|
|
服务中实例化的容器数。仅当 如果设置为 如果设置为 对应于 默认值: |
|
配置服务资源预留。 |
|
服务 CPU 预留。 对应于 |
|
服务内存预留,格式为
省略单位则默认为字节。 对应于 |
|
是否应从注册表解析当前映像摘要,并在更改时更新。 需要 API 版本 >= 1.30。 选项
|
|
配置容器退出时是否以及如何重新启动。 |
|
服务的重新启动条件。 对应于 选项
|
|
两次重新启动之间的延迟。 接受格式类似于以下内容的字符串: 对应于 |
|
服务重新启动的最大次数。 对应于 |
|
重启策略评估窗口。 接受一个字符串,格式如下: 对应于 |
|
配置在更新失败时,服务应如何回滚。 |
|
任务回滚之间的延迟。 接受一个字符串,格式如下: 对应于 需要 API 版本 >= 1.28。 |
|
回滚失败时采取的动作。 对应于 需要 API 版本 >= 1.28。 选项
|
|
回滚期间可能失败的任务比例。 对应于 需要 API 版本 >= 1.28。 |
|
每次任务回滚后,监控失败的时间。 接受一个字符串,格式如下: 对应于 需要 API 版本 >= 1.28。 |
|
指定回滚期间操作的顺序。 对应于 需要 API 版本 >= 1.29。 |
|
一次回滚的容器数量。如果设置为 0,则所有容器同时回滚。 对应于 需要 API 版本 >= 1.28。 |
|
描述服务密钥的字典列表。 对应于 |
|
包含密钥的文件名。如果未指定,则默认为 对应于 |
|
密钥文件组的 GID。 |
|
容器内的文件访问模式。必须是八进制数(如 |
|
密钥的 ID。 |
|
密钥在其创建时定义的名称。 |
|
密钥文件所有者的 UID。 |
|
选项
|
|
强制杀死容器前等待的时间。 接受一个字符串形式的持续时间,格式如下: 对应于 |
|
覆盖用于停止容器的默认信号。 对应于 |
|
键值对的字典。 |
|
通过使用 TLS 而不验证 Docker 主机服务器的真实性来保护与 API 的连接。请注意,如果 如果任务中未指定该值,则将使用环境变量 选项
|
|
在验证 Docker 主机服务器的真实性时,提供服务器的预期名称。 如果任务中未指定该值,则将使用环境变量 请注意,此选项在较旧版本中的默认值为 注意: Docker SDK for Python 7.0.0+ 不再支持此选项。使用 Docker SDK for Python 7.0.0 或更高版本指定它会导致错误。 |
|
分配一个伪终端。 对应于 选项
|
|
配置服务应如何更新。对于配置滚动更新很有用。 |
|
滚动更新延迟。 接受一个字符串,格式如下: 对应于 |
|
容器发生故障时采取的措施。 对应于 使用 选项
|
|
在调用失败操作之前,更新期间可能失败的任务比例。 对应于 |
|
监控更新任务是否失败的时间。 接受一个字符串,格式如下: 对应于 |
|
指定推出更新任务时的操作顺序。 对应于 需要 API 版本 >= 1.29。 |
|
滚动更新并行度。 对应于 |
|
对于 SSH 传输,请使用 需要 Docker SDK for Python 4.4.0 或更高版本。 选项
|
|
设置用于指定命令的用户名或 UID。 在 Ansible 2.8 之前,此选项的默认值为 已删除默认值,以便在此处未指定用户时使用映像中定义的用户。 对应于 |
|
使用 TLS 并验证 Docker 主机服务器的真实性,以确保与 API 的连接安全。 如果任务中未指定该值,则将使用环境变量 选项
|
|
工作目录的路径。 对应于 |
属性
属性 |
支持 |
描述 |
---|---|---|
操作组: community.docker.docker, docker |
在 |
|
支持: 完全 |
可以在 |
|
支持: 完全 |
当处于差异模式时,将返回有关已更改内容(或可能需要在 |
说明
注意
当使用 Docker API >= 1.30 和 Docker SDK for Python >= 3.2.0 时,镜像只会解析为最新的摘要。当使用旧版本时,请使用
force_update=true
来触发 swarm 解析新镜像。通过为每个任务提供参数或定义环境变量来连接到 Docker 守护进程。您可以定义
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 守护进程时,您可能需要安装额外的 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: Set command and arguments
community.docker.docker_swarm_service:
name: myservice
image: alpine
command: sleep
args:
- "3600"
- name: Set a bind mount
community.docker.docker_swarm_service:
name: myservice
image: alpine
mounts:
- source: /tmp/
target: /remote_tmp/
type: bind
- name: Set service labels
community.docker.docker_swarm_service:
name: myservice
image: alpine
labels:
com.example.description: "Accounting webapp"
com.example.department: "Finance"
- name: Set environment variables
community.docker.docker_swarm_service:
name: myservice
image: alpine
env:
ENVVAR1: envvar1
ENVVAR2: envvar2
env_files:
- envs/common.env
- envs/apps/web.env
- name: Set fluentd logging
community.docker.docker_swarm_service:
name: myservice
image: alpine
logging:
driver: fluentd
options:
fluentd-address: "127.0.0.1:24224"
fluentd-async-connect: "true"
tag: myservice
- name: Set restart policies
community.docker.docker_swarm_service:
name: myservice
image: alpine
restart_config:
condition: on-failure
delay: 5s
max_attempts: 3
window: 120s
- name: Set update config
community.docker.docker_swarm_service:
name: myservice
image: alpine
update_config:
parallelism: 2
delay: 10s
order: stop-first
- name: Set rollback config
community.docker.docker_swarm_service:
name: myservice
image: alpine
update_config:
failure_action: rollback
rollback_config:
parallelism: 2
delay: 10s
order: stop-first
- name: Set placement preferences
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
placement:
preferences:
- spread: node.labels.mylabel
constraints:
- node.role == manager
- engine.labels.operatingsystem == ubuntu 14.04
replicas_max_per_node: 2
- name: Set configs
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
configs:
- config_name: myconfig_name
filename: "/tmp/config.txt"
- name: Set networks
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
networks:
- mynetwork
- name: Set networks as a dictionary
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
networks:
- name: "mynetwork"
aliases:
- "mynetwork_alias"
options:
foo: bar
- name: Set secrets
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
secrets:
- secret_name: mysecret_name
filename: "/run/secrets/secret.txt"
- name: Start service with healthcheck
community.docker.docker_swarm_service:
name: myservice
image: nginx:1.13
healthcheck:
# Check if nginx server is healthy by curl'ing the server.
# If this fails or timeouts, the healthcheck fails.
test: ["CMD", "curl", "--fail", "http://nginx.host.com"]
interval: 1m30s
timeout: 10s
retries: 3
start_period: 30s
- name: Configure service resources
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
reservations:
cpus: 0.25
memory: 20M
limits:
cpus: 0.50
memory: 50M
- name: Remove service
community.docker.docker_swarm_service:
name: myservice
state: absent
返回值
此处记录了常见的返回值:这里,以下是此模块独有的字段
键 |
描述 |
---|---|
如果服务已更改,则为已更改的服务属性列表,否则为 []。 返回: 始终 示例: |
|
如果服务已重新创建(删除并创建),则为 True 返回: 始终 示例: |
|
表示服务当前状态的变量字典。与模块参数格式匹配。 请注意,事实不是已注册变量的一部分,但可以直接访问。 请注意,在 Ansible 2.7.9 之前,返回变量被记录为 返回: 始终 示例: |