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.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: 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 之前,返回变量被记录为  返回: 始终 示例:  | 
