• 2026 年 4 月 30 日之後將不再提供 AWS Systems Manager CloudWatch Dashboard。客戶可以繼續使用 Amazon CloudWatch 主控台來檢視、建立和管理其 Amazon CloudWatch 儀表板，就像現在一樣。如需詳細資訊，請參閱 [Amazon CloudWatch Dashboard 文件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 建立執行 Ansible 手冊的關聯
<a name="systems-manager-state-manager-ansible"></a>

您可以使用 `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-RunAnsiblePlaybook` 和 `AWS-ApplyAnsiblePlaybooks`。`AWS-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 Simple Storage Service (Amazon S3) 中下載手冊**

您也能以單一 .zip 檔案或目錄結構的形式，在 Amazon Simple Storage Service (Amazon S3) 中儲存和下載 Ansible 手冊。若要從 Amazon Simple Storage Service (Amazon S3) 中下載內容，請指定檔案的路徑。以下是兩個範例。

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

```
{
   "path":"https://s3.amazonaws.com/{{amzn-s3-demo-bucket/playbook.yml}}"
}
```

**範例 2：下載目錄的內容**

```
{
   "path":"https://s3.amazonaws.com/{{amzn-s3-demo-bucket/ansible/webservers/}}"
}
```

**重要**  
如果您指定 Amazon S3，則受管節點上的 AWS Identity and Access Management (IAM) 執行個體描述檔必須包含 S3 儲存貯體的許可。如需詳細資訊，請參閱[設定 Systems Manager 所需的執行個體許可](setup-instance-permissions.md)。

**支援壓縮的手冊結構**

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

**增強型日誌**

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

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

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

## 了解已安裝的相依性
<a name="systems-manager-state-manager-ansible-depedencies"></a>

如果您為 **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 手冊的關聯 (主控台)
<a name="systems-manager-state-manager-ansible-console"></a>

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

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

1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。

1. 在導覽窗格中，選擇 **State Manager**。

1. 選擇 **State Manager**，然後選擇 **Create association** (建立關聯)。

1. 針對 **Name (名稱)**，指定可協助您記住關聯用途的名稱。

1. 在 **Document** (文件) 清單中，請選擇 **`AWS-ApplyAnsiblePlaybooks`**。

1. 在 **Parameters (參數)** 區段中，針對 **Source Type (來源類型)**，選擇 **GitHub** 或 **S3**。

   **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}}"
   }
   ```

1. 針對 **Install Dependencies (安裝相依性)**，選擇一個選項。

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

1. (選用) 在**額外變數**欄位中，輸入您要 State Manager 在執行時期傳送到 Ansible 的變數。

1. (選用) 針對 **Check (檢查)**，選擇一個選項。

1. (選用) 針對 **Verbose (詳細資訊)**，選擇一個選項。

1. 對於 **Targets (目標)**，請選擇選項。如需使用目標的詳細資訊，請參閱[了解 State Manager 關聯中的目標和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。

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

1. 在 **Advanced options (進階選項)** 區段中，針對 **Compliance severity (合規嚴重性)**，選擇關聯的嚴重性等級。合規報告會指出關聯狀態合規與否，以及您在這裡指示的嚴重性等級。如需詳細資訊，請參閱[關於State Manager關聯合規](compliance-about.md#compliance-about-association)。

1. 在 **Rate control** (速率控制) 區段中，設定在受管節點機群之間執行State Manager關聯的選項。如需使用速率控制的詳細資訊，請參閱 [了解 State Manager 關聯中的目標和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。

   在 **Concurrency (並行)** 部分，選擇一個選項：
   + 選擇 **targets (目標)**，輸入可以同時執行關聯的目標絕對數量。
   + 選擇 **percentage (百分比)**，輸入可以同時執行關聯的目標集百分比。

   在 **Error threshold (錯誤閾值)** 部分，選擇一個選項：
   + 選擇 **errors (錯誤)**，輸入 State Manager 停止在額外目標執行關聯之前允許的錯誤絕對數量。
   + 選擇 **percentage (百分比)**，輸入 State Manager 停止在額外目標執行關聯之前允許的錯誤百分比。

1. (選用) 針對**輸出選項**，若要將命令輸出儲存至檔案，請選取**啟用將輸出寫入 S3** 方塊。在方塊中輸入儲存貯體和字首 (資料夾) 名稱。
**注意**  
授予能力以將資料寫入至 S3 儲存貯體的 S3 許可，會是指派給受管節點之執行個體設定檔的許可，而不是執行此任務之 IAM 使用者的許可。如需詳細資訊，請參閱[設定 Systems Manager 所需的執行個體許可](setup-instance-permissions.md)或[建立混合環境的 IAM 服務角色](hybrid-multicloud-service-role.md)。此外，若指定的 S3 儲存貯體位於不同的 AWS 帳戶內，請驗證與受管節點相關聯的執行個體設定檔或 IAM 服務角色是否具有寫入該儲存貯體的必要許可。

1. 選擇 **Create Association (建立關聯)**。

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

## 建立執行 Ansible 手冊的關聯 (CLI)
<a name="systems-manager-state-manager-ansible-cli"></a>

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

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

1. 如果您尚未安裝和設定 AWS Command Line Interface (AWS CLI)。

   如需相關資訊，請參閱[安裝或更新最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。

1. 執行以下其中一個命令來建立關聯，該關聯透過使用標籤將節點設為目標來執行執行 Ansible 手冊。將每個{{範例資源預留位置}}取代為您自己的資訊。命令 (A) 指定 GitHub 作為來源類型。命令 (B) 指定 Amazon Simple Storage Service (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}}"],"TimeoutSeconds":["3600"]}' \
       --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}}"], "TimeoutSeconds":["3600"]}' ^
       --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=Linux" \
       --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/amzn-s3-demo-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 運算式](reference-cron-and-rate-expressions.md)。

   系統會嘗試在節點上建立關聯，並立即套用狀態。

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

   ```
   aws ssm describe-association --association-id "{{ID}}"
   ```