community.docker.docker_secret 模块 – 管理 Docker 密钥。

注意

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

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

要安装它，请使用： ansible-galaxy collection install community.docker。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。

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

概要

• 在 Swarm 环境中创建和删除 Docker 密钥。类似于 docker secret create 和 docker secret rm。

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

• 通过删除密钥并重新创建它来执行对密钥的更新。

要求

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

• Docker API >= 1.25

• 用于 Python 的 Docker SDK：请注意，docker-py Python 模块已被 docker 取代（有关详细信息，请参见 此处）。此模块*不*与 docker-py 兼容。

• 用于 Python 的 Docker SDK >= 2.1.0

• Python >= 2.7

参数

参数	注释
api_version 别名：docker_api_version 字符串	Docker 主机上运行的 Docker API 的版本。 默认为 Docker SDK for Python 和 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 字典	键值元数据的映射，键和值都应为字符串。 如果提供了新的元数据或修改了现有元数据，则将通过删除并重新创建密钥来更新密钥。
name 字符串 / 必需	密钥的名称。
rolling_versions 布尔值 在 community.docker 2.2.0 中添加	如果设置为true，则密钥将创建递增的版本号添加到其名称中。 向托管的密钥添加包含版本号的标签，名称为ansible_version。 选项 false ← (默认) true
state 字符串	如果密钥应存在，则设置为present；如果密钥不应存在，则设置为absent。 选项 "absent" "present" ← (默认)
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 secret foo (from a file on the control machine)
  community.docker.docker_secret:
    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/secret/file') | b64encode }}"
    data_is_b64: true
    state: present

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

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

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

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

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

- name: Force the removal/creation of the secret
  community.docker.docker_secret:
    name: foo
    data: Goodnight everyone!
    force: true
    state: present

- name: Remove secret foo
  community.docker.docker_secret:
    name: foo
    state: absent

返回值

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

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

作者

• Chris Houseknecht (@chouseknecht)

资源链接

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