演練:建立執行 Ansible 手冊的關聯 - AWS Systems Manager

演練:建立執行 Ansible 手冊的關聯

您可以使用 AWS-ApplyAnsiblePlaybooks SSM 文件來建立執行 Ansible 手冊的 State Manager 關聯。State Manager 是 AWS Systems Manager 的一個功能。本文件提供執行手冊的下列優點:

  • 支援執行複雜的手冊

  • 支援從 GitHub 和 Amazon Simple Storage Service (Amazon S3) 下載手冊

  • 支援壓縮的手冊結構

  • 增強型日誌

  • 能夠指定綁定多個手冊時,要執行哪個手冊

注意

Systems Manager 包含兩個 SSM 文件,允許您建立執行 Ansible 手冊的 State Manager 關聯:AWS-RunAnsiblePlaybookAWS-ApplyAnsiblePlaybooksAWS-RunAnsiblePlaybook 文件已棄用。它在 Systems Manager 中仍維持可用,以用於舊版用途。由於此處所述的增強功能,我們建議您使用 AWS-ApplyAnsiblePlaybooks 文件。

macOS 不支援執行 Ansible 手冊的關聯。

支援執行複雜的手冊

AWS-ApplyAnsiblePlaybooks 文件支援綁定的複雜手冊,因為它可在執行指定的主要手冊之前,將整個檔案結構複製到本機目錄。您可以提供 Zip 檔案或目錄結構的來源手冊。Zip 檔或目錄可存放在 GitHub 或 Amazon S3 中。

支援從 GitHub 下載手冊

AWS-ApplyAnsiblePlaybooks 文件會使用 aws:downloadContent 外掛程式來下載手冊檔案。檔案可以儲存於 GitHub 中的單一檔案,也可以儲存成一組手冊檔案。若要從 GitHub 中下載內容,請指定 JSON 格式的 GitHub 儲存庫相關資訊。請見此處範例。

{ "owner":"TestUser", "repository":"GitHubTest", "path":"scripts/python/test-script", "getOptions":"branch:master", "tokenInfo":"{{ssm-secure:secure-string-token}}" }

支援從 Amazon S3 中下載手冊

您也可以單一 .zip 檔或目錄結構的形式,將 Ansible 手冊存放和下載在 Amazon S3 中。若要從 Amazon S3 中下載內容,請指定檔案的路徑。以下是兩個範例。

範例 1:下載特定的手冊檔案

{ "path":"https://s3.amazonaws.com/doc-example-bucket/playbook.yml" }

範例 2:下載目錄的內容

{ "path":"https://s3.amazonaws.com/doc-example-bucket/ansible/webservers/" }
重要

如果您指定 Amazon S3,則必須使用 AmazonS3ReadOnlyAccess 政策來設定受管執行個體上的 AWS Identity and Access Management (IAM) 執行個體描述檔。如需詳細資訊,請參閱建立 Systems Manager 的 IAM 執行個體描述檔

支援壓縮的手冊結構

AWS-ApplyAnsiblePlaybooks 文件允許您執行下載套件中的壓縮 .zip 檔。此文件會檢查下載的檔案是否包含 .zip 格式的壓縮檔案。如果找到 .zip,文件會自動解壓縮檔案,然後執行指定的 Ansible 自動化。

增強型日誌

AWS-ApplyAnsiblePlaybooks 文件包含選擇性參數,用於指定不同層級的日誌。指定 -v 表示低詳細資訊等級,-vv 或 -vvv 表示中詳細資訊等級,-vvvv 表示偵錯等級日誌。這些選項會直接映射到 Ansible 詳細資訊選項。

能夠指定綁定多個手冊時,要執行哪個手冊

AWS-ApplyAnsiblePlaybooks 文件包含必要參數,用於指定綁定多個手冊時要執行哪個手冊。此選項提供執行手冊的彈性,以支援不同的使用案例。

安裝的相依性

如果您為 InstallDependencies 參數指定 True,則 Systems Manager 會驗證您的執行個體是否已安裝下列相依性:

  • Ubuntu Server/Debian Server:Apt-get (套件管理)、Python 3、Ansible、Unzip

  • Amazon Linux:Ansible

  • RHEL:Python 3、Ansible、Unzip

如果找不到這些相依性中的一個或多個項目,則 Systems Manager 會自動安裝它們。

建立執行 Ansible 手冊的關聯 (主控台)

下列程序說明如何使用 Systems Manager 主控台來建立使用 AWS-ApplyAnsiblePlaybooks 文件執行 Ansible 手冊的 State Manager 關聯。

