本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 執行具有管理員權限的主機組態指令碼
主機組態指令碼可讓您在服務受管機群工作者上執行管理任務，例如軟體安裝。這些指令碼會以更高的權限執行 (`sudo`在 上為 Linux，在 上為 管理員Windows)，讓您可以靈活地為系統設定工作者。
Deadline Cloud 會在工作者進入 `STARTING` 狀態之後，以及在執行任何任務之前執行指令碼。
**重要**
指令碼以更高的許可執行。您有責任確保指令碼不會造成任何安全問題。
當您使用主機組態指令碼時，您必須負責監控機群的運作狀態。
主機組態指令碼的常見用途包括：
+ 安裝需要管理員存取權的軟體
+ 安裝Docker容器
+ 安裝第三方雲端儲存解決方案，例如 LucidLink。如需逐步解說，請參閱適用於 M&E [的 部落格上的使用適用於截止日期雲端的服務受管機群指令碼設定 LucidLink](https://aws.amazon.com/blogs/media/set-up-lucidlink-with-service-managed-fleet-scripts-for-aws-deadline-cloud/)。 AWS
您可以使用 主控台或使用 建立和更新主機組態指令碼 AWS CLI。
------
#### [ Console ]
1. 在**機群詳細資訊**頁面上，選擇**組態**索引標籤。
1. 在**指令碼**欄位中，輸入要以更高許可執行的指令碼。您可以選擇**匯入**以從工作站載入指令碼。
1. 設定執行指令碼的逾時期間，以秒為單位。預設值為 300 秒 (5 分鐘)。
1. 選擇**儲存變更**以儲存指令碼。
------
#### [ Create with CLI ]
使用下列 AWS CLI 命令來建立具有主機組態指令碼的機群。將*預留位置*文字取代為您的資訊。
```
aws deadline create-fleet \
--farm-id farm-12345 \
--display-name "fleet-name" \
--max-worker-count 1 \
--configuration '{
"serviceManagedEc2": {
"instanceCapabilities": {
"vCpuCount": {"min": 2},
"memoryMiB": {"min": 4096},
"osFamily": "linux",
"cpuArchitectureType": "x86_64"
},
"instanceMarketOptions": {"type":"spot"}
}
}' \
--role-arn arn:aws:iam::111122223333:role/role-name \
--host-configuration '{ "scriptBody": "script body", "scriptTimeoutSeconds": timeout value}'
```
------
#### [ Update with CLI ]
使用下列 AWS CLI 命令來更新機群的主機組態指令碼。將*預留位置*文字取代為您的資訊。
```
aws deadline update-fleet \
--farm-id farm-12345 \
--fleet-id fleet-455678 \
--host-configuration '{ "scriptBody": "script body", "scriptTimeoutSeconds": timeout value}'
```
------
下列指令碼示範：
+ 指令碼可用的環境變數
+ 該 AWS 登入資料正在 shell 中運作
+ 指令碼正在提升的 shell 中執行
------
#### [ Linux ]
使用下列指令碼來顯示指令碼正在執行並具有 `root` 權限：
```
# Print environment variables
set
# Check AWS Credentials
aws sts get-caller-identity
```
------
#### [ Windows ]
使用下列PowerShell指令碼來顯示指令碼正在以管理員權限執行：
```
Get-ChildItem env: | ForEach-Object { "$($_.Name)=$($_.Value)" }
aws sts get-caller-identity
function Test-AdminPrivileges {
$currentUser = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
$isAdmin = $currentUser.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
return $isAdmin
}
if (Test-AdminPrivileges) {
Write-Host "The current PowerShell session is elevated (running as Administrator)."
} else {
Write-Host "The current PowerShell session is not elevated (not running as Administrator)."
}
exit 0
```
------
## 主機組態指令碼故障診斷
當您執行主機組態指令碼時：
+ 成功時：工作者執行任務
+ 失敗時 （非零結束碼或當機）：
+ 工作者關閉
機群會使用最新的主機組態指令碼自動啟動新的工作者
若要監控指令碼：
1. 在截止日期雲端主控台中開啟機群頁面。
1. 選擇**檢視工作者**以開啟截止日期雲端監視器。
1. 在監控頁面中檢視工作者狀態。
**提示**
測試主機組態指令碼時，請將機群的最大工作者計數設定為 1，以避免在指令碼上反覆運算時啟動多個工作者。
重要說明：
+ 因錯誤而關閉的工作者無法在監視器中的工作者清單中使用。使用 CloudWatch Logs 在下列日誌群組中檢視工作者日誌：
```
/aws/deadline/farm-XXXXX/fleet-YYYYY
```
在該日誌群組中，尋找名為 的串流`worker-ZZZZZ`。
+ CloudWatch Logs 會根據您設定的保留期間來保留工作者日誌。
### 監控主機組態指令碼執行
透過主機組態指令碼，您可以完全控制截止日期雲端工作者。您可以安裝任何軟體套件、重新設定作業系統參數，或掛載共用檔案系統。透過此進階功能和 Deadline Cloud 擴展到數千個工作者的能力，您可以監控組態指令碼何時成功執行或失敗。
我們建議您使用下列解決方案來監控主機組態指令碼執行。
#### CloudWatch Logs 監控
所有機群主機組態日誌都會串流到機群的 CloudWatch 日誌群組，特別是工作者的 CloudWatch 日誌串流。例如， `/aws/deadline/farm-123456789012/fleet-777788889999`是陣列 `123456789012`、機群 的日誌群組`777788889999`。
每個工作者都會佈建專用日誌串流，例如 `worker-123456789012`。主機組態日誌包含日誌橫幅，例如*執行主機組態指令碼*和*完成執行主機組態指令碼，結束程式碼：0*。指令碼的結束程式碼包含在完成的橫幅中，可以使用 CloudWatch 工具進行查詢。
#### CloudWatch Logs 洞察
CloudWatch Logs Insights 提供進階功能來分析日誌資訊。例如，下列 Log Insights 查詢剖析主機組態結束程式碼，依時間排序：
```
fields @timestamp, @message, @logStream, @log
| filter @message like /Finished running Host Configuration Script/
| parse @message /exit code: (?\d+)/
| display @timestamp, exit_code
| sort @timestamp desc
```
如需有關 CloudWatch Logs Insights 的詳細資訊，請參閱《Amazon CloudWatch Logs 使用者指南**》中的[使用 CloudWatch Logs Insights 分析日誌資料](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)。
##### 工作者客服人員結構化記錄
Deadline Cloud 的工作者代理程式會將結構化 JSON 日誌發佈至 CloudWatch。工作者代理程式提供各種結構化日誌，用於分析工作者運作狀態。如需詳細資訊，請參閱 GitHub [上的截止日期雲端工作者代理程式記錄](https://github.com/aws-deadline/deadline-cloud-worker-agent/blob/mainline/docs/logging.md)。
結構化日誌的屬性會解壓縮至 Log Insights 中的欄位。您可以使用此 CloudWatch 功能來計算和分析主機組態啟動失敗。例如，計數和 bin 查詢可用來判斷失敗發生的頻率：
```
fields @timestamp, @message, @logStream, @log
| sort @timestamp desc
| filter message like /Worker Agent host configuration failed with exit code/
| stats count(*) by exit_code, bin(1h)
```
#### 指標和警示的 CloudWatch 指標篩選條件
您可以設定 CloudWatch 指標篩選條件，從日誌產生 CloudWatch 指標。指標篩選條件可讓您建立警示和儀表板，以監控主機組態指令碼執行。
**建立指標篩選條件**
1. 開啟 CloudWatch 主控台。
1. 在導覽窗格中，選擇**日誌**，然後選擇**日誌群組**。
1. 選取機群的日誌群組。
1. 選擇 **Create metric filter (建立指標篩選條件)**。
1. 使用下列其中一項定義您的篩選條件模式：
+ **對於成功指標：**
```
{$.message = "*Worker Agent host configuration succeeded.*"}
```
+ **對於失敗指標：**
```
{$.exit_code != 0 && $.message = "*Worker Agent host configuration failed with exit code*"}
```
1. 選擇**下一步**以建立具有下列值的指標：
+ **指標命名空間：**您的指標命名空間 （例如 **MyDeadlineFarm**)
+ **指標名稱：**您請求的指標名稱 （例如 **host\$1config\$1failure**)
+ **指標值：** **1** （每個執行個體的計數為 1)
+ **預設值：**保留空白
+ **單位：** **Count**
建立指標篩選條件後，您可以設定標準 CloudWatch 警示，以針對更高的主機組態失敗率採取動作，或將指標新增至 CloudWatch 儀表板以進行day-to-day操作和監控。
如需詳細資訊，請參閱《*Amazon CloudWatch Logs 使用者指南*》中的[篩選和模式語法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html)。