本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# AWS工作负载凭证提供程序
<a name="acm-certificate-automation"></a>

AWS工作负载凭证提供程序可自动使用从 ACM 导出的[公](https://docs.aws.amazon.com/acm/latest/userguide/acm-exportable-certificates.html)[共和私有](https://docs.aws.amazon.com/acm/latest/userguide/export-private.html) TLS 证书。提供程序会定期检索证书及其私钥，将其写入配置的路径，并有选择地运行命令来重新加载依赖的服务，例如 Web 服务器。

您可以在以下计算环境中使用工作负载凭证提供程序：
+ Amazon Elastic Compute Cloud（Amazon EC2）
+ On-premises 带有AWS凭据的服务器

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

**重要**  
此提供商只能使用可导出的证书。有关更多信息，请参阅[AWS Certificate Manager 可导出的公共证书](acm-exportable-certificates.md)和[导出私有证书](https://docs.aws.amazon.com/acm/latest/userguide/export-private.html)。

AWS工作负载凭证提供程序是开源的。有关源代码和贡献，请参阅[GitHub 存储库](https://github.com/aws/aws-workload-credentials-provider)。

## 证书自动化的工作原理
<a name="acm-cert-automation-refresh"></a>

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

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

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

## 先决条件
<a name="acm-cert-automation-prereqs"></a>

在安装提供程序之前，请确保您具备以下条件：
+ 带有 systemd 的 Linux 实例（亚马逊 Linux 2023、Ubuntu 20.04\+ 或 RHEL 8\+）
+ 或者运行 Windows Server 2016 或更高版本且版本为 PowerShell 5.1 或更高版本的 Windows 实例
+ 运行安装程序的管理员权限
+ ACM 中的可导出证书
+ 具有 ACM 导出权限的 IAM 角色（请参阅[所需的权限](#acm-cert-automation-permissions)）
+ AWS实例上可用的凭证（实例配置文件、环境变量或凭证文件）

## 安装提供商
<a name="acm-cert-automation-install"></a>

------
#### [ Linux ]

1. 

**构建提供商**

   从源代码构建提供程序二进制文件，或者获取适用于您的平台的预构建二进制文件。按照[安装 Rust](https://www.rust-lang.org/tools/install) 中的说明安装 Rust 工具链。

   ```
   cargo build --release
   ```

   可执行文件位于`target/release/aws-workload-credentials-provider`。

1. 

**创建配置文件**

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

1. 

**运行 安装程序**

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

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

1. 

**（可选）提供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 ]

1. 

**构建或获取提供者**

   从 Windows 的源代码构建提供程序二进制文件，或者获取预先构建的二进制文件。按照[安装 Rust](https://www.rust-lang.org/tools/install) 中的说明安装 Rust 工具链。

   ```
   cargo build --release
   ```

   可执行文件位于`target\release\aws-workload-credentials-provider.exe`。

1. 

**创建配置文件**

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

1. 

**运行 安装程序**

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

   ```
   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
   ```

1. 

**（可选）提供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
   ```

------

## 配置提供商
<a name="acm-cert-automation-configure"></a>

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

------
#### [ NGINX ]

```
[logging]
log_level = "info"
log_to_file = true

[capabilities.acm]
enabled = true

[[capabilities.acm.certificates]]
certificate_arn = "arn:aws:acm:us-west-2:123456789012:certificate/abcd1234-5678-90ab-cdef-EXAMPLE11111"
role_arn = "arn:aws:iam::123456789012:role/ACMExportRole"
certificate_path = "/etc/pki/tls/certs/example.com.crt"
private_key_path = "/etc/pki/tls/private/example.com.key"
chain_path = "/etc/pki/tls/certs/example.com-chain.pem"
refresh_command = "/usr/sbin/nginx -s reload"
```

------
#### [ Apache ]

```
[logging]
log_level = "info"
log_to_file = true

[capabilities.acm]
enabled = true

[[capabilities.acm.certificates]]
certificate_arn = "arn:aws:acm:us-west-2:123456789012:certificate/abcd1234-5678-90ab-cdef-EXAMPLE11111"
role_arn = "arn:aws:iam::123456789012:role/ACMExportRole"
certificate_path = "/etc/ssl/certs/example.com.crt"
private_key_path = "/etc/ssl/private/example.com.key"
chain_path = "/etc/ssl/certs/example.com-chain.pem"
refresh_command = "/bin/systemctl reload httpd"
```

------
#### [ Apache (Windows) ]

```
[logging]
log_level = "info"
log_to_file = true

[capabilities.acm]
enabled = true

[[capabilities.acm.certificates]]
certificate_arn = "arn:aws:acm:us-west-2:123456789012:certificate/abcd1234-5678-90ab-cdef-EXAMPLE11111"
role_arn = "arn:aws:iam::123456789012:role/ACMExportRole"
certificate_path = 'C:\Apache24\conf\ssl\example.com.crt'
private_key_path = 'C:\Apache24\conf\ssl\example.com.key'
chain_path = 'C:\Apache24\conf\ssl\example.com-chain.pem'
refresh_command = 'C:\Apache24\bin\httpd.exe -k restart'
```

------

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

### 重新加载动态配置
<a name="acm-cert-automation-reload"></a>

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

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

------
#### [ Linux ]

```
aws-workload-credentials-provider acm reload --config /path/to/new-config.toml
```

------
#### [ Windows ]

```
& 'C:\Program Files\AWS\WorkloadCredentialsProvider\bin\aws-workload-credentials-provider.exe' acm reload -Config C:\path\to\new-config.toml
```

------

## 所需的权限
<a name="acm-cert-automation-permissions"></a>

### 基本凭证
<a name="acm-cert-automation-permissions-base"></a>

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

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

### 证书导出角色
<a name="acm-cert-automation-permissions-export-role"></a>

中指定的角色`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)
<a name="acm-cert-automation-permissions-refresh"></a>

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

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

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

## 验证安装
<a name="acm-cert-automation-verify"></a>

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

------
#### [ Linux ]

1. **检查服务状态：**

   ```
   sudo systemctl status aws-workload-credentials-provider-acm
   ```

1. **查看提供商日志：**

   ```
   cat /opt/aws/workload-credentials-provider/logs/acm_provider.log
   ```

1. **验证证书文件是否存在：**

   ```
   ls -la /etc/pki/tls/certs/example.com.crt
   ls -la /etc/pki/tls/private/example.com.key
   ```

1. **验证证书内容：**

   ```
   openssl x509 -in /etc/pki/tls/certs/example.com.crt -noout -subject -dates
   ```

------
#### [ Windows ]

1. **检查服务状态：**

   ```
   Get-Service AWSWorkloadCredentialsProvider-ACM | Format-List Name, Status, StartType
   ```

1. **查看提供商日志：**

   ```
   Get-Content "C:\ProgramData\AWS\WorkloadCredentialsProvider\logs\acm_provider.log" -Tail 20
   ```

1. **验证证书文件是否存在：**

   ```
   Get-Item C:\certs\example.com.crt
   Get-Item C:\certs\example.com.key
   ```

1. **验证证书内容：**

   ```
   $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\certs\example.com.crt")
   $cert | Select-Object Subject, NotBefore, NotAfter
   ```

------

## 配置参考
<a name="acm-cert-automation-config-reference"></a>


| 字段 | 必填 | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| 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 格式） | 

## 日志记录
<a name="acm-cert-automation-logging"></a>

在 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`设置来配置日志记录。有关更多信息，请参阅 [配置参考](#acm-cert-automation-config-reference)。