本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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)
+ 具有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 執行個體 (Amazon Linux 2023、Ubuntu 20.04\+ 或 RHEL 8\+)
+ 或使用 PowerShell 5.1 或更新版本執行 Windows Server 2016 或更新版本的 Windows 執行個體
+ 執行安裝程式的管理員存取權
+ ACM 中的可匯出憑證
+ 具有 ACM 匯出許可的 IAM 角色 （請參閱 [所需的許可](#acm-cert-automation-permissions))
+ AWS執行個體上可用的登入資料 （執行個體描述檔、環境變數或登入資料檔案）

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

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

1. 

**建置供應商**

   從來源建置提供者二進位檔，或取得您平台的預先建置二進位檔。遵循 [Install 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. 

**執行 安裝程式**

   以根目錄執行安裝指令碼：

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

1. 

**（選用） 提供AWS登入資料**

   在具有連接執行個體描述檔的 Amazon EC2 執行個體上，提供者會自動取得登入資料。對於其他環境，建立系統化覆寫檔案以注入登入資料：

   ```
   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 來源建置提供者二進位檔，或取得預先建置的二進位檔。遵循 [Install 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`目錄。如果這包含指令不存在，安裝程式會發出警告。如果沒有它，產生的 sudoers 檔案就沒有效果，重新整理命令將會失敗。

在 Windows 上，提供者會將 觸發`refresh_command`為 SYSTEM 排程任務。

## 驗證安裝
<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 | 是 | — | 要為ExportCertificate呼叫擔任的 IAM 角色 ARN | 
| certificates[].certificate\_path | 是 | — | 寫入憑證檔案的絕對路徑 | 
| certificates[].private\_key\_path | 是 | — | 寫入私有金鑰檔案的絕對路徑 | 
| certificates[].chain\_path | 否 | — | 寫入憑證鏈的絕對路徑。如果省略，鏈會附加到 certificate\_path | 
| certificates[].refresh\_command | 否 | — | 憑證檔案更新後要執行的命令。必須是絕對路徑 | 
| certificates[].certificate\_and\_chain\_permission | 否 | 0600 | cert 和 chain 檔案的檔案許可 (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)。