演練:建立執行 MOF 檔案的關聯 - AWS Systems Manager

演練:建立執行 MOF 檔案的關聯

透過使用 AWS-ApplyDSCMofs SSM 文件,您可以利用 State Manager (AWS Systems Manager 的一個功能) 來執行受管物件格式 (MOF) 檔案,在 Windows Server 受管執行個體上強制達成所要的狀態。AWS-ApplyDSCMofs 文件有兩種執行模式。運用第一種模式,您可以設定關聯,以便掃描並報告受管執行個體是否處於指定 MOF 檔案中定義的所需狀態。在第二種模式中,您可以執行 MOF 檔案,並根據資源和 MOF 檔案中所定義的資源值,來變更您執行個體的組態。AWS-ApplyDSCMofs 文件允許您從 Amazon Simple Storage Service (Amazon S3)、本機共用、或具有 HTTPS 網域的安全網站中下載和執行 MOF 組態檔案。

State Manager記錄和報告每個 MOF 檔案執行在每個關聯執行期間的狀態。State Manager也將每個 MOF 檔案執行的輸出以合規事件報告,您可在 AWS Systems Manager 合規頁面中檢視。

MOF 檔案執行建構於 Windows PowerShell Desired State Configuration (PowerShell DSC)。PowerShell DSC 是一個宣告式平台,用於設定、部署和管理 Windows 系統。PowerShell DSC 可讓管理員以稱為 DSC 設定的簡單文字文件,描述想要如何設定伺服器。PowerShell DSC 設定是一種特殊的 PowerShell 指令碼,用於說明要做什麼,而非做法。執行設定會產生一份 MOF 檔案。MOF 檔案可套用到一或多個伺服器,以達到伺服器所需的設定。PowerShell DSC 資源負責強制執行設定。如需詳細資訊,請參閱 Windows PowerShell Desired State Configuration 概觀

使用 Amazon S3 存放成品

如果您使用 Amazon S3 存放 PowerShell 模組、MOF 檔案、合規報告或狀態報告,則 AWS Systems Manager SSM Agent 使用的 AWS Identity and Access Management (IAM) 角色必須擁有儲存貯體的 GetObjectListBucket 許可。如果您不提供這些許可,系統會傳回 Access Denied (存取遭拒) 錯誤。以下是有關在 Amazon S3 中存放成品的重要資訊。

  • 如果儲存貯體位於不同的 AWS 帳戶,則您必須建立授予帳戶 (或 IAM 角色) GetObjectListBucket 許可的儲存貯體資源政策。

  • 如果您想要使用自訂的 DSC 資源,您可以從 Amazon S3 儲存貯體下載這些資源。您也可以從 PowerShell gallery 自動進行安裝。

  • 如果您使用 Amazon S3 作為模組來源,請以下列區分大小寫的格式上傳模組的 Zip 檔:ModuleName_ModuleVersion.zip。例如:MyModule_1.0.0.zip。

  • 所有檔案必須位於儲存貯體的根資料夾。不支援資料夾結構。

在 MOF 檔案解析登入資料

登入資料是透過使用 AWS Secrets ManagerAWS Systems ManagerParameter Store解析。這可讓您設定自動登入資料輪換。這也允許 DSC 將憑證自動傳播到您的伺服器,無需重新部署 MOF。

若要在組態中使用 AWS Secrets Manager 機密,請建立 PSCredential 物件,其中使用者名稱為包含憑證的機密的 SecretId 或 SecretARN。您可以為密碼指定任何值。值會被忽略。以下是範例。

Configuration MyConfig { $ss = ConvertTo-SecureString -String 'a_string' -AsPlaintext -Force $credential = New-Object PSCredential('a_secret_or_ARN', $ss) Node localhost { File file_name { DestinationPath = 'C:\MyFile.txt' SourcePath = '\\FileServer\Share\MyFile.txt' Credential = $credential } } }

使用組態資料中的 PsAllowPlaintextPassword 設定編譯您的 MOF。這是可行的,因為登入資料只會包含標記。

在 Secrets Manager 中,確保執行個體在 IAM 受管政策中,以及選擇性在機密資源政策 (如有的話) 中擁有 GetSecretValue 存取權限。如要使用 DSC,秘密的格式必須如下。

