• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。

# 创建运行 Ansible Playbook 的关联
<a name="systems-manager-state-manager-ansible"></a>

您可以使用 `AWS-ApplyAnsiblePlaybooks` SSM 文档创建运行 Ansible Playbook 的State Manager关联。State Manager是 AWS Systems Manager 中的一项工具。本文档为运行 Playbook 提供了以下好处：
+ 支持运行复杂的 Playbook
+ 支持从 GitHub 和 Amazon Simple Storage Service（Amazon S3）下载 Playbook
+ 支持压缩的 PlayBook 结构
+ 增强的日志记录
+ 捆绑 Playbook 时可以指定要运行的 Playbook

**注意**  
Systems Manager 包括两个 SSM 文档，使您能够创建运行 Ansible Playbook 的 State Manager 关联：`AWS-RunAnsiblePlaybook` 和 `AWS-ApplyAnsiblePlaybooks`。`AWS-RunAnsiblePlaybook` 文档已被弃用。它在 Systems Manager 中仍然提供，用于传统用途。由于此处介绍的增强功能，我们建议您使用 `AWS-ApplyAnsiblePlaybooks` 文档。  
运行 Ansible Playbook 的关联在 macOS 中不受支持。

**支持运行复杂的 Playbook**

`AWS-ApplyAnsiblePlaybooks` 文档支持捆绑的复杂 Playbook，因为它会在执行指定的主 Playbook 之前将整个文件结构复制到本地目录中。您可以在 Zip 文件或目录结构中提供源 Playbook。Zip 文件或目录可以存储在 GitHub 或 Amazon S3 中。

**支持从 GitHub 下载 Playbook**

`AWS-ApplyAnsiblePlaybooks` 文档使用 `aws:downloadContent` 插件下载 Playbook 文件。文件可以存储在 GitHub 中的单个文件中，也可以存储为一组组合 Playbook 文件。要从 GitHub 下载内容，请以 JSON 格式指定有关 GitHub 存储库的信息。见下列。

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

**支持从 Amazon S3** 下载 Playbook

您还可以将 Ansible Playbook 作为单个 .zip 文件或目录结构存储和下载到 Amazon S3 中。要从 Amazon S3 下载内容，您必须指定该文件的路径。以下是两个示例。

**示例 1：下载特定 Playbook 文件**

```
{
   "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)。

**支持压缩的 PlayBook 结构**

`AWS-ApplyAnsiblePlaybooks` 文档使您可以在下载的捆绑包中运行压缩的 .zip 文件。该文档检查下载的文件是否包含 .zip 格式的压缩文件。如果找到 .zip 文件，则文档将自动解压缩文件，然后运行指定的 Ansible 自动化。

**增强的日志记录**

`AWS-ApplyAnsiblePlaybooks` 文档包括一个可选参数，用于指定不同级别的日志记录。指定 -v 来表示低详细程度，-vv 或 –vvv 表示中等详细程度，-vvvv 表示调试级别日志记录。这些选项直接映射到 Ansible 详细程度选项。

**捆绑 Playbook 时可以指定要运行的 Playbook**

`AWS-ApplyAnsiblePlaybooks` 文档包含一个必需参数，用于指定捆绑多个 PlayBook 时要运行哪个 PlayBook。此选项为运行 PlayBook 提供了灵活性，以支持不同的使用案例。

## 了解安装的依赖项
<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 Playbook 的关联（控制台）
<a name="systems-manager-state-manager-ansible-console"></a>

以下过程介绍了如何使用 Systems Manager 控制台创建 State Manager 关联，以便使用 `AWS-ApplyAnsiblePlaybooks` 文档运行 Ansible Playbook。

**创建运行 Ansible Playbook 的关联（控制台）**

1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。

1. 在导航窗格中，请选择 **State Manager**。

1. 选择** Create Association**，然后选择 **State Manager**。

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 (PlayBook 文件)**，输入文件名。如果 Zip 文件包含 Playbook，则必须指定 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. 在 **高级选项** 部分中，对于**合规性严重级别**，选择关联的严重级别。合规性报告指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息，请参阅 [关于 State Manager 关联合规性](compliance-about.md#compliance-about-association)。

1. 在 **Rate control**（速率控制）部分，配置用于在托管式节点机群中运行 State Manager 关联的选项。有关使用速率控制的信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。

   在**并发**部分中，选择一个选项：
   + 选择 **targets (目标)** 输入可同时运行关联的目标的绝对数量。
   + 选择 **percentage (百分比)** 输入可同时运行关联的目标集的百分比。

   在**错误阈值**部分中，选择一个选项：
   + 选择 **errors (错误)** 以输入允许的错误绝对数量，超过该数量后 State Manager 停止对其他目标运行关联。
   + 选择 **percentage (百分比)** 以输入允许的错误百分比，超过该百分比后 State Manager 停止对其他目标运行关联。

1. （可选）对于 **Output options (输出选项)**，要将命令输出保存到文件，请选中 **Enable writing output to S3 (启用将输出写入 S3)** 方框。在方框中输入存储桶和前缀（文件夹）名称。
**注意**  
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给托管式节点的实例配置文件的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。

1. 选择**创建关联**。

**注意**  
如果使用标签在一个或多个目标节点上创建关联，然后从某一节点中删除标签，则该节点将不再运行该关联。该节点不再与 State Manager 文档关联。

## 创建运行 Ansible Playbook 的关联（CLI）
<a name="systems-manager-state-manager-ansible-cli"></a>

以下过程介绍了如何使用 AWS Command Line Interface（AWS CLI）创建 State Manager 关联，以便使用 `AWS-ApplyAnsiblePlaybooks` 文档运行 Ansible Playbook。

**创建运行 Ansible Playbook 的关联（CLI）**

1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。

   有关更多信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。

1. 运行以下命令之一来创建运行 Ansible Playbook 的关联，该关联使用标签将节点设为目标。将每个*示例资源占位符*替换为您自己的信息。命令（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"],"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"
   ```