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

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

演练:创建运行 Chef 配方的关联

您可以使用 状态管理器 文档创建运行 Chef 配方的 AWS-ApplyChefRecipes 关联。SSM您可以使用 Systems Manager AWS-ApplyChefRecipes 文档定位基于 Linux 的 SSM 托管节点。本文档为运行 Chef 配方提供了以下好处:

  • 支持多个版本的 Chef(Chef 11 到 Chef 14)。

  • 在目标实例上自动安装 Chef 客户端软件。

  • (可选)在目标实例上运行 Systems Manager 合规性检查,并将合规性检查的结果存储在 Amazon Simple Storage Service (Amazon S3Amazon S3) 存储桶中。

  • 在文档的单次运行中运行多个说明书和配方。

  • (可选)在 why-run 模式下运行配方,以显示哪些配方会在未进行更改的情况下在目标实例上发生更改。

  • (可选)将自定义 JSON 属性应用于 chef-client 运行。

您可以使用 GitHub 或 S3 存储桶作为您在 AWS-ApplyChefRecipes 文档中指定的 Chef 说明书和配方的源。

注意

当前不支持运行 Chef 配方的关联。macOS

先决条件:设置您的关联、存储库和说明书

在创建 AWS-ApplyChefRecipes 文档之前,请准备您的 Chef 说明书和说明书存储库。如果您尚未获得要使用的 Chef 说明书,则可以先使用 AWS 为您准备的测试 HelloWorld 说明书。默认情况下,AWS-ApplyChefRecipes 文档已指向此说明书。您的说明书的设置应类似于以下目录结构。在以下示例中,jenkinsnginx 是 Chef 网站上的 Chef Supermarket 中提供的 Chef 说明书的示例。

虽然 AWS 无法正式支持 Chef Supermarket 网站上的说明书,但其中的许多说明书将与 AWS-ApplyChefRecipes 文档结合使用。以下是在测试社区说明书时需要检查的标准示例:

  • 说明书应支持您的目标 Systems Manager 托管节点的基于 Linux 的操作系统。

  • 说明书将适用于您使用的 Chef 客户端版本(Chef 11 到 Chef 14)。

  • 说明书与 Chef Infra 客户端兼容,并且不需要 Chef 服务器。

验证您是否能访问 Chef.io 网站,以便在运行列表中指定的任何说明书都能在 Systems Manager 文档运行时安装。支持使用嵌套的 cookbooks 文件夹,但这不是必需的;您可以将说明书直接存储在根级别下。

<Top-level directory, or the top level of the archive file (ZIP or tgz or tar.gz)> └── cookbooks (optional level) ├── jenkins │ ├── metadata.rb │ └── recipes └── nginx ├── metadata.rb └── recipes
重要

在创建运行 Chef 配方的 状态管理器 关联之前,请注意,除非您将 Systems ManagerChef client version (Chef 客户端版本) 的值设置为 ,否则文档运行将在您的 None 托管节点上安装 Chef 客户端软件。 此操作使用 Chef 中的安装脚本代表您安装 Chef 组件。在运行 AWS-ApplyChefRecipes 文档之前,请确保您的企业能够遵守任何适用的法律要求,包括适用于对 Chef 软件的使用的许可条款。有关更多信息,请参阅 Chef 网站

Systems Manager 可以向 S3 存储桶、Systems Manager 控制台发送合规性报告,或者提供合规性结果以响应 Systems Manager API 命令。要运行 Systems Manager 合规性报告,附加到 Systems Manager 托管实例的实例配置文件必须具有写入到 S3 存储桶的权限。该实例配置文件必须有权使用 Systems Manager PutComplianceItem API。有关 Systems Manager 合规性的更多信息,请参阅AWS Systems Manager 配置合规性

记录文档运行

当您通过使用 状态管理器 关联运行 Systems Manager 文档时,可以配置关联以选择文档运行的输出,并且可以将输出发送到 Amazon S3 或 Amazon CloudWatch Logs。要帮助在关联运行完后轻松进行故障排除,请验证是否已将关联配置为将命令输出写入 S3 存储桶或 CloudWatch Logs。有关更多信息,请参阅创建关联

