本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 搭配 Amazon EC2 和內部部署機器使用 AWS AppConfig 代理程式
您可以使用 AWS AppConfig 代理程式 AWS AppConfig ，與在 Amazon Elastic Compute Cloud (Amazon EC2) Linux 執行個體上執行的應用程式整合。代理程式會以下列方式增強應用程式處理和管理：
+ 客服人員會使用 AWS Identity and Access Management (IAM) 角色 AWS AppConfig 來代表您呼叫 ，並管理組態資料的本機快取。透過從本機快取提取組態資料，您的應用程式需要較少的程式碼更新來管理組態資料、在幾毫秒內擷取組態資料，並且不受可能中斷對此類資料呼叫的網路問題影響。\*
+ 代理程式為擷取和解析 AWS AppConfig 功能旗標提供原生體驗。
+ 代理程式現成提供快取策略、輪詢間隔和本機組態資料的可用性的最佳實務，同時追蹤後續服務呼叫所需的組態字符。
+ 在背景執行時，代理程式會定期輪詢 AWS AppConfig 資料平面以進行組態資料更新。您的應用程式可以透過連線至連接埠 2772 上的 localhost （可自訂的預設連接埠值） 並呼叫 HTTP GET 來擷取資料來擷取資料。
\*AWS AppConfig 當服務第一次擷取您的組態資料時，代理程式會快取資料。因此，擷取資料的第一個呼叫比後續呼叫慢。
**Topics**
+ [步驟 1：（必要） 建立資源並設定許可](#appconfig-integration-ec2-resources-and-permissions)
+ [步驟 2：（必要） 在 Amazon EC2 執行個體上安裝和啟動 AWS AppConfig 代理程式](#appconfig-integration-ec2-installing)
+ [步驟 3：（選用，但建議） 將日誌檔案傳送至 CloudWatch Logs](#appconfig-integration-ec2-logs)
+ [步驟 4：（選用） 使用環境變數來設定 AWS AppConfig Agent for Amazon EC2](#appconfig-integration-ec2-configuring)
+ [步驟 5：（必要） 擷取組態資料](#appconfig-integration-ec2-retrieving-data)
+ [步驟 6 （選用，但建議）：自動更新至 AWS AppConfig 代理程式](#appconfig-integration-ec2-updating-agent)
## 步驟 1：（必要） 建立資源並設定許可
若要 AWS AppConfig 與在 Amazon EC2 執行個體上執行的應用程式整合，您必須建立 AWS AppConfig 成品和組態資料，包括功能旗標或自由格式組態資料。如需詳細資訊，請參閱[在 中建立功能旗標和自由格式組態資料 AWS AppConfig](creating-feature-flags-and-configuration-data.md)。
若要擷取由 託管的組態資料 AWS AppConfig，您的應用程式必須設定為可存取 AWS AppConfig 資料平面。若要授予應用程式存取權，請更新指派給 Amazon EC2 執行個體角色的 IAM 許可政策。具體而言，您必須將 `appconfig:StartConfigurationSession`和 `appconfig:GetLatestConfiguration`動作新增至政策。請見此處範例：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"appconfig:StartConfigurationSession",
"appconfig:GetLatestConfiguration"
],
"Resource": "*"
}
]
}
```
------
如需將許可新增至政策的詳細資訊，請參閱《[IAM 使用者指南》中的新增和移除 IAM 身分許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 **
## 步驟 2：（必要） 在 Amazon EC2 執行個體上安裝和啟動 AWS AppConfig 代理程式
AWS AppConfig 代理程式託管在由 管理的 Amazon Simple Storage Service (Amazon S3) 儲存貯體中 AWS。使用下列程序在您的 Linux 執行個體上安裝最新版本的 代理程式。如果您的應用程式分散在多個執行個體，則必須在每個託管應用程式的執行個體上執行此程序。
**注意**
記下以下資訊：
AWS AppConfig 代理程式適用於執行核心版本 4.15 或更新版本的 Linux 作業系統。不支援以 Debian 為基礎的系統，例如 Ubuntu。
代理程式支援 x86\_64 和 ARM64 架構。
對於分散式應用程式，我們建議您將安裝和啟動命令新增至 Auto Scaling 群組的 Amazon EC2 使用者資料。如果您這樣做，每個執行個體會自動執行命令。如需詳細資訊，請參閱《*Amazon EC2 使用者指南*》中的[在啟動時在 Linux 執行個體上執行命令](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html)。此外，請參閱《*Amazon EC2 Auto Scaling 使用者指南*》中的[教學課程：設定使用者資料以透過執行個體中繼資料擷取目標生命週期狀態](https://docs.aws.amazon.com/autoscaling/ec2/userguide/tutorial-lifecycle-hook-instance-metadata.html)。
本主題中的程序說明如何透過登入執行個體來執行 命令來執行安裝代理程式等動作。您可以從本機用戶端機器執行命令，並使用 Run Command 鎖定一或多個執行個體，這是其中的工具 AWS Systems Manager。如需詳細資訊，請參閱 *AWS Systems Manager 使用者指南*中的 [AWS Systems Manager 執行命令](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html)。
AWS AppConfig Amazon EC2 Linux 執行個體上的代理程式是一項`systemd`服務。
**在執行個體上安裝和啟動 AWS AppConfig 代理程式**
1. 登入您的 Linux 執行個體。
1. 開啟終端機，並使用管理員許可執行下列其中一個命令：
**x86\_64**
```
sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/latest/aws-appconfig-agent.rpm
```
**ARM64**
```
sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/arm64/latest/aws-appconfig-agent.rpm
```
如果您想要安裝特定版本的 AWS AppConfig 代理程式，請以特定版本編號取代 URL `latest` 中的 。以下是 x86\_64 的範例：
```
sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/2.0.2/aws-appconfig-agent.rpm
```
1. 執行下列命令來啟動代理程式：
```
sudo systemctl start aws-appconfig-agent
```
1. 執行下列命令來驗證代理程式是否正在執行：
```
sudo systemctl status aws-appconfig-agent
```
如果成功，命令會傳回如下資訊：
```
aws-appconfig-agent.service - aws-appconfig-agent
...
Active: active (running) since Mon 2023-07-26 00:00:00 UTC; 0s ago
...
```
**注意**
若要停用代理程式，請執行下列命令：
```
sudo systemctl stop aws-appconfig-agent
```
## 步驟 3：（選用，但建議） 將日誌檔案傳送至 CloudWatch Logs
根據預設， AWS AppConfig Agent 會將日誌發佈至 STDERR。系統化會將 Linux 執行個體上執行之所有服務的 STDOUT 和 STDERR 重新導向至系統化日誌。如果您僅在一或兩個執行個體上執行 AWS AppConfig 代理程式，則可以在系統日誌中檢視和管理日誌資料。我們強烈建議分散式應用程式使用更好的解決方案是將日誌檔案寫入磁碟，然後使用 Amazon CloudWatch 代理程式將日誌資料上傳至 AWS 雲端。此外，您可以設定 CloudWatch 代理程式從執行個體中刪除舊日誌檔案，以防止執行個體用盡磁碟空間。
若要啟用記錄到磁碟，您必須設定`LOG_PATH`環境變數，如中所述[步驟 4：（選用） 使用環境變數來設定 AWS AppConfig Agent for Amazon EC2](#appconfig-integration-ec2-configuring)。
若要開始使用 CloudWatch 代理程式，請參閱《[Amazon CloudWatch 使用者指南》中的使用 CloudWatch 代理程式從 Amazon EC2 執行個體和內部部署伺服器收集指標和日誌 CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。 *Amazon CloudWatch * 您可以使用快速設定，這是 Systems Manager 中的工具，可快速安裝 CloudWatch 代理程式。如需詳細資訊，請參閱*AWS Systems Manager 《 使用者指南*》中的[快速設定主機管理](https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-host-management.html)。
**警告**
如果您選擇不使用 CloudWatch 代理程式將日誌檔案寫入磁碟，則必須刪除舊的日誌檔案。 AWS AppConfig 代理程式會每小時自動輪換日誌檔案。如果您不刪除舊的日誌檔案，您的執行個體可能會用盡磁碟空間。
在執行個體上安裝 CloudWatch 代理程式後，請建立 CloudWatch 代理程式組態檔案。組態檔案會指示 CloudWatch 代理程式如何使用 AWS AppConfig 代理程式日誌檔案。如需建立 CloudWatch 代理程式組態檔案的詳細資訊，請參閱[建立 CloudWatch 代理程式組態檔案](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file.html)。
將下列`logs`區段新增至執行個體上的 CloudWatch 代理程式組態檔案，並儲存您的變更：
```
"logs": {
"logs_collected": {
"files": {
"collect_list": [
{
"file_path": "/{{path_you_specified_for_logging}}",
"log_group_name": "${{{YOUR_LOG_GROUP_NAME}}}/aws-appconfig-agent.log",
"auto_removal": true
},
...
]
},
...
},
...
}
```
如果 的值`auto_removal`為 `true`，CloudWatch 代理程式會自動刪除輪換的 AWS AppConfig 代理程式日誌檔案。
## 步驟 4：（選用） 使用環境變數來設定 AWS AppConfig Agent for Amazon EC2
您可以使用環境變數來設定 Amazon EC2 的 AWS AppConfig Agent。若要設定`systemd`服務的環境變數，請建立插入式單位檔案。下列範例示範如何建立插入式單位檔案，將 AWS AppConfig 客服人員記錄層級設定為 `DEBUG`。
**如何為環境變數建立捨入單位檔案的範例**
1. 登入您的 Linux 執行個體。
1. 開啟終端機，並使用管理員許可執行下列命令。命令會建立組態目錄：
```
sudo mkdir /etc/systemd/system/aws-appconfig-agent.service.d
```
1. 執行下列命令來建立插入式單位檔案。以檔案的名稱取代 {{file\_name}}。延伸模組必須是 `.conf`：
```
sudo touch /etc/systemd/system/aws-appconfig-agent.service.d/{{file_name}}.conf
```
1. 在插入式單位檔案中輸入資訊。下列範例會新增定義 環境變數的`Service`區段。此範例會將 AWS AppConfig 客服人員日誌層級設定為 `DEBUG`。
```
[Service]
Environment=LOG_LEVEL=DEBUG
```
1. 執行下列命令以重新載入系統化組態：
```
sudo systemctl daemon-reload
```
1. 執行下列命令以重新啟動 AWS AppConfig Agent：
```
sudo systemctl restart aws-appconfig-agent
```
您可以在插入式單位檔案中指定下列環境變數，以設定 Amazon EC2 的 AWS AppConfig Agent。
**注意**
下表包含**範例值**欄。根據您的監視器解析度，您可能需要捲動至資料表底部，然後向右捲動以檢視資料欄。
****
| 環境變數 | 詳細資訊 | 預設值 | 範例值 (s) |
| --- | --- | --- | --- |
| `ACCESS_TOKEN` | 此環境變數定義從代理程式 HTTP 伺服器請求組態資料時必須提供的字符。字符的值必須在 HTTP 請求授權標頭中設定，授權類型為 `Bearer`。請見此處範例。GET /applications/my_app/...
Host: localhost:2772
Authorization: Bearer
| 無 | MyAccessToken |
| `BACKUP_DIRECTORY` | 此環境變數可讓 AWS AppConfig 客服人員將擷取的每個組態備份儲存至指定的目錄。 備份到磁碟的組態不會加密。如果您的組態包含敏感資料， AWS AppConfig 建議您使用檔案系統許可來實作最低權限原則。如需詳細資訊，請參閱[中的安全性 AWS AppConfig](appconfig-security.md)。 | 無 | /path/to/backups |
| `HTTP_PORT` | 此環境變數會指定代理程式 HTTP 伺服器執行所在的連接埠。 | 2772 | 2772 |
| `HTTP_HOST` | HTTP\_HOST 變數控制 AWS AppConfig 代理程式如何繫結至網路介面。繫結行為會根據執行時間環境而有所不同，以確保最佳安全性和可存取性。 | ECS、EKS [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/appconfig/latest/userguide/appconfig-integration-ec2.html)
EC2 和內部部署[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/appconfig/latest/userguide/appconfig-integration-ec2.html) | 自訂組態選項。您可以使用這些值覆寫預設行為：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/appconfig/latest/userguide/appconfig-integration-ec2.html) |
| `LOG_LEVEL` | 此環境變數會指定代理程式所記錄的詳細資訊層級。每個關卡都包含目前關卡和所有更高關卡。此值不區分大小寫。從最詳細到最不詳細，日誌層級為：`trace`、`debug`、`info`、`warn``error`、`fatal`、 和 `none`。`trace` 日誌包含有關代理程式的詳細資訊，包括時間資訊。 | info | 追蹤
偵錯
info
警告
error
嚴重
無 |
| `LOG_PATH` | 寫入日誌的磁碟位置。如果未指定，日誌會寫入 stderr。 | 無 | /path/to/logs/agent.log |
| `MANIFEST` | 此環境變數會設定 AWS AppConfig 代理程式，以利用其他每個組態的功能，例如多帳戶擷取，並將組態儲存至磁碟。如需這些功能的詳細資訊，請參閱[使用資訊清單來啟用其他擷取功能](appconfig-agent-how-to-use-additional-features.md)。 | 無 | 使用 AWS AppConfig 組態做為資訊清單時：`MyApp:MyEnv:MyManifestConfig`。
從磁碟載入資訊清單時： `file:/path/to/manifest.json` |
| `MAX_CONNECTIONS` | 此環境變數會設定代理程式用來從中擷取組態的連線數目上限 AWS AppConfig。 | 3 | 3 |
| `POLL_INTERVAL` | 此環境變數控制代理程式輪詢 AWS AppConfig 更新組態資料的頻率。您可以指定間隔的秒數。您也可以指定具有時間單位的數字：秒為 s，分鐘為 m，小時為 h。如果未指定單位，代理程式預設為 秒。例如，60、60 和 1 公尺會產生相同的輪詢間隔。 | 45 秒 | 45
45 秒
5m
1h |
| `PREFETCH_LIST` | 此環境變數會在代理程式啟動 AWS AppConfig 時指定代理程式請求的組態資料。逗號分隔清單中可能會提供多個組態識別符。 | 無 | MyApp：MyEnv：MyConfig
abcd123：efgh456：ijkl789
MyApp：MyEnv：Config1，MyApp：MyEnv：Config2 |
| `PRELOAD_BACKUPS` | 如果設定為 `true`， AWS AppConfig 代理程式會將 中找到的組態備份載入`BACKUP_DIRECTORY`記憶體，並立即檢查服務是否存在較新的版本。如果設定為 `false`， AWS AppConfig 代理程式只會在無法從服務擷取組態資料時，從組態備份載入內容，例如您的網路發生問題時。 | true | true
false |
| PROXY\_HEADERS | 此環境變數會指定PROXY\_URL環境變數中參考的代理所需的標頭。值是以逗號分隔的標頭清單。 | 無 | 標頭：值
h1：v1、h2：v2 |
| PROXY\_URL | 此環境變數會指定代理程式連線所用的代理 URL AWS 服務，包括支援 AWS AppConfigHTTPS和 HTTP URL。 URLs | 無 | http：//localhost：7474
https://my-proxy.example.com |
| `REQUEST_TIMEOUT` | 此環境變數控制代理程式等待回應的時間長度 AWS AppConfig。如果服務未回應，請求會失敗。
如果請求是用於初始資料擷取，代理程式會傳回錯誤到您的應用程式。
如果在更新資料的背景檢查期間發生逾時，代理程式會記錄錯誤，並在短暫延遲後重試。
您可以指定逾時的毫秒數。您也可以指定具有時間單位的數字：毫秒為 毫秒，秒為 。如果未指定單位，代理程式預設為毫秒。例如，5000、5000ms 和 5s 會產生相同的請求逾時值。 | 3000 毫秒 | 3000
3000 毫秒
5 秒 |
| ROLE\_ARN | 此環境變數指定 IAM 角色的 Amazon Resource Name (ARN)。 AWS AppConfig 代理程式會擔任此角色來擷取組態資料。 | 無 | arn：aws：iam：：123456789012：role/MyRole |
| ROLE\_EXTERNAL\_ID | 此環境變數會指定要與擔任的角色 ARN 搭配使用的外部 ID。 | 無 | MyExternalId |
| ROLE\_SESSION\_NAME | 此環境變數會指定要與擔任 IAM 角色的登入資料建立關聯的工作階段名稱。 | 無 | AWSAppConfigAgentSession |
| SERVICE\_REGION | 此環境變數指定 AWS 區域 代理程式用來呼叫 AWS AppConfig 服務的替代方案 AWS AppConfig 。如果未定義，代理程式會嘗試判斷目前的區域。如果無法啟動，則代理程式無法啟動。 | 無 | us-east-1
eu-west-1 |
| `WAIT_ON_MANIFEST` | 此環境變數會將 AWS AppConfig 代理程式設定為等到資訊清單處理完畢再完成啟動。 | true | true
false |
## 步驟 5：（必要） 擷取組態資料
您可以使用 HTTP localhost 呼叫從 AWS AppConfig 代理程式擷取組態資料。下列範例使用 `curl`搭配 HTTP 用戶端。您可以使用應用程式語言或可用程式庫支援的任何可用 HTTP 用戶端來呼叫代理程式，包括 AWS SDK。
** 擷取任何已部署組態的完整內容**
```
$ curl "http://localhost:2772/applications/{{application_name}}/environments/{{environment_name}}/configurations/{{configuration_name}}"
```
**從 AWS AppConfig 類型的組態擷取單一旗標及其屬性 `Feature Flag`**
```
$ curl "http://localhost:2772/applications/{{application_name}}/environments/{{environment_name}}/configurations/{{configuration_name}}?flag={{flag_name}}"
```
**從 類型的組態存取多個旗標及其屬性 AWS AppConfig `Feature Flag`**
```
$ curl "http://localhost:2772/applications/{{application_name}}/environments/{{environment_name}}/configurations/{{configuration_name}}?flag={{flag_name_one}}&flag={{flag_name_two}}"
```
## 步驟 6 （選用，但建議）：自動更新至 AWS AppConfig 代理程式
AWS AppConfig 代理程式會定期更新。為了確保您在執行個體上執行最新版本的 AWS AppConfig 代理程式，建議您將下列命令新增至 Amazon EC2 使用者資料。您可以將命令新增至執行個體或 EC2 Auto Scaling 群組上的使用者資料。每次執行個體啟動或重新啟動時，指令碼都會安裝並啟動最新版本的代理程式。
```
#!/bin/bash
# install the latest version of the agent
yum install -y https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/latest/aws-appconfig-agent.rpm
# optional: configure the agent
mkdir /etc/systemd/system/aws-appconfig-agent.service.d
echo "${{{MY_AGENT_CONFIG}}}" > /etc/systemd/system/aws-appconfig-agent.service.d/overrides.conf
systemctl daemon-reload
# start the agent
systemctl start aws-appconfig-agent
```