{ 'Username': 'a_name', 'Password': 'a_password' }

機密可以具有其他屬性 (例如,用於輪換的屬性),但必須至少具有使用者名稱和密碼屬性。

建議您採用多使用者輪換的方法,可讓您擁有兩個不同的使用者名稱和密碼,而輪換 AWS Lambda 函數會在它們之間翻轉。這個方法可讓您擁有多個作用中的帳戶,同時排除在輪換時鎖定使用者的風險。

在 MOF 檔案使用字符

字符讓您能夠在 MOF 編譯完成,修改資源屬性值。這允許您在需要類似組態的多個伺服器上重複使用常見的 MOF 檔案。

字符替換僅適用於 String (字串) 類型的資源屬性。然而,如果您的資源擁有巢狀 CIM 執行個體屬性,其也會從該 CIM 執行個體中的 String 屬性解析字符。您無法在數字或陣列使用字符替換。

例如,假設您使用的是 xComputerManagement 資源,而您想要使用 DSC 重新命名電腦。一般而言,您需要擁有該機器專用的 MOF 檔案。然而,有了字符支援,您可以建立一個 MOF 檔案並套用到所有執行個體。在 ComputerName 屬性中,您不需要將電腦名稱硬編碼至 MOF,只需要使用執行個體標籤類型字符。值會在 MOF 剖析時進行解析。請參閱以下範例。

Configuration MyConfig { xComputer Computer { ComputerName = '{tag:ComputerName}' } }

接著,在 Systems Manager 主控台中的受管執行個體上設定標籤,或是在 Amazon EC2 主控台中設定 Amazon Elastic Compute Cloud (Amazon EC2) 標籤。當您執行文件時,指令碼會替換執行個體標籤值的 {tag:ComputerName} 字符。

您也可以在單一屬性結合多個標籤,如下例中所示。

Configuration MyConfig { File MyFile { DestinationPath = '{env:TMP}\{tag:ComputerName}' Type = 'Directory' } }

您可以使用五種不同類型的字符:

  • tag:Amazon EC2 或受管執行個體標籤。

  • tagb64:與 tag 相同,但系統使用 base64 來將值解碼。這可讓您在標籤值使用特殊字元。

  • env:解析環境變數。

  • ssm:Parameter Store 值。僅支援 String 和 Secure String 類型。

  • tagssm:與標籤相同,但如果執行個體上未設定該標籤,系統會嘗試從具有相同名稱的 Systems Manager 參數中解析該值。當您想要擁有「預設全域值」,但希望能在單一執行個體 (例如 one-box 部署) 上進行覆寫時,這是非常實用的。

以下是使用 ssm 字符類型的 Parameter Store 範例。

File MyFile { DestinationPath = "C:\ProgramData\ConnectionData.txt" Content = "{ssm:%servicePath%/ConnectionData}" }

字符可讓 MOF 檔案變成泛型和可重複使用,在減少冗餘的程式碼上扮演重要角色。如果您可以避開伺服器特定的 MOF 檔案,則不需要 MOF 建置服務。MOF 建置服務會增加成本,減緩佈建速度,並提高執行個體群組之間組態不一致的風險,因為在編譯 MOF 時,會在建置伺服器上安裝不同的模組版本。

Prerequisites

建立執行 MOF 檔案的關聯之前,確認您的受管執行個體已安裝下列先決條件:

建立執行 MOF 檔案的關聯