使用 GitHub 作为说明书源

AWS-ApplyChefRecipes 文档使用 aws:downloadContent 插件下载说明书。要从 GitHub 下载内容,请以 JSON 格式将有关 GitHub 存储库的信息指定到文档。以下是示例:

{ "owner":"TestUser", "repository":"GitHubCookbookRepository", "path":"cookbooks/HelloWorld", "getOptions":"branch:master", "tokenInfo":"{{ssm-secure:secure-string-token}}" }

使用 Amazon S3 作为说明书源

您还可以将 Chef 说明书作为单个 .ziptar.gz 文件或目录结构存储和下载到 Amazon S3 中。要从 Amazon S3 下载内容,您必须指定该文件的路径。以下是两个示例:

示例 1:下载特定说明书

{ "path":"https://s3.amazonaws.com/chef-cookbooks/HelloWorld.zip" }

示例 2:下载目录的内容

{ "path":"https://s3.amazonaws.com/chef-cookbooks-test/HelloWorld" }
重要

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

创建运行 Chef 配方的关联(控制台)

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

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

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

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

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

  5. Parameters (参数) 中,对于 Source Type (源类型),选择 GitHubS3

  6. Source info (源信息) 中,采用下列格式之一输入说明书源信息。

    1. 如果您在步骤 5 中选择 GitHub,则采用以下格式输入存储库信息:

      { "owner":"user_name", "repository":"name", "path":"path_to_directory_or_cookbook_to_download", "getOptions":"branch:branch_name", "tokenInfo":"{{(Optional)_token_information}}" }
    2. 如果已在步骤 5 中选择 S3,请采用以下格式输入路径信息:

      { "path":"https://s3.amazonaws.com/path_to_directory_or_cookbook_to_download" }
  7. Run list (运行列表) 中,按以下格式列出要运行的配方,并用逗号将每个配方分隔开,如下所示。请不要在逗号后面包含空格。

    recipe[cookbook_name1::recipe_name],recipe[cookbook_name2::recipe_name]
  8. (可选)在 JSON attributes content (JSON 属性内容) 中,添加任何包含希望 Chef 客户端传递给目标实例的属性的自定义 JSON。

    最好是将 JSON attributes content (JSON 属性内容) 参数用于以下目的:

    • 您只想覆盖少量属性,并且您无需使用自定义说明书。

      自定义 JSON 可帮助您消除设置和维护说明书存储库以仅覆盖几个属性的额外工作。

    • 预计会变化的值。

      例如,如果您的 Chef 说明书配置了接受付款的第三方应用程序,则可以使用自定义 JSON 指定付款终端节点 URL。如果第三方软件制造商更改了付款终端节点 URL,则可以使用自定义 JSON 将付款终端节点更新为新的 URL。

  9. 对于 Chef client version (Chef 客户端版本),请指定 Chef 版本。有效值为 11121314None。 如果您指定 1114,则 Systems Manager 会在目标实例上安装正确的 Chef 客户端版本。如果您指定 None,则在运行文档的配方之前,Systems Manager 不会在目标实例上安装 Chef 客户端。默认值为 14

  10. (可选)对于 Chef client arguments (Chef 客户端参数),请指定您正在使用的 Chef 版本所支持的其他参数。要了解有关支持的参数的更多信息,请在运行 Chef 客户端的实例上运行 chef-client -h

  11. (可选)启用 Why-run 以显示在配方运行时将对目标实例进行的更改,这不会实际更改目标实例。

  12. 对于 Compliance severity (合规性严重性),请选择要报告的 Systems Manager 配置合规性结果的严重性。合规性报告指示关联状态是合规还是不合规以及您在指定的严重级别。配置合规性报告存储在一个 S3 存储桶中,您已将该存储桶指定为 Compliance report bucket (合规性报告存储桶) 参数的值(步骤 15)。有关配置合规性的更多信息,请参阅本指南中的使用配置合规性

    合规性扫描测量 Chef 配方和实例资源中指定的配置之间的偏离。有效值为 CriticalHighMediumLowInformationalUnspecifiedNone。 要跳过合规性报告,请选择 None

  13. 对于 Compliance type (合规性类型),请指定要报告其结果的合规性类型。有效值为 Association(对于 状态管理器 关联)或 Custom:()custom_type。 默认值为 Custom:Chef

  14. 对于 Compliance report bucket (合规性报告存储桶),输入 S3 存储桶的名称,该存储桶用于存储此文档执行的每个 Chef 运行的相关信息,包括资源配置和配置合规性结果。

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

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

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

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

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

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

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

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

    注意

    授予将数据写入 S3 存储桶的能力的 S3 权限是分配给实例的实例配置文件的权限,而不是执行此任务的 IAM 用户的权限。有关更多信息,请参阅 为 Systems Manager 创建 IAM 实例配置文件。此外,如果指定的 S3 存储桶位于不同的 AWS 账户中,请确保与该实例关联的实例配置文件具有写入该存储桶的必要权限。

  17. 选择创建关联

