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

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

可以使用 AWS-ApplyChefRecipes SSM 文档创建运行 Chef 配方的 State Manager 关联。State Manager 是 Amazon Systems Manager 的一种功能。可以使用 AWS-ApplyChefRecipes SSM 文档定位基于 Linux 的 Systems Manager 托管节点。本文档为运行 Chef 配方提供了以下好处:

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

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

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

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

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

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

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

注意

运行 Chef 配方的关联在 macOS 上不受支持。

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

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

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

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

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

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

验证您是否能访问 Chef.io 网站,以便在运行列表中指定的任何说明书都能在 Systems Manager 文档 (SSM 文档)运行时安装。支持使用嵌套的 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 配方的 State Manager 关联时,请注意,文档运行时会在 Systems Manager 托管节点上安装 Chef 客户端软件,除非您将 Chef 客户端版本的值设置到 None。此操作使用 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 合规性的更多信息,请参阅 Amazon Systems Manager Compliance

记录文档运行

当您通过使用 State Manager 关联运行 Systems Manager 文档(SSM 文档)时,您可以配置关联以选择文档运行的输出,并且可以将输出发送到 Amazon S3 或 Amazon CloudWatch Logs(CloudWatch Logs)。要帮助在关联运行完后轻松进行故障排除,请验证是否已将关联配置为将命令输出写入 Amazon 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" }
重要

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

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

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

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

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

    -或者-

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

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

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

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

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

  7. 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" }
  8. Run list (运行列表) 中,按以下格式列出要运行的配方,并用逗号将每个配方分隔开,如下所示。请不要在逗号后面包含空格。

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

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

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

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

    • 预计会变化的值。

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

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

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

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

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

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

  14. 对于 Compliance type (合规性类型),请指定要报告其结果的合规性类型。有效值为 Association(对于 State Manager 关联)或 Custom:custom_type。原设定值为 Custom:Chef

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

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

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

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

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

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

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

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

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

    注意

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

  18. 选择创建关联

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

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

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

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

  2. 运行以下命令之一来创建关联,该关联通过使用标签定位节点来运行 Chef 说明书。将每个示例资源占位符替换为您自己的信息。命令 (A) 使用 GitHub 作为源类型。命令 (B) 使用 Amazon S3 作为源类型。

    (A) GitHub 源

    Linux & macOS
    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": ["DOC-EXAMPLE-BUCKET"]}' \ --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": ["DOC-EXAMPLE-BUCKET"]}' ^ --association-name "name" ^ --schedule-expression "cron_or_rate_expression"

    以下是示例。

    Linux & macOS
    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 *)"
    Windows
    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 & macOS
    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": ["DOC-EXAMPLE-BUCKET"]}' \ --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": ["DOC-EXAMPLE-BUCKET"]}' ^ --association-name "name" ^ --schedule-expression "cron_or_rate_expression"

    以下是示例。

    Linux & macOS
    aws ssm create-association --name "AWS-ApplyChefRecipes" \ --targets "Key=tag:OS,Values= Linux" \ --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 *)"
    Windows
    aws ssm create-association --name "AWS-ApplyChefRecipes" ^ --targets "Key=tag:OS,Values= Linux" ^ --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 *)"
    注意

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

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

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

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

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

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

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

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

注意

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


                        查看计数合规性页面合规性资源摘要部分中的计数。

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


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

(View output) 查看输出 显示详细状态的最后 4,000 个字符。Systems Manager 先将异常作为第一个元素,查找详细消息,并显示它们,直至达到 4000 个字符的配额。该过程显示在引发异常之前输出的日志消息,这些消息是用于故障排除的最相关消息。

有关如何查看合规性信息的信息,请参阅 Amazon Systems Manager Compliance

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

如果 State Manager 关联失败,则不会报告合规性数据。例如,如果 Systems Manager 尝试从节点没有权限访问的 S3 存储桶中下载 Chef 说明书,则关联将失败,并且 Systems Manager 不会报告合规性数据。