AWS Systems Manager
用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

创建运行 Ansible Playbook 的关联

您可以使用 AWS-ApplyAnsiblePlaybooks 文档创建运行 Ansible Playbook 的 状态管理器 关联。本文档为运行 Playbook 提供了以下好处:

  • 支持运行复杂的 Playbook

  • 支持从 GitHub 和 Amazon Simple Storage Service (Amazon S3) 下载 Playbook

  • 支持压缩的 PlayBook 结构

  • 增强的日志记录

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

注意

Systems Manager 包括两个 SSM 文档,使您能够创建运行 Ansible Playbook 的 状态管理器 关联:AWS-RunAnsiblePlaybookAWS-ApplyAnsiblePlaybooksAWS-RunAnsiblePlaybook 文档已被弃用。它在 Systems Manager 中仍然提供,用于传统用途。由于此处介绍的增强功能,我们建议您使用 AWS-ApplyAnsiblePlaybooks 文档。

支持运行复杂的 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/aws-execute-ansible-test/ansible/playbook.yml" }

示例 2:下载目录的内容

{ "path":"https://s3.amazonaws.com/aws-execute-ansible-test/ansible/webservers/" }

重要

如果您指定 Amazon S3,则必须使用 AmazonS3ReadOnlyAccess 策略配置您托管实例上的 AWS Identity and Access Management (IAM) 实例配置文件。有关更多信息,请参阅 为 Systems Manager 创建 IAM 实例配置文件

支持压缩的 PlayBook 结构

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

增强的日志记录

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

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

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

已安装依赖项

如果您为 InstallDependencies 参数指定 True,则 Systems Manager 验证您的实例上是否安装了以下依赖项。如果找不到这些依赖项中的一个或多个,则 Systems Manager 将自动安装它们。

  • Ubuntu/Debian:Apt-get(程序包管理)、Python 3、Ansible、Unzip

  • Amazon Linux:Ansible

  • RHEL:Python 3、Ansible、Unzip

创建运行 Ansible Playbook 的关联(控制台)

以下过程介绍了如何使用 Systems Manager 控制台创建 状态管理器 关联,以便使用 AWS-ApplyAnsiblePlaybooks 文档运行 Ansible Playbook。

创建运行 Ansible Playbook 的关联(控制台)

  1. 通过以下网址打开 AWS Systems Manager 控制台:https://console.amazonaws.cn/systems-manager/

  2. 在导航窗格中,选择 状态管理器,然后选择 Create association (创建关联)

  3. 对于 Name (名称),请指定一个名称,该名称可帮助您记住关联的用途。

  4. Document (文档) 列表中,选择 AWS-ApplyAnsiblePlaybooks

  5. 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" }
  6. 对于 Install Dependencies (安装依赖项),请选择一个选项。

  7. (可选)对于 Playbook File (PlayBook 文件),输入文件名。如果 Playbook 包含在 Zip 文件中,则必须指定 Zip 文件的相对路径。

  8. (可选)对于 Extra Variables (额外变量),请输入希望 状态管理器 在运行时发送到 Ansible 的变量。

  9. (可选)对于 Check (检查),选择一个选项。

  10. (可选)对于 Verbose (详细),选择一个选项。

  11. 对于 Targets (目标),选择一个选项。有关使用目标的信息,请参阅将目标和速率控制与 状态管理器 关联结合使用

  12. Specify schedule (指定计划) 部分中,选择 On schedule (按计划)No schedule (无计划)。如果选择 On schedule (按计划),则可使用提供的按钮为关联创建 cron 或 rate 计划。

  13. 高级选项 部分中,对于 Compliance severity (合规性严重级别),选择关联的严重级别。合规性报告指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息,请参阅 关于 状态管理器 关联合规性

  14. Rate control (速率控制) 部分,配置用于在托管实例队列中运行 状态管理器 关联的选项。有关使用速率控制的信息,请参阅将目标和速率控制与 状态管理器 关联结合使用

    Concurrency (并发) 部分中,选择一个选项:

    • 选择 targets (目标) 输入可同时运行关联的目标的绝对数量。

    • 选择 percentage (百分比) 输入可同时运行关联的目标集的百分比。

    Error threshold (错误阈值) 部分中,选择一个选项:

    • 选择 errors (错误) 以输入允许的错误绝对数量,超过该数量后 状态管理器 停止对其他目标运行关联。

    • 选择 percentage (百分比) 以输入 允许的错误百分比,超过该百分比后 状态管理器 停止对其他目标运行关联。

  15. Output options (输出选项) 部分中,如果要将创建关联的命令的输出写入到 Amazon S3 存储桶,请选择 Enable writing output to S3 (启用将输出写入 S3)

  16. 选择创建关联

注意

如果使用标签在一个或多个目标实例上创建关联,然后从某一实例中删除标签,则该实例将不再运行该关联。该实例不再与 状态管理器 文档关联。

创建运行 Ansible Playbook 的关联 (CLI)

以下过程介绍了如何使用 AWS CLI 创建 状态管理器 关联,以便使用 AWS-ApplyAnsiblePlaybooks 文档运行 Ansible Playbook。

创建运行 Ansible Playbook 的关联 (CLI)

  1. 安装并配置 AWS CLI(如果尚未执行该操作)。

    有关信息,请参阅安装或升级 AWS CLI

  2. 运行以下命令之一来创建关联,该关联通过使用 Amazon EC2 标签定位实例来运行 Ansible Playbook。命令 (A) 指定 GitHub 作为源类型。命令 (B) 指定 Amazon S3 作为源类型。

    (A) GitHub 源

    LinuxWindows
    Linux
    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 源

    LinuxWindows
    Linux
    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/myTestBucket/playbook.yml\"}"],"InstallDependencies":["True"],"PlaybookFile":["playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \ --association-name "AnsibleAssociation" --schedule-expression "cron(0 2 ? * SUN *)"

    注意

    状态管理器 关联不支持所有的 cron 和 rate 表达式。有关为关联创建 cron 和 rate 表达式的更多信息,请参阅参考:Systems Manager 的 Cron 和 Rate 表达式

    系统将尝试在实例上创建关联并立即应用状态。

  3. 运行以下命令查看您刚才创建的关联的更新状态。

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