community.aws.acm_certificate 模块 – 在 AWS Certificate Manager 服务中上传和删除证书
注意
此模块是 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 的 Certificate Manager (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_access_key_id 别名在 5.1.0 版本中添加，以与 AWS botocore SDK 保持一致。 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，则不能指定此项。（因为域名编码在公共证书的主体中。） |
|
连接到的 URL，而不是默认的 AWS 端点。虽然这可以用于连接到其他与 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，则此任务将删除具有此名称标签的所有 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。
对 |
|
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_secret_access_key 别名在 5.1.0 版本中添加，以与 AWS botocore SDK 保持一致。 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 选项互斥。 别名 aws_session_token 和 session_token 在 3.2.0 版本中添加，该参数在 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。 选项
|
注释
注意
tags 和 purge_tags 的支持在 3.2.0 版本中添加。
注意： 对于模块，环境变量和配置文件是从 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 时 示例: |