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连接到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 daemon。您可以定义 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 daemon 时，您可能需要安装额外的 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 daemon 通信。

示例

- 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 为密钥对象分配的 ID。 返回值：成功和 state=present 示例： "hzehrmyjigmcp2gb6nlhmjqcv"
secret_name 字符串 community.docker 2.2.0版本中添加	已创建的密钥对象的名称。 返回值：成功和 state=present 示例： "awesome_secret"

作者

• Chris Houseknecht (@chouseknecht)

集合链接

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