证书自动化的工作原理先决条件安装提供商配置提供商所需的权限验证安装配置参考日志记录

AWS工作负载凭证提供程序

AWS工作负载凭证提供程序可自动使用从 ACM 导出的公共和私有 TLS 证书。提供程序会定期检索证书及其私钥，将其写入配置的路径，并有选择地运行命令来重新加载依赖的服务，例如 Web 服务器。

您可以在以下计算环境中使用工作负载凭证提供程序：

Amazon Elastic Compute Cloud（Amazon EC2）
On-premises 带有AWS凭据的服务器

工作负载证书提供商使用 IAM 角色假设来检索证书。它作为系统服务在 Linux 和 Windows 上以专用的低权限用户身份本地运行，并以受限权限写入证书文件。

重要

此提供商只能使用可导出的证书。有关更多信息，请参阅AWS Certificate Manager 可导出的公共证书和导出私有证书。

AWS工作负载凭证提供程序是开源的。有关源代码和贡献，请参阅GitHub 存储库。

证书自动化的工作原理

提供商使用调度程序，按固定的间隔刷新每个已配置的证书：

刷新间隔为 24 小时。
在每个周期中，提供程序都会导出证书，将其与磁盘上的文件进行比较，并仅在内容发生更改时才写入新文件。
更新证书文件后，配置文件将refresh_command运行（例如，重新加载 NGINX 或 Apache）。
如果证书内容未更改，则会跳过刷新命令。

提供程序在每次系统启动时和服务启动后不久都会执行一次初始刷新，当多个提供商在队列中同时启动时，会有少量随机抖动，以避免同步进行 API 调用。

该提供程序还支持动态配置重新加载，允许您添加、删除或修改证书，而无需重新安装。有关更多信息，请参阅重新加载动态配置。

先决条件

在安装提供程序之前，请确保您具备以下条件：

带有 systemd 的 Linux 实例（亚马逊 Linux 2023、Ubuntu 20.04+ 或 RHEL 8+）
或者运行 Windows Server 2016 或更高版本且版本为 PowerShell 5.1 或更高版本的 Windows 实例
运行安装程序的管理员权限
ACM 中的可导出证书
具有 ACM 导出权限的 IAM 角色（请参阅所需的权限）
AWS实例上可用的凭证（实例配置文件、环境变量或凭证文件）

安装提供商

Linux

构建提供商

从源代码构建提供程序二进制文件，或者获取适用于您的平台的预构建二进制文件。按照安装 Rust 中的说明安装 Rust 工具链。
```
cargo build --release
```
可执行文件位于target/release/aws-workload-credentials-provider。
创建配置文件

使用您的证书详细信息创建 TOML 配置文件。有关示例，请参阅配置提供商。当您使用该--config选项时，安装程序/etc/aws-workload-credentials-provider/config.toml会自动将此文件复制到。

运行安装程序

以 root 用户身份运行安装脚本：


cd aws_workload_credentials_provider_common/configuration
sudo ./install --config /path/to/your/config.toml

（可选）提供AWS凭证

在附带实例配置文件的 Amazon EC2 实例上，提供商会自动获取证书。对于其他环境，请创建一个 systemd 覆盖文件以注入凭据：


sudo mkdir -p /etc/systemd/system/aws-workload-credentials-provider-acm.service.d
sudo tee /etc/systemd/system/aws-workload-credentials-provider-acm.service.d/creds.conf > /dev/null <<EOF
[Service]
Environment="AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE"
Environment="AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
Environment="AWS_REGION=us-west-2"
EOF
sudo systemctl daemon-reload
sudo systemctl restart aws-workload-credentials-provider-acm

Windows

构建或获取提供者

从 Windows 的源代码构建提供程序二进制文件，或者获取预先构建的二进制文件。按照安装 Rust 中的说明安装 Rust 工具链。
```
cargo build --release
```
可执行文件位于target\release\aws-workload-credentials-provider.exe。
创建配置文件

使用您的证书详细信息创建 TOML 配置文件。有关示例，请参阅配置提供商。当您使用-Config参数时，安装程序C:\ProgramData\AWS\WorkloadCredentialsProvider\config.toml会自动将此文件复制到。

运行安装程序

以管理员身份运行安装脚本：


cd aws_workload_credentials_provider_common\configuration
.\install.ps1 -Config C:\path\to\your\config.toml

要在不启动服务的情况下进行安装，请执行以下操作：


.\install.ps1 -Config C:\path\to\your\config.toml -NoStart

（可选）提供AWS凭证

在附带实例配置文件的 Amazon EC2 实例上，提供商会通过 IMDS 自动获取证书。对于其他环境，请通过 Windows 注册表为服务设置环境变量：


