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安全连接到API并验证Docker主机服务器的真实性。 如果任务中未指定此值，则将使用环境变量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包。对于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: 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分配给配置对象的ID。 返回：成功且state=present 示例： "hzehrmyjigmcp2gb6nlhmjqcv"
config_name 字符串 在community.docker 2.2.0版本中添加	已创建配置对象的名称。 返回：成功且state=present 示例： "awesome_config"

作者

• Chris Houseknecht (@chouseknecht)

• John Hu (@ushuz)

资源链接

• 问题追踪器
• 代码仓库
• 寻求帮助 (Docker)
• 寻求帮助 (Docker Compose)
• 寻求帮助 (Docker Swarm)
• 提交错误报告
• 提出功能请求
• 沟通