演练:创建运行 Ansible Playbook 的关联 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

演练:创建运行 Ansible Playbook 的关联

您可以使用 AWS-ApplyAnsiblePlaybooks SSM 文档创建运行 Ansible Playbook 的 State Manager 关联。State Manager 是 Amazon Systems Manager 的一种功能。本文档为运行 Playbook 提供了以下好处:

  • 支持运行复杂的 Playbook

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

  • 支持压缩的 PlayBook 结构

  • 增强的日志记录

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

注意

Systems Manager 包括两个 SSM 文档,使您能够创建运行 Ansible Playbook 的 State Manager 关联:AWS-RunAnsiblePlaybookAWS-ApplyAnsiblePlaybooksAWS-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/doc-example-bucket/playbook.yml" }

示例 2:下载目录的内容

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

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

支持压缩的 PlayBook 结构

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

增强的日志记录

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

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

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

已安装依赖项

如果您为 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 的关联(控制台)

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

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

  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中,选择 State Manager

    -或者-

    如果首先打开 Amazon Systems Manager 主页,选择菜单图标 ( ) 打开导航窗格,然后选择 State Manager

  3. 选择 Create Association,然后选择 State Manager

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

  15. Rate control(速率控制)部分,配置用于在托管式节点机群中运行 State Manager 关联的选项。有关使用速率控制的信息,请参阅 关于 State Manager 关联中的目标和速率控制

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

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

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

    错误阈值部分中,选择一个选项:

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

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

  16. (可选)对于 Output options (输出选项),要将命令输出保存到文件,请选中 Enable writing output to S3 (启用将输出写入 S3) 方框。在方框中输入存储桶和前缀(文件夹)名称。

    注意

    授予将数据写入 S3 存储桶的能力的 S3 权限,是分配给托管式节点的实例配置文件的权限,而不是执行此任务的 IAM 用户的权限。有关更多信息,请参阅为 Systems Manager 创建 IAM 实例配置文件为混合环境创建 IAM 服务角色。此外,如果指定的 S3 存储桶位于不同的 Amazon Web Services 账户 中,请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。

  17. 选择创建关联

注意

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

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

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

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

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

    有关信息,请参阅安装或升级 Amazon 命令行工具

  2. 运行以下命令之一来创建关联,该关联通过使用标签定位节点来运行 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"]}' \ --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=Linux" \ --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"