建立會執行 MOF 檔案的關聯

  1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的 主控台。https://console.aws.amazon.com/systems-manager/

  2. 在導覽窗格中,選擇 State Manager

    -或-

    如果 AWS Systems Manager 首頁先開啟,選擇選單圖示 ( ) 以開啟導覽窗格,然後選擇 State Manager

  3. 選擇 State Manager,然後選擇 Create association (建立關聯)。

  4. Name (名稱) 欄位中指定名稱。此為選用操作,但建議您採用。名稱可協助您了解所建立關聯的目的。名稱中不得使用空格。

  5. Document (文件) 清單中,請選擇 AWS-ApplyDSCMofs

  6. Parameters (參數) 區段中,指定您對所需和選用輸入參數的選擇。

    1. Mofs To Apply (要套用的 MOF):指定一或多個執行此關聯時要執行的 MOF 檔案。使用逗號來分隔 MOF 檔案清單。您可以指定以下用來找出 MOF 檔案的選項:

      • Amazon S3 儲存貯體名稱。儲存貯體名稱必須使用小寫字母。使用以下格式指定此資訊。

        s3:doc-example-bucket:MOF_file_name.mof

        如果您想要指定 AWS 區域,則使用以下格式。

        s3:bucket_Region:doc-example-bucket:MOF_file_name.mof
      • 一個安全網站。使用以下格式指定此資訊。

        https://domain_name/MOF_file_name.mof

        請見此處範例。

        https://www.example.com/TestMOF.mof
      • 在本機共享的檔案系統。使用以下格式指定此資訊。

        \server_name\shared_folder_name\MOF_file_name.mof

        請見此處範例。

        \StateManagerAssociationsBox\MOFs_folder\MyMof.mof
    2. Service Path (服務路徑):(選用) 服務路徑可以是您想要寫入報告和狀態資訊的 Amazon S3 儲存貯體字首。或是Parameter Store參數基礎標籤的路徑。解析參數基礎標籤時,系統會使用 {ssm:%servicePath%/parameter_name},將 servicePath 值注入參數名稱。例如,如果您的服務路徑為「WebServers/Production」,則系統會將參數解析為:WebServers/Production/parameter_name。當您在相同帳戶中執行多個環境時,這是非常實用的。

    3. Report Bucket Name (報告儲存貯體名稱):(選用) 輸入您想要寫入合規資料的 Amazon S3 儲存貯體名稱。報告會以 JSON 格式儲存在這個儲存貯體中。

      注意

      您可以根據儲存貯體的所在區域,為儲存貯體名稱加上以區域為名的字首。例如:us-west-2:MyMOFBucket。如果您在 us-east-1 以外的特定區域中使用 Amazon S3 端點的代理,則應為儲存貯體名稱加上以區域為名的字首。如果儲存貯體名稱未包含字首,則可透過使用 us-east-1 端點自動探索儲存貯體區域。

    4. Mof Operation Mode (Mof 操作模式):執行 AWS-ApplyDSCMofs 關聯時選擇 State Manager 行為:

      • Apply (套用):修正不合規的執行個體組態。

      • ReportOnly (僅報告):不修正執行個體組態,但記錄所有合規資料並回報不合規的執行個體。

    5. Status Bucket Name (狀態儲存貯體名稱):(選用) 輸入您想要寫入 MOF 執行狀態資訊的 Amazon S3 儲存貯體名稱。這些狀態報告是執行個體最近一次合規執行的單一摘要。這表示,報告會在關聯下一次執行 MOF 檔案時遭到覆寫。

      注意

      您可以根據儲存貯體的所在區域,為儲存貯體名稱加上以區域為名的字首。範例如下:us-west-2:doc-example-bucket。如果您在 us-east-1 以外的特定區域中使用 Amazon S3 端點的代理,則應為儲存貯體名稱加上以區域為名的字首。如果儲存貯體名稱未包含字首,則會使用 us-east-1 端點自動探索儲存貯體區域。

    6. Module Source Bucket Name (模組來源儲存貯體名稱):(選用) 輸入包含 PowerShell 模組檔案的 Amazon S3 儲存貯體名稱。如果您指定 None (無),請為下一個選項 Allow PS Gallery Module Source (允許 PS Gallery 模組來源) 選擇 True (True)。

      注意

      您可以根據儲存貯體的所在區域,為儲存貯體名稱加上以區域為名的字首。範例如下:us-west-2:doc-example-bucket。如果您在 us-east-1 以外的特定區域中使用 Amazon S3 端點的代理,則應為儲存貯體名稱加上以區域為名的字首。如果儲存貯體名稱未包含字首,則會使用 us-east-1 端點自動探索儲存貯體區域。

    7. Allow PS Gallery Module Source (允許 PS Gallery 模組來源):(選擇性) 選擇 True 以從 https://www.powershellgallery.com/ 下載 PowerShell 模組。如果您選擇 False,請為前一個選項 ModuleSourceBucketName 中指定來源。

    8. Proxy Uri (代理 Uri):(選擇性) 使用此選項,從代理伺服器下載 MOF 檔案。

    9. Reboot Behavior (重新啟動行為):(選擇性) 如果您的 MOF 檔案執行需要重新啟動,指定以下其中一個重新啟動行為:

      • AfterMof (MOF 之後):在完成所有 MOF 執行後重新啟動執行個體。即使有多個 MOF 執行要求重新啟動,系統會等到所有 MOF 執行完成之後,才重新啟動。

      • Immediately (立即):每當 MOF 執行提出要求,就立即重新啟動執行個體。如果執行的多個 MOF 檔案請求重新啟動,則會重新啟動執行個體多次。

      • Never (從不):不會重新啟動執行個體,即使 MOF 執行明確要求重新啟動。

    10. Use Computer Name For Reporting (使用電腦名稱進行報告):(選用) 開啟此選項,以在報告合規資訊時使用電腦名稱。預設值為 false,這表示報告合規資訊時,系統會使用執行個體 ID。

    11. Turn on Verbose Logging (開啟詳細記錄):(選用) 建議您在首次部署 MOF 檔案時開啟詳細記錄。

      重要

      允許後,與標準關聯執行記錄相比,詳細記錄能將更多的資料寫入 Amazon S3 儲存貯體。這可能導致效能變慢,及更高的 Amazon S3 儲存費用。為了減緩儲存空間大小問題,建議您在 Amazon S3 儲存貯體上開啟生命週期政策。如需詳細資訊,請參閱《Amazon Simple Storage Service 主控台使用者指南》中的如何建立 S3 儲存貯體的生命週期政策?

    12. Turn on Debug Logging (開啟偵錯記錄):(選用) 建議開啟偵錯記錄,以便排除 MOF 錯誤。我們也建議您針對一般使用停用此選項。

      重要

      允許後,與標準關聯執行記錄相比,偵錯記錄能將更多的資料寫入 Amazon S3 儲存貯體。這可能導致效能變慢,及更高的 Amazon S3 儲存費用。為了減緩儲存空間大小問題,建議您在 Amazon S3 儲存貯體上開啟生命週期政策。如需詳細資訊,請參閱《Amazon Simple Storage Service 主控台使用者指南》中的如何建立 S3 儲存貯體的生命週期政策?

    13. Compliance Type (合規類型):(選擇性) 指定報告合規資訊時使用的合規類型。預設合規類型為 Custom:DSC。如果您建立多個執行 MOF 檔案的關聯,請務必為每個關聯指定不同的合規類型。如果您沒有執行此作業,每個使用 Custom:DSC 的額外關聯都會覆寫現有的合規資料。

    14. Pre Reboot Script (指令碼在重新啟動前):(選擇性) 指定若組態指示重新啟動為必要時,所要執行的指令碼。指令碼會在重新啟動之前執行。指令碼必須為單行。使用分號分隔其他行。

  7. Targets (目標) 區段,選擇 Specifying tags (指定標籤)Manually Selecting Instance (手動選取執行個體)。如果您選擇使用標籤將資源設為目標,請在提供的欄位中輸入標籤索引鍵和標籤值。如需使用目標的詳細資訊,請參閱關於 State Manager 關聯中的目標和速率控制

  8. Specify schedule (指定排程) 區段中,擇一選擇 On Schedule (按照排程)No schedule (無排程)。如果您選擇 On Schedule (按照排程),則使用提供的按鈕來為關聯建立 Cron 或 Rate 排程。

  9. Advanced options (進階選項) 區段中:

    • Compliance severity (合規嚴重性) 中,選擇關聯的嚴重性等級。合規報告會指出關聯狀態合規與否,以及您在這裡指示的嚴重性等級。如需更多詳細資訊,請參閱 關於State Manager關聯合規

  10. Rate control (速率控制) 區段中,針對在受管執行個體機群之間執行State Manager關聯設定選項。如需關於這些選項的詳細資訊,請參閱 關於 State Manager 關聯中的目標和速率控制

    Concurrency (並行) 部分,選擇一個選項:

    • 選擇 targets (目標),輸入可以同時執行關聯的目標絕對數量。

    • 選擇 percentage (百分比),輸入可以同時執行關聯的目標集百分比。

    Error threshold (錯誤閾值) 部分,選擇一個選項:

    • 選擇 errors (錯誤),輸入State Manager停止在額外目標執行關聯之前允許的錯誤絕對數量。

    • 選擇 percentage (百分比),輸入State Manager停止在額外目標執行關聯之前允許的錯誤百分比。

  11. (選用) 針對 Output options (輸出選項),若要將命令輸出儲存至檔案,請選取 Enable writing output to S3 (啟用將輸出寫入 S3) 方塊。在方塊中輸入儲存貯體和字首 (資料夾) 名稱。

    注意

    授予能力以將資料寫入至 S3 儲存貯體的 S3 許可,會是指派給受管節點之執行個體設定檔的許可,而不是執行此任務之 IAM 使用者的許可。如需詳細資訊,請參閱建立適用於 Systems Manager 的 IAM 執行個體設定檔或者建立適用於混合環境的 IAM 服務角色。此外,若指定的 S3 儲存貯體位於不同的 AWS 帳戶 內,請驗證與受管節點相關聯的執行個體設定檔或 IAM 服務角色是否具有寫入該儲存貯體的必要許可。

  12. 選擇 Create Association (建立關聯)