创建运行 Chef 配方的关联 (CLI)

以下过程介绍了如何使用 AWS CLI 创建 状态管理器 关联,以便使用 AWS-ApplyChefRecipes 文档运行 Chef 说明书。

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

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

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

    (A) GitHub 源

    Linux
    aws ssm create-association --name "AWS-ApplyChefRecipes" \ --targets Key=tag:TagKey,Values=TagValue \ --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"path\": \"path_to_directory_or_cookbook_to_download\", \"getOptions\": \"branch:branch_name\"}"], "RunList":["{\"recipe[cookbook_name1::recipe_name]\", \"recipe[cookbook_name2::recipe_name]\"}"], "JsonAttributesContent": ["{Custom_JSON}"], "ChefClientVersion": ["version_number"], "ChefClientArguments":["{chef_client_arguments}"], "WhyRun": true_or_false, "ComplianceSeverity": ["severity_value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": [""]}' \ --association-name "name" --schedule-expression "cron_or_rate_expression"
    Windows
    aws ssm create-association --name "AWS-ApplyChefRecipes" ^ --targets Key=tag:TagKey,Values=TagValue ^ --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"path\": \"path_to_directory_or_cookbook_to_download\", \"getOptions\": \"branch:branch_name\"}"], "RunList":["{\"recipe[cookbook_name1::recipe_name]\", \"recipe[cookbook_name2::recipe_name]\"}"], "JsonAttributesContent": ["{Custom_JSON}"], "ChefClientVersion": ["version_number"], "ChefClientArguments":["{chef_client_arguments}"], "WhyRun": true_or_false, "ComplianceSeverity": ["severity_value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": [""]}' ^ --association-name "name" --schedule-expression "cron_or_rate_expression"

    示例如下:

    aws ssm create-association --name "AWS-ApplyChefRecipes" \ --targets Key=tag:OS,Values=Linux \ --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ChefRecipeTest\", \"repository\": \"ChefCookbooks\", \"path\": \"cookbooks/HelloWorld\", \"getOptions\": \"branch:master\"}"], "RunList":["{\"recipe[HelloWorld::HelloWorldRecipe]\", \"recipe[HelloWorld::InstallApp]\"}"], "JsonAttributesContent": ["{\"state\": \"visible\",\"colors\": {\"foreground\": \"light-blue\",\"background\": \"dark-gray\"}}"], "ChefClientVersion": ["14"], "ChefClientArguments":["{--fips}"], "WhyRun": false, "ComplianceSeverity": ["Medium"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["ChefComplianceResultsBucket"]}' \ --association-name "MyChefAssociation" --schedule-expression "cron(0 2 ? * SUN *)"

    (B) S3 源

    Linux
    aws ssm create-association --name "AWS-ApplyChefRecipes" \ --targets Key=tag:TagKey,Values=TagValue \ --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_cookbook_to_download\"}"], "RunList":["{\"recipe[cookbook_name1::recipe_name]\", \"recipe[cookbook_name2::recipe_name]\"}"], "JsonAttributesContent": ["{Custom_JSON}"], "ChefClientVersion": ["version_number"], "ChefClientArguments":["{chef_client_arguments}"], "WhyRun": true_or_false, "ComplianceSeverity": ["severity_value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": [""]}' \ --association-name "name" --schedule-expression "cron_or_rate_expression"
    Windows
    aws ssm create-association --name "AWS-ApplyChefRecipes" ^ --targets Key=tag:TagKey,Values=TagValue ^ --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_cookbook_to_download\"}"], "RunList":["{\"recipe[cookbook_name1::recipe_name]\", \"recipe[cookbook_name2::recipe_name]\"}"], "JsonAttributesContent": ["{Custom_JSON}"], "ChefClientVersion": ["version_number"], "ChefClientArguments":["{chef_client_arguments}"], "WhyRun": true_or_false, "ComplianceSeverity": ["severity_value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": [""]}' ^ --association-name "name" --schedule-expression "cron_or_rate_expression"

    示例如下:

    aws ssm create-association --name "AWS-ApplyChefRecipes" ^ --targets "Key=tag:OS,Values= Windows" ^ --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/DOC-EXAMPLE-BUCKET/HelloWorld\"}"], "RunList":["{\"recipe[HelloWorld::HelloWorldRecipe]\", \"recipe[HelloWorld::InstallApp]\"}"], "JsonAttributesContent": ["{\"state\": \"visible\",\"colors\": {\"foreground\": \"light-blue\",\"background\": \"dark-gray\"}}"], "ChefClientVersion": ["14"], "ChefClientArguments":["{--fips}"], "WhyRun": false, "ComplianceSeverity": ["Medium"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["ChefComplianceResultsBucket"]}' ^ --association-name "name" --schedule-expression "cron(0 2 ? * SUN *)"
    注意

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

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

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

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

