community.aws.acm_certificate 模块 – 在 AWS 证书管理器服务中上传和删除证书
注意
此模块是 community.aws 集合 (版本 9.0.0) 的一部分。
如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install community.aws。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。
要在 playbook 中使用它，请指定：community.aws.acm_certificate。
community.aws 1.0.0 中的新增功能
概要
在 Amazon Web Service 的证书管理器 (AWS ACM) 中导入和删除证书。
此模块目前不与 AWS 提供的证书交互。它目前仅管理用户提供给 AWS 的证书。
ACM API 允许用户为同一个域名上传多个证书，甚至上传多个相同的证书。此模块尝试限制此类自由度，以符合 Ansible 的理念，使其成为幂等的。它通过将 AWS 资源“名称”标签应用于 ACM 证书来实现此目的。
当 state=present 时，如果 ACM 中有一个证书的
Name标签等于 name_tag 参数，并且主体和链相同，则此任务将成功完成，无需任何效果。当 state=present 时，如果 ACM 中有一个证书的 Name 标签等于 name_tag 参数，但主体不同，则此任务将覆盖该证书。
当 state=present 时，如果 ACM 中有多个证书的 Name 标签等于 name_tag 参数，则此任务将失败。
当 state=absent 且定义了 certificate_arn 时，如果此区域中存在具有该 ARN 的 ACM 资源，则此模块将删除该资源，如果不存在，则成功完成，无需任何效果。
当 state=absent 且定义了 domain_name 时，此模块将删除此 AWS 区域中所有具有相应域名的 ACM 资源。如果没有，则成功完成，无需任何效果。
当 state=absent 且未定义 certificate_arn，并且未定义 domain_name 时，此模块将删除此 AWS 区域中所有具有相应 Name 标签的 ACM 资源。如果没有，则成功完成，无需任何效果。
请注意，由于 ACM API 的限制，这可能无法与大小为 4096 位的密钥正常工作。
在 5.0.0 版本之前，此模块称为
community.aws.aws_acm。用法没有改变。
别名：aws_acm
要求
执行此模块的主机需要以下要求。
python >= 3.6
boto3 >= 1.28.0
botocore >= 1.31.0
参数
参数 |
注释 |
|---|---|
AWS 访问密钥 ID。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 还可以按优先级递减顺序使用 aws_access_key 和 profile 选项是互斥的。 为了与 AWS botocore SDK 保持一致，在 5.1.0 版本中添加了 aws_access_key_id 别名。 ec2_access_key 别名已被弃用，并将在 2024-12-01 之后的发行版中删除。
|
|
验证 SSL 证书时要使用的 CA 捆绑包的位置。 还可以使用 |
|
用于修改 botocore 配置的字典。 参数可以在 AWS 文档中找到 https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config。 |
|
PEM 编码的公共证书的主体。 当 state 不是 如果您的证书位于文件中，请使用 |
|
要修改或删除的 ACM 中证书的 ARN。 如果 state=present，则可以更新具有指定 ARN 的证书。例如，这可以用来向现有证书添加/删除标签。 如果 state=absent，则必须提供 certificate_arn、domain_name 或 name_tag 之一。 如果 state=absent 并且此区域中不存在具有此 ARN 的资源，则任务将成功完成，无需任何效果。 如果 state=absent 并且相应的资源存在于其他区域，则此任务可能会报告成功而不会删除该资源。 |
|
PEM 编码的证书链的主体。 如果您的证书链位于文件中，请使用 当 state=absent 时忽略 |
|
使用 也可以使用 选项
|
|
证书的域名。 如果 state=absent 且指定了 domain_name，则此任务将删除具有此域的所有 ACM 证书。 必须且只能提供 domain_name、name_tag 和 certificate_arn 中的一个。 如果 state=present，则不应指定此参数。（因为域名已编码在公共证书的主体中。） |
|
连接到非默认 AWS 端点的 URL。虽然这可以用于连接到其他与 AWS 兼容的服务，但 amazon.aws 和 community.aws 集合仅针对 AWS 进行了测试。 也可以使用 ec2_url 和 s3_url 别名已弃用，将在 2024-12-01 之后的一个版本中删除。
|
|
使用 AWS 标签对资源进行标记的唯一标识符，密钥为 Name。 这可以是 AWS 接受的任何一组标签值字符。 这是为了确保 Ansible 可以对证书进行幂等处理，即使 ACM API 允许重复证书。 如果 state=preset，则必须指定此参数。 如果 state=absent 且指定了 name_tag，则此任务将删除所有具有此 Name 标签的 ACM 证书。 如果 state=absent，则必须提供 certificate_arn、domain_name 或 name_tag 中的一个。 如果同时设置了 name_tag 和 tags 中的“Name”标签，则值必须相同。 如果未设置 tags 中的“Name”标签，而设置了 name_tag，则 name_tag 值将复制到 tags。 |
|
PEM 编码私钥的主体。 当 state=present 且证书不存在时，此参数是必需的。 当 state=absent 时，此参数将被忽略。 如果您的私钥位于文件中，请使用 |
|
用于身份验证的命名 AWS 配置文件。 有关命名配置文件的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html。 也可以使用 profile 选项与 aws_access_key、aws_secret_key 和 security_token 选项互斥。 |
|
如果 如果未设置 以 选项
|
|
要使用的 AWS 区域。 对于 IAM、Route53 和 CloudFront 等全球服务，将忽略 region。 也可以使用 有关更多信息，请参阅 Amazon AWS 文档 http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region。 ec2_region 别名已弃用，将在 2024-12-01 之后的一个版本中删除。
|
|
AWS 密钥。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 也可以使用 secret_key 和 profile 选项互斥。 为了与 AWS botocore SDK 保持一致，在 5.1.0 版本中添加了 aws_secret_access_key 别名。 ec2_secret_key 别名已弃用，将在 2024-12-01 之后的一个版本中删除。
|
|
与临时凭据一起使用的 AWS STS 会话令牌。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 也可以使用 security_token 和 profile 选项互斥。 在 3.2.0 版本中添加了 aws_session_token 和 session_token 别名，在 6.0.0 版本中将参数从 security_token 重命名为 session_token。 security_token、aws_security_token 和 access_token 别名已弃用，将在 2024-12-01 之后的一个版本中删除。
|
|
如果 state=present，则将上传指定的公共证书和私钥，Name 标签等于 name_tag。 如果 state=absent，则将删除此区域中任何具有相应 domain_name、name_tag 或 certificate_arn 的证书。 选项
|
|
表示要应用于资源的标签的字典。 如果未设置 |
|
设置为 强烈建议不要设置 validate_certs=false，作为替代方案，请考虑改为设置 aws_ca_bundle。 选项
|
注释
注意
在 3.2.0 版本中添加了对 tags 和 purge_tags 的支持。
警告：对于模块，环境变量和配置文件是从 Ansible 的“主机”上下文读取的，而不是“控制器”上下文。因此，可能需要将文件显式复制到“主机”。对于查找和连接插件，环境变量和配置文件是从 Ansible 的“控制器”上下文读取的，而不是“主机”上下文。
Ansible 使用的 AWS SDK (boto3) 也可能从 Ansible “主机”上下文中的配置文件（通常为
~/.aws/credentials）读取凭据和其他设置（例如区域）的默认值。更多信息，请参见 https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html。
示例
- name: upload a self-signed certificate
community.aws.acm_certificate:
certificate: "{{ lookup('file', 'cert.pem' ) }}"
privateKey: "{{ lookup('file', 'key.pem' ) }}"
name_tag: my_cert # to be applied through an AWS tag as "Name":"my_cert"
region: ap-southeast-2 # AWS region
- name: create/update a certificate with a chain
community.aws.acm_certificate:
certificate: "{{ lookup('file', 'cert.pem' ) }}"
private_key: "{{ lookup('file', 'key.pem' ) }}"
name_tag: my_cert
certificate_chain: "{{ lookup('file', 'chain.pem' ) }}"
state: present
region: ap-southeast-2
register: cert_create
- name: print ARN of cert we just created
ansible.builtin.debug:
var: cert_create.certificate.arn
- name: delete the cert we just created
community.aws.acm_certificate:
name_tag: my_cert
state: absent
region: ap-southeast-2
- name: delete a certificate with a particular ARN
community.aws.acm_certificate:
certificate_arn: "arn:aws:acm:ap-southeast-2:123456789012:certificate/01234567-abcd-abcd-abcd-012345678901"
state: absent
region: ap-southeast-2
- name: delete all certificates with a particular domain name
community.aws.acm_certificate:
domain_name: acm.ansible.com
state: absent
region: ap-southeast-2
- name: add tags to an existing certificate with a particular ARN
community.aws.acm_certificate:
certificate_arn: "arn:aws:acm:ap-southeast-2:123456789012:certificate/01234567-abcd-abcd-abcd-012345678901"
tags:
Name: my_certificate
Application: search
Environment: development
purge_tags: true
返回值
常用的返回值已在 此处 记录，以下是此模块特有的字段
键 |
描述 |
|---|---|
已在 ACM 中删除的证书的 ARN 列表 返回：当 state=absent 时 示例： |
|
关于已上传证书的信息 返回：当 state=present 时 |
|
ACM 中证书的 ARN 返回：当 state=present 且不在检查模式时 示例： |
|
公共证书中编码的域名 返回：当 state=present 时 示例： |