State Manager會在指定的執行個體或目標上建立並立即執行關聯。在初次執行後,關聯會根據您定義的排程和以下規則,依間隔執行:

  • State Manager間隔開始時, 在線上執行個體上執行關聯,並略過離線執行個體。

  • State Manager嘗試於間隔期間在所有已設定的執行個體上執行關聯。

  • 如果未在間隔期間執行關聯 (例如,因為並行值限制了一次所能處理關聯的執行個體數),則 State Manager 會嘗試在下一個間隔期間執行關聯。

  • State Manager會記錄所有略過的間隔的歷程記錄。您可以在 Execution History (執行歷程記錄) 標記檢視歷程記錄。

注意

AWS-ApplyDSCMofs 是 Systems Manager 命令文件。這表示您也可以使用 Run Command (AWS Systems Manager 的一個功能) 執行此文件。如需更多詳細資訊,請參閱 使用 Systems Manager Run Command 傳送命令

Troubleshooting

本節包括一些資訊,可協助您排除建立執行 MOF 檔案的關聯時所發生的問題。

開啟增強型記錄

故障診斷的第一個步驟是開啟增強型記錄。具體來說,請執行下列操作:

  1. 確認關聯已設定為將命令輸出寫入 Amazon S3 或 Amazon CloudWatch Logs (CloudWatch)。

  2. Enable Verbose Logging (啟用詳細記錄) 參數設為 True。

  3. Enable Debug Logging (啟用偵錯記錄) 參數設為 True。

