community.crypto.acme_certificate_renewal_info 模块 – 确定是否应续订证书

注意

此模块是 community.crypto 集合（版本 2.22.3）的一部分。

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

要安装它，请使用：ansible-galaxy collection install community.crypto。您需要进一步的要求才能使用此模块，请参阅 要求 以了解详细信息。

要在 playbook 中使用它，请指定：community.crypto.acme_certificate_renewal_info。

community.crypto 2.20.0 中的新功能

概要

要求

以下要求需要在执行此模块的主机上满足。

参数

参数

注释

acme_directory

字符串 / 必需

要使用的 ACME 目录。这是访问 ACME CA 服务器 API 的入口点 URL。

出于安全原因，默认设置为 Let’s Encrypt 暂存服务器（对于 ACME v1 协议）。这将创建技术上正确但不受信任的证书。

对于 Let’s Encrypt，所有暂存端点都可以在这里找到：https://letsencrypt.openssl.ac.cn/docs/staging-environment/。对于 Buypass，所有端点都可以在这里找到：https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints

对于 Let’s Encrypt，ACME v2 的生产目录 URL 为 https://acme-v02.api.letsencrypt.org/directory。

对于 Buypass，ACME v2 和 v1 的生产目录 URL 为 https://api.buypass.com/acme/directory。

对于 ZeroSSL，ACME v2 的生产目录 URL 为 https://acme.zerossl.com/v2/DV90。

对于 Sectigo，ACME v2 的生产目录 URL 为 https://acme-qa.secure.trust-provider.com/v2/DV。

此模块的备注包含此模块已测试过的 ACME 服务列表。

acme_version

整数 / 必需

端点的 ACME 版本。

对于经典的 Let’s Encrypt 和 Buypass ACME 端点，必须为 1，对于标准化的 ACME v2 端点，必须为 2。

值 1 自 community.crypto 2.0.0 起已弃用，并将从 community.crypto 3.0.0 中删除。

选项

  • 1

  • 2

ari_algorithm

字符串

如果使用 ARI 信息，则选择使用哪种算法来确定是否立即续订。

standard 选择 ARI 规范中提供的算法。

start 一旦达到续订间隔的开始时间，则返回 should_renew=true。

选项

  • "standard" ←（默认）

  • "start"

certificate_content

字符串

用于确定续订的 X.509 证书的内容。

certificate_path 和 certificate_content 是互斥的。

certificate_path

路径

用于确定续订的 X.509 证书的路径。

如果证书不存在，模块将始终返回 should_renew=true。

certificate_path 和 certificate_content 是互斥的。

now

字符串

使用此时间戳而不是当前时间戳来确定是否应续订证书。

时间可以指定为相对时间或绝对时间戳。

时间将始终解释为 UTC 时间。

有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是一个整数 + [w | d | h | m | s]（例如 +32w1d2h）。

remaining_days

整数

证书必须保持有效的剩余天数。

例如，如果 remaining_days=20，如果证书的有效期不足 20 天，则此检查会导致 should_renew=true。

remaining_percentage

浮点数

证书有效期应剩余的百分比。

例如，如果 remaining_percentage=0.1，并且证书的有效期为 90 天，如果证书的有效期少于 9 天，则此检查会导致 should_renew=true。

必须是 0 到 1 之间的值。

request_timeout

整数

在 community.crypto 2.3.0 中添加

Ansible 应该等待 ACME API 响应的时间。

此超时应用于所有 HTTP(S) 请求（HEAD、GET、POST）。

默认值： 10

select_crypto_backend

字符串

确定要使用的加密后端。

默认选择是 auto，它会尝试使用 cryptography（如果可用），并回退到 openssl。

如果设置为 openssl，将尝试使用 openssl 二进制文件。

如果设置为 cryptography，将尝试使用 cryptography 库。

选项

  • "auto" ← (默认)

  • "cryptography"

  • "openssl"

use_ari

布尔值

是否使用 ARI 信息（如果可用）。

如果 ACME 服务器实现 ARI 的方式与此模块不兼容，则将其设置为 false。

选项

  • false

  • true ← (默认)

validate_certs

布尔值

对 ACME 目录的调用是否会验证 TLS 证书。

警告： 仅应出于测试目的将其设置为 false，例如在针对本地 Pebble 服务器进行测试时。

选项

  • false

  • true ← (默认)

属性

属性

支持

描述

check_mode

支持：完全

此操作不会修改状态。

可以在 check_mode 中运行并返回已更改的状态预测，而无需修改目标。

diff_mode

支持：不适用

此操作不会修改状态。

在差异模式下运行时，将返回有关已更改的内容（或可能需要在 check_mode 中更改的内容）的详细信息。

注意

注意

  • 虽然选择的默认值是为了使该模块可以与 Let’s Encrypt CA 一起使用，但原则上该模块可以与任何提供 ACME 端点的 CA 一起使用，例如 Buypass Go SSL。

  • 到目前为止，ACME 模块仅由开发人员针对 Let’s Encrypt（测试和生产）、Buypass（测试和生产）、ZeroSSL（生产）和 Pebble 测试服务器 进行了测试。我们收到了社区的反馈，他们也可以与 Sectigo ACME Service for InCommon 一起使用。如果您在使用其他 ACME 服务器时遇到问题，请创建一个问题以帮助我们支持它。如果您发现未提及的 ACME 服务器可以正常工作，也请提供反馈。

  • 如果提供了足够新版本的 cryptography 库（有关详细信息，请参阅“要求”），将使用它而不是 openssl 二进制文件。可以使用 select_crypto_backend 选项显式禁用或启用此功能。请注意，使用 openssl 二进制文件会较慢。

另请参阅

另请参阅

community.crypto.acme_certificate

允许使用 ACME 协议获取证书

community.crypto.acme_ari_info

获取证书的续订信息

示例

- name: Retrieve renewal information for a certificate
  community.crypto.acme_certificate_renewal_info:
    certificate_path: /etc/httpd/ssl/sample.com.crt
  register: cert_data

- name: Should the certificate be renewed?
  ansible.builtin.debug:
    var: cert_data.should_renew

返回值

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

键

描述

cert_id

字符串

根据 ARI 规范的证书 ID。

已返回： 成功，证书存在，并且具有 Authority Key Identifier X.509 扩展

示例： "aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE"

msg

字符串

有关续订原因的信息。

应向用户显示，因为在 ARI 触发续订的情况下，它可能包含重要信息，例如有关错误颁发证书的强制撤销的信息。

已返回： 成功

示例： "证书不存在。"

should_renew

布尔值

是否应续订证书。

如果未提供证书或证书已过期，则始终为 true。

已返回： 成功

示例： true

supports_ari

布尔值

是否使用 ARI 信息来确定续订。这可以用来确定是否为 community.crypto.acme_certificate 模块指定 include_renewal_cert_id=when_ari_supported。

如果 use_ari=false，则始终为 false。

已返回： 成功

示例： true

作者

  • Felix Fontein (@felixfontein)