$regPath = "HKLM:\SYSTEM\CurrentControlSet\Services\AWSWorkloadCredentialsProvider-ACM"
$envVars = @(
    "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE",
    "AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "AWS_REGION=us-west-2"
)
New-ItemProperty -Path $regPath -Name "Environment" -Value $envVars -PropertyType MultiString -Force
Restart-Service AWSWorkloadCredentialsProvider-ACM

配置提供商

使用您的证书详细信息创建 TOML 配置文件。当您使用该--config选项/etc/aws-workload-credentials-provider/config.toml时，安装程序会将此文件复制到。

注意

省略chain_path时，证书链将附加到文件中certificate_path以生成完整链文件。这与需要包含证书及其链的单个文件的 Web 服务器兼容。

重新加载动态配置

通过运行acm reload命令，无需重新安装即可更新提供程序的配置。这将验证新配置，更新权限以匹配新的证书路径，并重新启动服务。

从配置中删除的证书将停止刷新。新证书将立即开始首次导出。每个证书都作为一项独立的任务运行，因此一个证书的失败不会影响其他证书。

所需的权限

基本凭证

提供商的基本凭证（实例配置文件或环境）必须能够担任每个证书中指定的角色role_arn：


{
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::123456789012:role/ACMExportRole"
}

证书导出角色

中指定的角色role_arn需要以下权限：


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "acm:ExportCertificate",
            "Resource": "arn:aws:acm:us-west-2:123456789012:certificate/*"
        }
    ]
}

角色的信任策略必须允许提供者的基本身份来假设它：


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/EC2InstanceRole"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

刷新命令权限 (Linux)

在 Linux 上，提供程序refresh_command通过sudo执行配置的。安装程序在上生成一个 sudoers 条目/etc/sudoers.d/aws-workload-credentials-provider，允许提供者用户在没有密码提示的情况下运行精确配置的命令。

重要

确保/etc/sudoers包含/etc/sudoers.d目录。如果这个 include 指令不存在，安装程序会发出警告。没有它，生成的 sudoers 文件将无效，刷新命令将失败。

在 Windows 上，提供程序将refresh_command作为系统计划任务触发。

验证安装

安装完成后，请验证提供程序是否正在运行并且正在写入证书：

配置参考

字段	必填	默认值	说明
`logging.log_level`	否	`info`	记录详细程度：`debug`、、、`info`、`warn` `error` `none`
`logging.log_to_file`	否	`true`	将日志写入文件 (`true`) 或 stdout/stderr (`false`)
`capabilities.acm.enabled`	否	`false`	启用或禁用 ACM 功能
`certificates[].certificate_arn`	是	—	要导出的 ACM 证书的 ARN
`certificates[].role_arn`	是	—	要为呼叫担任的 IAM 角色 ARN `ExportCertificate`
`certificates[].certificate_path`	是	—	写入证书文件的绝对路径
`certificates[].private_key_path`	是	—	写入私钥文件的绝对路径
`certificates[].chain_path`	否	—	写入证书链的绝对路径。如果省略，则将链附加到 `certificate_path`
`certificates[].refresh_command`	否	—	更新证书文件后要运行的命令。必须是绝对路径
`certificates[].certificate_and_chain_permission`	否	`0600`	证书和链文件的文件权限（Linux `mode` 格式）
`certificates[].key_permission`	否	`0600`	私钥文件的文件权限（Linux `mode` 格式）

日志记录

在 Linux 上，提供程序登录到/opt/aws/workload-credentials-provider/logs/acm_provider.log。

在 Windows 上，提供商登录到C:\ProgramData\AWS\WorkloadCredentialsProvider\logs\acm_provider.log。服务启动和停止事件也记录在源下的 Windows 应用程序事件日志中AWSWorkloadCredentialsProvider-ACM。

日志轮换-当当前文件达到 10 MB 时，提供程序会创建一个新的日志文件，并最多存储五个存档的日志文件。

AWS服务日志 — 当提供者呼叫时ExportCertificate，该呼叫将使用包含以下内容AWSCloudTrail 的用户代理字符串进行录制aws-workload-credentials-provider。提供程序的内部操作（调度程序周期、文件写入）仅出现在本地日志中。

您可以使用log_level和log_to_file设置来配置日志记录。有关更多信息，请参阅配置参考。

文档惯例

集成服务之外的自动化

证书管理

AWS工作负载凭证提供程序

重要

证书自动化的工作原理

先决条件

安装提供商

构建提供商

创建配置文件

运行 安装程序

（可选）提供AWS凭证

构建或获取提供者

创建配置文件

运行 安装程序

（可选）提供AWS凭证

配置提供商

注意

重新加载动态配置

所需的权限

基本凭证

证书导出角色

刷新命令权限 (Linux)

重要

验证安装

配置参考

日志记录

运行安装程序

运行安装程序