community.crypto.acme_certificate_renewal_info 模块 – 判断是否需要续期证书

注意

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

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

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

要在剧本中使用它，请指定： 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。

自community.crypto 2.0.0起，值1已弃用，并将从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

支持： N/A

此操作不会修改状态。

在差异模式下，将返回有关已更改内容（或可能需要在 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。

返回：成功，证书存在，并且具有授权密钥标识符X.509扩展

示例： "aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE"

msg

字符串

有关续订原因的信息。

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

返回：成功

示例： "The certificate does not exist."

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)