開啟詳細和偵錯記錄後,Stdout 輸出檔案會包括指令碼執行的詳細資訊。此輸出檔可協助您找出指令碼失敗的位置。Stderr 輸出檔案包括指令碼執行期間發生的錯誤。

常見問題

本節包括一些資訊,介紹建立執行 MOF 檔案的關聯時可能發生的常見問題,以及排除這些問題的步驟。

我的 MOF 未套用

如果State Manager無法將關聯套用到您的執行個體,則先檢閱 Stderr 輸出檔。這個檔案可協助您了解問題的根源。亦請確認下列內容:

  • 執行個體具有所有 MOF 相關 Amazon S3 儲存貯體所需的存取許可。具體而言:

    • s3:GetObject 許可:對於私有 Amazon S3 儲存貯體中的 MOF 檔案及 Amazon S3 儲存貯體中的自訂模組,這是必要的。

    • s3:PutObject 許可:對於將合規報告和合規狀態寫入 Amazon S3 儲存貯體,這是必要的。

  • 如果您使用的是標籤,則確保執行個體具有所需的 IAM 政策。若使用標籤,執行個體 IAM 角色必須具有允許 ec2:DescribeInstancesssm:ListTagsForResource 動作的政策。

  • 確保執行個體已指派預期的標籤或 SSM 參數。

  • 確認標籤或 SSM 參數無拼寫錯誤。

  • 嘗試在本機於執行個體上套用 MOF,以確保 MOF 檔案本身沒有問題。

我的 MOF 似乎無法執行,但 Systems Manager 執行成功