查看 Chef 资源合规性详细信息

Systems Manager 在运行 Amazon Simple Storage Service 文档时指定的 Amazon S3 (Compliance report bucket (合规性报告存储桶)AWS-ApplyChefRecipes 值中捕获有关 Chef 托管资源的合规性信息。在 S3 存储桶中搜索有关 Chef 资源失败的信息可能需要很长时间。相反,您可以在 Systems Manager Compliance (合规性) 页面上查看该信息。

Systems Manager 合规性扫描收集在最近一次 Chef 运行中创建或检查的托管节点上的资源的相关信息。资源可以包括文件、目录、systemd 服务、yum 软件包、模板化文件、gem 软件包和依赖说明书等。

合规性资源摘要部分显示失败的资源数。在以下示例中,ComplianceTypeCustom:Chef,并且一个资源不合规。

注意

Custom:Chef 文档中的默认值。ComplianceTypeAWS-ApplyChefRecipes该值是可自定义的。


                        在 Compliance (合规性) 页面的 Compliance resources summary (合规性资源摘要) 部分中查看计数。

Details overview for resources (资源的详细概述) 部分显示有关不合规的 AWS 资源的信息。此部分还包括对其运行合规性的 Chef 资源类型、问题的严重性、合规性状态以及指向更多信息的链接(如适用)。


                        查看 Chef 托管资源失败的合规性详细信息

View output (查看输出) 显示详细状态的最后 4000 个字符。Systems Manager 将异常作为第一个元素,然后查找详细消息,并显示尽可能多的内容,直至达到 4000 个字符的限制。该过程显示在引发异常之前输出的日志消息,这些消息是用于故障排除的最相关消息。

有关如何查看合规性信息的信息,请参阅 AWS Systems Manager 配置合规性

关联失败将影响合规性报告

如果 状态管理器 关联失败,则不会报告合规性数据。例如,如果 Systems Manager 尝试从实例无权访问的 S3 存储桶中下载 Chef 说明书,则关联将失败,并且 Systems Manager 不会报告合规性数据。