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
用于 Python 的 Docker SDK:请注意,docker-py Python 模块已被 docker 取代(有关详细信息,请参阅 此处)。此模块 *不* 适用于 docker-py。
用于 Python 的 Docker SDK >= 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。 |
|
键值对的字典。 对应于 |
|
调试模式 Choices
|
|
自定义 DNS 服务器列表。 对应于 |
|
自定义 DNS 选项列表。 对应于 |
|
自定义 DNS 搜索域列表。 对应于 |
|
用于连接 Docker API 的 URL 或 Unix 套接字路径。要连接到远程主机,请提供 TCP 连接字符串。例如, 如果任务中未指定该值,则会使用环境变量 默认值: |
|
服务端点模式。 对应于 Choices
|
|
服务环境变量的列表或字典。 如果传递列表,则每个项目需要采用 如果传递字典,则 YAML 解析器可能会将值解析为数字、布尔值或其他类型,为了避免数据丢失,必须引用这些值(例如 对应于 |
|
即使没有更改需要,也强制更新。 对应于 Choices
|
|
容器进程将作为其运行的其他组名称和/或 ID 的列表。 对应于 |
|
配置一个检查,用于确定此服务的容器是否“健康”。有关运行状况检查工作原理的详细信息,请参阅 HEALTHCHECK Dockerfile 指令 的文档。
|
|
运行检查的时间间隔。 |
|
报告不健康所需的连续失败次数。它接受整数值。 |
|
在启动健康重试倒计时之前,容器初始化的开始时间段。 |
|
运行以检查运行状况的命令。 必须是字符串或列表。如果是一个列表,则第一项必须是 |
|
允许一次检查运行的最长时间。 |
|
容器主机名。 对应于 |
|
主机到 IP 的映射字典,其中每个主机名都是字典中的键。每个主机名都将添加到容器的 /etc/hosts 文件中。 对应于 |
|
服务镜像路径和标签。 对应于 |
|
在每个服务容器内部使用 init 来转发信号和回收进程。 对应于 需要 API 版本 >= 1.37。 Choices
|
|
键值对的字典。 对应于 |
|
配置服务资源限制。 |
|
服务 CPU 限制。 对应于 |
|
服务内存限制,格式为
省略单位默认为字节。 对应于 |
|
服务的日志配置。 |
|
配置服务的日志驱动程序。 对应于 |
|
服务日志驱动程序的选项。 对应于 |
|
服务复制模式。 更改时将删除并重新创建服务。 对应于 Choices
|
|
描述服务挂载的字典列表。 对应于 |
|
卷驱动程序配置。 只能在 |
|
用于卷的卷驱动程序插件的名称。 |
|
作为键值对传递给此卷驱动程序的选项。 |
|
要应用的卷标签。 |
|
要使用的传播模式。 仅当 Choices
|
|
挂载是否应为只读。 Choices
|
|
挂载源(例如卷名称或主机路径)。 如果 |
|
容器路径。 |
|
tmpfs 的文件模式,八进制表示。 仅当 |
|
tmpfs 挂载的大小,格式为 仅当 |
|
挂载类型。 请注意, Choices
|
|
服务名称。 对应于 |
|
服务网络名称或字典的列表。 当传递字典时,有效的子选项为 在 API 版本 1.29 之前,不支持更新和删除网络。如果进行了更改,则会删除并重新创建服务。 对应于 |
|
配置服务放置偏好和约束。 |
|
服务约束的列表。 对应于 |
|
作为键值对的放置偏好列表。 对应于 需要 API 版本 >= 1.27。 |
|
每个节点的最大任务数。 对应于 需要 API 版本 >= 1.40 |
|
描述服务发布的端口的字典列表。 对应于 |
|
要使用的发布模式。 需要 API 版本 >= 1.32。 Choices
|
|
要使用的协议。 Choices
|
|
要外部可用的端口。 |
|
容器内要公开的端口。 |
|
将容器的根文件系统以只读方式挂载。 对应于 Choices
|
|
服务中实例化的容器数量。仅当 如果设置为 如果设置为 对应于 默认值: |
|
配置服务资源预留。 |
|
服务 CPU 预留。 对应于 |
|
服务内存预留,格式为
省略单位默认为字节。 对应于 |
|
是否应从注册表解析并更新当前镜像摘要(如果已更改)。 需要 API 版本 >= 1.30。 Choices
|
|
配置容器退出时是否以及如何重启。 |
|
服务的重启条件。 对应于 Choices
|
|
重启之间的延迟。 接受格式如下的字符串: 对应于 |
|
服务重启的最大次数。 对应于 |
|
重启策略评估窗口。 接受格式如下的字符串: 对应于 |
|
配置在更新失败的情况下应如何回滚服务。 |
|
任务回滚之间的延迟。 接受格式如下的字符串: 对应于 需要 API 版本 >= 1.28。 |
|
回滚失败时要采取的操作。 对应于 需要 API 版本 >= 1.28。 Choices
|
|
在回滚期间可能失败的任务的分数。 对应于 需要 API 版本 >= 1.28。 |
|
每次任务回滚后监控失败的持续时间。 接受格式如下的字符串: 对应于 需要 API 版本 >= 1.28。 |
|
指定回滚期间操作的顺序。 对应于 需要 API 版本 >= 1.29。 |
|
一次回滚的容器数量。如果设置为 0,则所有容器同时回滚。 对应于 需要 API 版本 >= 1.28。 |
|
描述服务密钥的字典列表。 对应于 |
|
包含密钥的文件名。如果未指定,则默认为 对应于 |
|
密钥文件组的 GID。 |
|
容器内部的文件访问模式。必须是八进制数(如 |
|
密钥的 ID。 |
|
创建时定义的密钥名称。 |
|
密钥文件所有者的 UID。 |
|
Choices
|
|
在强制杀死容器之前等待的时间。 接受格式为字符串的持续时间,例如: 对应于 |
|
覆盖用于停止容器的默认信号。 对应于 |
|
键值对的字典。 |
|
通过使用 TLS 而不验证 Docker 主机服务器的真实性来保护与 API 的连接。请注意,如果同时将 如果未在任务中指定该值,则将使用环境变量 Choices
|
|
在验证 Docker 主机服务器的真实性时,提供服务器的预期名称。 如果未在任务中指定该值,则将使用环境变量 请注意,此选项在旧版本中的默认值为 注意: Docker SDK for Python 7.0.0+ 不再支持此选项。使用 Docker SDK for Python 7.0.0 或更高版本指定它将导致错误。 |
|
分配一个伪终端。 对应于 Choices
|
|
配置应如何更新服务。用于配置滚动更新非常有用。 |
|
滚动更新延迟。 接受格式如下的字符串: 对应于 |
|
容器发生故障时要采取的操作。 对应于 使用 Choices
|
|
在调用失败操作之前,更新期间可能失败的任务比例。 对应于 |
|
监视更新任务失败的时间。 接受格式如下的字符串: 对应于 |
|
指定推出更新任务时操作的顺序。 对应于 需要 API 版本 >= 1.29。 |
|
滚动更新并行度。 对应于 |
|
对于 SSH 传输,请使用 需要 Docker SDK for Python 4.4.0 或更高版本。 Choices
|
|
设置用于指定命令的用户名或 UID。 在 Ansible 2.8 之前,此选项的默认值为 默认值已被删除,因此如果此处未指定用户,则使用镜像中定义的用户。 对应于 |
|
通过使用 TLS 并验证 Docker 主机服务器的真实性来保护与 API 的连接。 如果未在任务中指定该值,则将使用环境变量 Choices
|
|
工作目录的路径。 对应于 |
属性
属性 |
支持 |
描述 |
---|---|---|
操作组: community.docker.docker, docker |
在 |
|
支持: 完整 |
可以在 |
|
支持: 完整 |
在 diff 模式下,将返回有关已更改的内容(或可能需要在 |
说明
注意
仅当使用 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 包。对于 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 守护进程通信。
示例
- 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 之前,返回变量被记录为 返回: 总是 示例: |