community.docker.docker_config 模块 – 管理 Docker 配置。

注意

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

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

要安装它，请使用： ansible-galaxy collection install community.docker。您需要其他需求才能使用此模块，请参阅 需求 以了解详情。

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

概要

• 在 Swarm 环境中创建和删除 Docker 配置。类似于 docker config create 和 docker config rm。

• 向新配置的元数据中添加“ansible_key”，这是一个加密的哈希数据表示，然后在以后的运行中用于测试配置是否已更改。如果不存在“ansible_key”，则除非设置了 force 选项，否则不会更新配置。

• 配置的更新是通过删除配置并重新创建它来执行的。

需求

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

• Docker API >= 1.30

• Python 的 Docker SDK：请注意，docker-py Python 模块已被 docker 取代（请参阅 此处 以了解详情）。此模块*不*支持 docker-py。

• Python 的 Docker SDK >= 2.6.0

• Python >= 2.7

参数

参数	注释
api_version 别名：docker_api_version 字符串	Docker 主机上运行的 Docker API 的版本。 默认为 Python 的 Docker SDK 和 docker 守护程序支持的最新 API 版本。 如果任务中未指定此值，则将使用环境变量 DOCKER_API_VERSION 的值。如果未设置环境变量，则将使用默认值。 默认值： "auto"
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 字符串	配置的值。 与data_src互斥。如果state=present，则需要data和data_src中的一个。
data_is_b64 布尔值	如果设置为true，则假定数据为 Base64 编码，并在使用前进行解码。 为了使用二进制data，最好将其保持为 Base64 编码，并让此选项进行解码。 选项 false ← (默认) true
data_src 路径 在 community.docker 1.10.0 中添加	目标上读取配置的文件。 与data互斥。如果state=present，则需要data和data_src中的一个。
debug 布尔值	调试模式 选项 false ← (默认) true
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"
force 布尔值	与state=present一起使用，始终删除并重新创建现有配置。 如果true，则即使现有配置未更改，也会被替换。 选项 false ← (默认) true
labels 字典	键值元数据的映射，其中key和value都应为字符串。 如果提供新的元数据或修改现有元数据，则配置将通过删除它并重新创建它来更新。
name 字符串 / 必需	配置的名称。
rolling_versions 布尔值 在 community.docker 2.2.0 中添加	如果设置为true，则配置将使用附加到其名称的递增版本号创建。 向托管的配置添加包含版本号的标签，名称为ansible_version。 选项 false ← (默认) true
state 字符串	如果配置应该存在，则设置为present；如果配置不应该存在，则设置为absent。 选项 "absent" "present" ← (默认)
template_driver 字符串 在 community.docker 2.5.0 中添加	设置为golang以在data中使用 Go 模板或在data_src中使用 Go 模板文件。 选项 "golang"
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
versions_to_keep 整数 在 community.docker 2.2.0 中添加	使用rolling_versions时，要保留的旧配置版本数。 创建新配置后，将删除多余的旧配置。 设置为-1以保留所有内容，或设置为0或1以仅保留当前配置。 默认值： 5

属性

属性	支持	描述
action_group	动作组： community.docker.docker, docker	在module_defaults中使用group/docker或group/community.docker.docker来设置此模块的默认值。
check_mode	支持：完全支持	可以在check_mode下运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在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.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: Create config foo (from a file on the control machine)
  community.docker.docker_config:
    name: foo
    # If the file is JSON or binary, Ansible might modify it (because
    # it is first decoded and later re-encoded). Base64-encoding the
    # file directly after reading it prevents this to happen.
    data: "{{ lookup('file', '/path/to/config/file') | b64encode }}"
    data_is_b64: true
    state: present

- name: Create config foo (from a file on the target machine)
  community.docker.docker_config:
    name: foo
    data_src: /path/to/config/file
    state: present

- name: Change the config data
  community.docker.docker_config:
    name: foo
    data: Goodnight everyone!
    labels:
      bar: baz
      one: '1'
    state: present

- name: Add a new label
  community.docker.docker_config:
    name: foo
    data: Goodnight everyone!
    labels:
      bar: baz
      one: '1'
      # Adding a new label will cause a remove/create of the config
      two: '2'
    state: present

- name: No change
  community.docker.docker_config:
    name: foo
    data: Goodnight everyone!
    labels:
      bar: baz
      one: '1'
      # Even though 'two' is missing, there is no change to the existing config
    state: present

- name: Update an existing label
  community.docker.docker_config:
    name: foo
    data: Goodnight everyone!
    labels:
      bar: monkey   # Changing a label will cause a remove/create of the config
      one: '1'
    state: present

- name: Force the (re-)creation of the config
  community.docker.docker_config:
    name: foo
    data: Goodnight everyone!
    force: true
    state: present

- name: Remove config foo
  community.docker.docker_config:
    name: foo
    state: absent

返回值

常见的返回值已在此处记录，以下是此模块特有的字段

键	描述
config_id 字符串	Docker 分配给 config 对象的 ID。 返回：成功和state=present 示例："hzehrmyjigmcp2gb6nlhmjqcv"
config_name 字符串 在 community.docker 2.2.0 中添加	已创建的 config 对象的名称。 返回：成功和state=present 示例："awesome_config"

作者

• Chris Houseknecht (@chouseknecht)

• John Hu (@ushuz)

集合链接

• 问题追踪器
• 代码库（源代码）
• 寻求帮助（Docker）
• 寻求帮助（Docker Compose）
• 寻求帮助（Docker Swarm）
• 提交错误报告
• 请求功能
• 沟通