如果 AWS-ApplyDSCMofs 文件成功執行,則 Systems Manager 執行狀態會顯示為 Success (成功)。此狀態不會依照 MOF 檔案中的組態要求,反映您執行個體的合規狀態。若要檢視您執行個體的合規狀態,請查看合規報告。您可以在 Amazon S3 報告儲存貯體中檢視 JSON 報告。這適用於 Run Command 和State Manager執行。此外,對於 State Manager,您可以在 Systems Manager 合規頁面查看合規詳細資訊。

Stderr 狀態:嘗試連接服務時名稱解析失敗

此錯誤表示指令碼無法連接遠端服務。最有可能是指令碼無法連接 Amazon S3。此問題通常發生在指令碼嘗試將合規報告或合規狀態寫入文件參數中提供的 Amazon S3 儲存貯體時。一般而言,此錯誤發生在運算環境使用包括允許清單的防火牆或透明代理時。若要解決此問題:

  • 對於所有 Amazon S3 儲存貯體參數,請使用區域特定的儲存貯體語法。例如,Mofs to Apply (要套用的 MOF) 參數應採用以下格式:

    s3:儲存貯體區域儲存貯體名稱MOF 檔名.mof。

    請見此處範例: s3:us-west-2:doc-example-bucket:my-mof.mof

    報告、狀態和模組來源儲存貯體名稱應採用以下格式。

    儲存貯體區域儲存貯體名稱。請見此處範例:us-west-1:doc-example-bucket

  • 如果區域特定的語法無法修正問題,則確保目標執行個體可以存取想要的區域中的 Amazon S3。為了確認:

    1. 在適當的 Amazon S3 區域中尋找 Amazon S3 的端點名稱。如需相關資訊,請參閱《Amazon Web Services 一般參考》中的 Amazon S3 服務端點

    2. 登入到目標執行個體並執行以下 ping 命令。

      ping s3.s3-region.amazonaws.com

      如果 ping 失敗,則表示 Amazon S3 出現故障或防火牆/透明代理封鎖對 Amazon S3 區域的存取,或是執行個體無法存取網際網路。

檢視 DSC 資源合規詳細資訊

當您執行 AWS-ApplyDSCMofs 文件時,Systems Manager 會擷取您指定的 Amazon S3 狀態儲存貯體中的 DSC 資源故障的合規資訊。在 Amazon S3 儲存貯體中搜尋 DSC 資源故障相關資訊可能非常耗時。您可以改為在 Systems Manager Compliance (合規) 頁面中檢視此資訊。

合規資源摘要區段顯示失敗的資源計數。在以下範例中,ComplianceTypeCustom:DSC 和不合規的一個資源。

注意

Custom:DSC 是 AWS-ApplyDSCMofs 文件中的預設 ComplianceType 值。這個值是可自訂的。


                        檢視 Compliance (合規) 頁面的 Compliance resources summary (合規資源摘要) 區域中的計數。

Details overview for resources (資源詳細資訊概觀) 區段會顯示使用不合規 DSC 資源的 AWS 資源相關資訊。本章節也包含 MOF 名稱、指令碼執行步驟,以及 (如適用) 檢視輸出連結,以檢視詳細的狀態資訊。


                        檢視 MOF 執行資源故障的合規詳細資訊

View output (檢視輸出) 連結會顯示詳細狀態的最後 4,000 個字元。Systems Manager 會使用例外狀況做為第一個元素開始,然後掃描詳細訊息,並在到達 4,000 個字元配額之前加上盡可能多的字首。這個程序會顯示拋出例外狀況之前的輸出日誌訊息,也就是與故障診斷最相關的訊息。


                        檢視 MOF 資源合規問題的詳細輸出

如需如何檢視合規資訊的相關資訊,請參閱 AWS Systems Manager 合規

影響合規報告的狀況

若 State Manager 關聯失敗,則系統不會報告合規資料。更具體地說,若 MOF 無法處理,則 Systems Manager 不會報告任何合規項目,因為關聯會失敗。例如,若 Systems Manager 嘗試從執行個體沒有存取許可的 Amazon S3 儲存貯體下載 MOF,則關聯會失敗,也不會報告合規資料。

若第二個 MOF 中的資源失敗,則 Systems Manager 報告合規資料。例如,若 MOF 嘗試在不存在的硬碟上建立檔案,則 Systems Manager 會報告合規,因為 AWS-ApplyDSCMofs 文件能夠完全處理,這表示關聯成功執行。