建立執行 Ansible 手冊的關聯 (主控台)

  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-ApplyAnsiblePlaybooks

  6. Parameters (參數) 區段中,針對 Source Type (來源類型),選擇 GitHubS3

    GitHub

    如果您選擇 GitHub,請輸入下列格式的儲存庫資訊。

    { "owner":"user_name", "repository":"name", "path":"path_to_directory_or_playbook_to_download", "getOptions":"branch:branch_name", "tokenInfo":"{{(Optional)_token_information}}" }

    S3

    如果您選擇 S3,請輸入下列格式的路徑資訊。

    { "path":"https://s3.amazonaws.com/path_to_directory_or_playbook_to_download" }
  7. 針對 Install Dependencies (安裝相依性),選擇一個選項。

  8. (選用) 針對 Playbook File (手冊檔案),輸入檔案名稱。如果 Zip 檔包含手冊,則必須指定 Zip 檔的相對路徑。

  9. (選用) 針對 Extra Variables (額外變數),輸入您要 State Manager 在執行時間傳送到 Ansible 的變數。

  10. (選用) 針對 Check (檢查),選擇一個選項。

  11. (選用) 針對 Verbose (詳細資訊),選擇一個選項。

  12. 對於 Targets (目標),請選擇選項。如需使用目標的詳細資訊,請參閱關於 State Manager 關聯中的目標和速率控制

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

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

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

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

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

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

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

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

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

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

    注意

    授予能力以將資料寫入至 S3 儲存貯體的 S3 許可,會是指派給執行個體之執行個體描述檔的許可,而不是執行此工作之 IAM 使用者的許可。如需詳細資訊,請參閱建立 Systems Manager 的 IAM 執行個體描述檔。此外,若指定的 S3 儲存貯體位於不同的 AWS 帳戶 內,請驗證與執行個體相關聯的執行個體描述檔是否具有寫入該儲存貯體的必要許可。

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

注意

如果您使用標籤在一或多個目標執行個體上建立關聯,然後從執行個體移除標籤,則該執行個體將不再執行該關聯。系統會從State Manager文件中取消該執行個體的關聯。

建立執行 Ansible 手冊的關聯 (CLI)

下列程序說明如何使用 AWS Command Line Interface (AWS CLI) 來建立使用 AWS-ApplyAnsiblePlaybooks 文件執行 Ansible 手冊的 State Manager 關聯。

建立執行 Ansible 手冊的關聯 (CLI)

  1. 如果您尚未安裝並設定 AWS Command Line Interface (AWS CLI),請進行相應的操作。

    如需相關資訊,請參閱安裝或升級 AWS 命令列工具

  2. 執行以下其中一個命令,使用 Amazon Elastic Compute Cloud (Amazon EC2) 標籤將執行個體設為目標,以建立執行 Ansible 手冊的關聯。命令 (A) 指定 GitHub 做為來源類型。命令 (B) 指定 Amazon S3 作為來源類型。

    (A) GitHub 來源

    Linux & macOS
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \ --targets Key=tag:TagKey,Values=TagValue \ --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' \ --association-name "name" --schedule-expression "cron_or_rate_expression"
    Windows
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^ --targets Key=tag:TagKey,Values=TagValue ^ --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' ^ --association-name "name" --schedule-expression "cron_or_rate_expression"

    請見此處範例。

    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \ --targets "Key=tag:OS,Values=Linux" \ --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ansibleDocumentTest\", \"repository\": \"Ansible\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True"],"PlaybookFile":["hello-world-playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \ --association-name "AnsibleAssociation" --schedule-expression "cron(0 2 ? * SUN *)"

    (B) S3 來源

    Linux & macOS
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \ --targets Key=tag:TagKey,Values=TagValue \ --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' \ --association-name "name" --schedule-expression "cron_or_rate_expression"
    Windows
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^ --targets Key=tag:TagKey,Values=TagValue ^ --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' ^ --association-name "name" --schedule-expression "cron_or_rate_expression"

    請見此處範例。

    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \ --targets "Key=tag:OS,Values= Windows" \ --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/DOC-EXAMPLE-BUCKET/playbook.yml\"}"],"InstallDependencies":["True"],"PlaybookFile":["playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \ --association-name "AnsibleAssociation" --schedule-expression "cron(0 2 ? * SUN *)"
    注意

    State Manager 關聯不支援所有 Cron 和 Rate 表達式。如需針對關聯建立 Cron 和 Rate 運算式的詳細資訊,請參閱參考:Systems Manager 的 Cron 和 Rate 表達式

    系統會嘗試在執行個體上建立關聯,並立即套用狀態。

  3. 執行以下命令來檢視您剛剛所建立的關聯的更新狀態。

    aws ssm describe-association --association-id "ID"