本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
將 AWS AppConfig 代理程式搭配 Amazon EC2 和現場部署機器
您可以使用 AWS AppConfig 代理程式 AWS AppConfig 與在 Amazon 彈性運算雲端 (AmazonEC2) Linux 執行個體上執行的應用程式整合。代理程式可透過下列方式加強應用程式處理與管理:
-
代理程式 AWS AppConfig 會使用 AWS Identity and Access Management (IAM) 角色並管理組態資料的本機快取,代表您呼叫。藉由從本機快取提取組態資料,您的應用程式需要較少的程式碼更新來管理組態資料、擷取設定資料 (以毫秒為單位),而且不會受到可能中斷此類資料呼叫的網路問題影響。 *
-
代理程式提供擷取和解析 AWS AppConfig 功能旗標的原生體驗。
-
代理程式現成可提供快取策略、輪詢間隔以及本機組態資料可用性的最佳作法,同時追蹤後續服務呼叫所需的組態 Token。
-
在背景執行時,代理程式會定期輪詢 AWS AppConfig 資料平面以進行組態資料更新。您的應用程序可以通過連接到端口 2772 上的 localhost(可定制的默認端口值)並調用檢索數據來檢索數據HTTPGET來檢索數據。
*AWS AppConfig 代理程式會在服務第一次擷取您的組態資料時快取資料。因此,第一次檢索數據的調用比後續調用慢。
主題
步驟 1:(必要) 建立資源和設定權限
若要 AWS AppConfig 與 Amazon EC2 執行個體上執行的應用程式整合,您必須建立成 AWS AppConfig 品和組態資料,包括功能旗標或自由格式組態資料。如需詳細資訊,請參閱在中建立特徵旗標和任意格式組態資料 AWS AppConfig。
若要擷取由託管的組態資料 AWS AppConfig,您的應用程式必須設定為具有 AWS AppConfig 資料平面的存取權。若要授予應用程式存取IAM權,請更新指派給 Amazon EC2 執行個體角色的許可政策。具體而言,您必須將appconfig:StartConfigurationSession
和appconfig:GetLatestConfiguration
動作新增至策略。請見此處範例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "appconfig:StartConfigurationSession", "appconfig:GetLatestConfiguration" ], "Resource": "*" } ] }
如需有關新增權限至策略的詳細資訊,請參閱《IAM使用指南》中的新增和移除IAM身分識別權限。
步驟 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 執行個體上執行命令。此外,請參閱 Amazon EC2 Auto Scaling 使用者指南中的教學:設定使用者資料以透過執行個體中繼資料擷取目標生命週期狀態。
-
本主題中的程序說明如何透過登入執行個體來執行命令來執行安裝代理程式之類的動作。您可以從本機用戶端電腦執行命令,並使用 Run Command (功能) 來鎖定一或多個執行個體的目標 AWS Systems Manager。如需詳細資訊,請參閱 AWS Systems Manager 使用者指南中的 AWS Systems Manager 執行命令。
-
AWS AppConfig Amazon EC2 Linux 實例上的代理是一種
systemd
服務。
在執行個體上安裝和啟動 AWS AppConfig 代理程式
-
登入您的 Linux 執行個體。
-
開啟終端機,並以 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 代理程式,請
latest
在中取URL代為特定版本號碼。以下是 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
-
執行下列命令以啟動代理程式:
sudo systemctl start aws-appconfig-agent
-
執行下列命令以確認代理程式是否正在執行:
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 記錄檔
依預設, AWS AppConfig 代理程式會將記錄檔發佈到STDERR。Systemd 會將 Linux 執STDOUT行STDERR個體上執行的所有服務重新導向至 systemd 日誌。如果您只在一或兩個執行個體上執行 AWS AppConfig 代理程式,則可以在 systemd 日誌中檢視和管理記錄資料。更好的解決方案是我們強烈推薦用於分散式應用程式的解決方案,是將日誌檔寫入磁碟,然後使用 Amazon CloudWatch Agent 將日誌資料上傳到 AWS 雲端。此外,您可以設定 CloudWatch 代理程式刪除執行個體中的舊記錄檔,以防止執行個體磁碟空間不足。
若要啟用記錄到磁碟,您必須設定LOG_PATH
環境變數,如中所述步驟 4:(選用) 使用環境變數設定 Amazon 的 AWS AppConfig 代理程式 EC2。
若要開始使用 CloudWatch 代理程式,請參閱 Amazon 使用者指南中的代理 CloudWatch 程式從 Amazon EC2 執行個體和現場部署伺服器收集 CloudWatch 指標和日誌。您可以使用「快速設定」,這是一種「Systems Manager」功能來快速安裝 CloudWatch 代理程式。如需詳細資訊,請參閱AWS Systems Manager 使用指南中的快速設定主機管理。
警告
如果您選擇在不使用 CloudWatch 代理程式的情況下將記錄檔寫入磁碟,則必須刪除舊的記錄檔。 AWS AppConfig 代理程式會每小時自動輪換記錄檔。如果您未刪除舊的記錄檔,執行個體可能會耗盡磁碟空間。
在執行個體上安裝 CloudWatch 代理程式之後,請建立 CloudWatch 代理程式設定檔。組態檔會指示 CloudWatch 代理程式如何使用 AWS AppConfig 代理程式記錄檔。如需有關建立 CloudWatch 代理程式組態檔的詳細資訊,請參閱建立 CloudWatch 代理程式組態檔。
將下列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:(選用) 使用環境變數設定 Amazon 的 AWS AppConfig 代理程式 EC2
您可以使用環境變數為 Amazon EC2 設定 AWS AppConfig 代理程式。若要設定systemd
服務的環境變數,您可以建立嵌入式單位檔案。下列範例顯示如何建立插入式單元檔案,以將 AWS AppConfig 代理程式記錄層級設定為DEBUG
。
如何為環境變數建立下拉式單位檔案的範例
-
登入您的 Linux 執行個體。
-
開啟終端機,並以系統管理員權限執行下列命令。該命令創建一個配置目錄:
sudo mkdir /etc/systemd/system/aws-appconfig-agent.service.d
-
執行下列指令以建立置入式單元檔案。Replace (取代)
file_name
與文件的名稱。副檔名必須是.conf
:sudo touch /etc/systemd/system/aws-appconfig-agent.service.d/
file_name
.conf -
在下拉式單位檔案中輸入資訊。下列範例會新增定義環境變數的
Service
區段。此範例會將 AWS AppConfig 代理程式記錄層級設定為DEBUG
。[Service] Environment=LOG_LEVEL=DEBUG
-
執行下列命令以重新載入 systemd 組態:
sudo systemctl daemon-reload
-
執行下列命令以重新啟動 AWS AppConfig 代理程式:
sudo systemctl restart aws-appconfig-agent
您可以在插入式單元檔案中指定下列環境變數,以設定 Amazon EC2 的 AWS AppConfig 代理程式。
環境變數 | 詳細資訊 | 預設值 |
---|---|---|
|
此環境變數定義了從代理程式HTTP伺服器要求組態資料時必須提供的 Token。權杖的值必須在授權類型為的HTTP要求授權標頭中設定
|
無 |
|
此環境變數可讓 AWS AppConfig 代理程式將擷取之每個組態的備份儲存至指定目錄。 重要備份到磁碟的組態不會加密。如果您的配置包含敏感數據, AWS AppConfig 建議您使用文件系統權限實踐最低權限原則。如需詳細資訊,請參閱中的安全性 AWS AppConfig。 |
無 |
|
此環境變數指定代理程式HTTP伺服器執行所在的連接埠。 |
2772 |
|
此環境變數指定代理程式記錄的詳細資料層級。每個級別包括當前級別和所有更高級別。變量是區分大小寫的。從最詳細到最不詳細,記錄層級為: |
|
|
寫入記錄檔的磁碟位置。如果未指定,則會將記錄寫入 stderr。 |
無 |
|
此環境變數會設定 AWS AppConfig 代理程式,以利用額外的每個組態功能,例如多帳戶擷取,以及將組態儲存至磁碟。您可以輸入下列其中一個值:
如需這些功能的詳細資訊,請參閱使用資訊清單啟用其他擷取功能。 |
true |
|
此環境變數會設定代理程式用來擷取組態的連線數目上限。 AWS AppConfig |
3 |
|
此環境變數可控制代理程式輪詢 AWS AppConfig 更新組態資料的頻率。您可以指定間隔的秒數。您也可以指定帶有時間單位的數字:s 表示秒,m 表示分鐘,h 表示小時。如果未指定單位,則代理程式預設為秒。例如,60、60 和 1m 會產生相同的輪詢間隔。 |
四十五秒鐘 |
|
此環境變數會指定代理程式啟動時立即 AWS AppConfig 要求的組態資料。 |
無 |
|
如果設為 |
true |
PROXY_HEADERS |
此環境變數會指定環PROXY_URL 境變數中所參考 Proxy 所需的標頭。值是以逗號分隔的標頭清單。每個標題使用下面的形式。
|
無 |
PROXY_URL |
此環境變數指定URL要用於從代理程式到的連線的 Proxy AWS 服務,包括 AWS AppConfig。 HTTPS 並得HTTP URLs到支持。 |
無 |
|
此環境變數可控制代理程式等待回應的時間量。 AWS AppConfig如果服務沒有回應,請求就會失敗。 如果要求是用於初始資料擷取,則代理程式會將錯誤傳回給您的應用程式。 如果在背景檢查更新資料期間發生逾時,代理程式會記錄錯誤,並在短暫的延遲後再試一次。 您可以指定逾時的毫秒數。您也可以指定具有時間單位的數字:ms 表示毫秒,s 表示秒。如果未指定單位,則代理程式預設為毫秒。例如,5000、5000 毫秒和 5 秒會產生相同的要求逾時值。 |
三千毫秒 |
ROLE_ARN |
此環境變數指定IAM角色的 Amazon 資源名稱 (ARN)。 AWS AppConfig 代理程式會假設此角色來擷取組態資料。 | 無 |
ROLE_EXTERNAL_ID |
此環境變數會指定要與假定角色搭配使用的外部 ID ARN。 | 無 |
ROLE_SESSION_NAME |
此環境變數會指定要與假定IAM角色之認證相關聯的工作階段名稱。 | 無 |
SERVICE_REGION |
此環境變數會指定 AWS AppConfig 代理程式 AWS 區域 用來呼叫 AWS AppConfig 服務的替代方案。如果未定義,代理程式會嘗試判斷目前的「區域」。如果無法啟動,代理程式將無法啟動。 | 無 |
|
此環境變數會設定 AWS AppConfig 代理程式等到資訊清單處理完成後才完成啟動。 |
true |
步驟 5:(必要) 擷取組態資料
您可以使用HTTP本機主機呼叫,從 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 使用者資料。您可以將這些指令新增至執行個體或「EC2Auto 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