先决条件：设置您的关联、存储库和说明书运行配方时向目标应用 JSON 属性使用 Git 作为说明书源使用 GitHub 作为说明书源使用 HTTP 作为说明书源使用 Amazon S3 作为说明书源创建运行Chef配方的关联（控制台）创建运行Chef配方的关联 (CLI)查看 Chef 资源合规性详细信息

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

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

支持Chef（Chef11 到 Chef 18）的多个版本。
在目标节点上自动安装Chef客户端软件。
（可选）在目标节点上运行 Systems Manager 合规性检查，并将合规性检查的结果存储在 Amazon Simple Storage Service (Amazon S3) 存储桶中。
在文档的单次运行中运行多个说明书和配方。
（可选）在 why-run 模式下运行配方，以显示哪些配方会在未进行更改的情况下在目标节点上发生更改。
（可选）将自定义 JSON 属性应用于 chef-client 运行。
（可选）应用存储在指定位置源文件中的自定义 JSON 属性。

您可以使用 Git、GitHub、HTTP 或 Amazon S3 存储桶作为您在文档中指定的食Chef谱和食谱的下载源。AWS-ApplyChefRecipes

注意

macOS或不支持运行Chef配方的关联Windows Server。

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

在创建AWS-ApplyChefRecipes文档之前，请准备好您的Chef食谱和食谱存储库。如果你还没有想要使用的Chef食谱，你可以先使用一本为你准备的测试HelloWorld食谱。 Amazon 默认情况下，AWS-ApplyChefRecipes 文档已指向此说明书。您的说明书的设置应类似于以下目录结构。在以下示例中，jenkins和nginx是Chef网站上提供的Chef食谱示例。Chef Supermarket

尽管 Amazon 无法在Chef Supermarket网站上正式支持食谱，但其中许多都适用于该AWS-ApplyChefRecipes文档。以下是在测试社群说明书时需要确认的标准示例：

说明书应支持您的目标 Systems Manager 托管式节点的基于 Linux 的操作系统。
该食谱应该对你使用的Chef客户端版本（Chef11 到 Chef 18）有效。
该食谱与 Chef 服务器兼容Chef Infra Client，且不需要 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关联之前，请注意，除非将Chef客户端版本的值设置为，否则文档运行会在 Systems Manager 托管节点上安装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。

记录文档运行

使用关联运行 Systems Manager 文档（SSM 文档）时，您可以将State Manager关联配置为选择文档运行的输出，并且可以将输出发送到 Amazon S3 或 Amazon CloudWatch 日志（日CloudWatch 志）。为了便于在关联完成运行后进行故障排除，请验证关联是否已配置为将命令输出写入 Amazon S3 存储桶或 CloudWatch 日志。有关更多信息，请参阅在 Systems Manager 中使用关联。。

运行配方时向目标应用 JSON 属性

在关联运行期间，您可以为Chef客户端指定 JSON 属性以应用于目标节点。设置关联时，您可以提供原始 JSON，也可以提供存储在 Amazon S3 中的 JSON 文件路径。

如果您想自定义配方的运行方式而无需修改配方本身，请使用 JSON 属性，例如：

覆盖少量属性

使用自定义 JSON 可以避免维护一个配方的多个版本，以适应细微差异。
提供变量值

使用自定义 JSON 来指定可能更改的值 run-to-run。例如，如果您的Chef食谱配置了接受付款的第三方应用程序，则可以使用自定义 JSON 来指定付款端点 URL。

在原始 JSON 中指定属性

以下是可用于为Chef食谱指定自定义 JSON 属性的格式示例。


{"filepath":"/tmp/example.txt", "content":"Hello, World!"}

指定 JSON 文件的路径

以下是可用于为Chef食谱指定自定义 JSON 属性的路径的格式示例。


{"sourceType":"s3", "sourceInfo":"someS3URL1"}, {"sourceType":"s3", "sourceInfo":"someS3URL2"}

使用 Git 作为说明书源

该AWS-ApplyChefRecipes文档使用aws:downloadContent插件下载Chef食谱。要从 Git 下载内容，请以 JSON 格式指定有关 Git 存储库的信息，如下例所示。将每个 example-resource-placeholder 替换为您自己的信息。


{
   "repository":"GitCookbookRepository",
   "privateSSHKey":"{{ssm-secure:ssh-key-secure-string-parameter}}",
   "skipHostKeyChecking":"false",
   "getOptions":"branch:refs/head/main",
   "username":"{{ssm-secure:username-secure-string-parameter}}",
   "password":"{{ssm-secure:password-secure-string-parameter}}"
}

使用 GitHub 作为说明书源

AWS-ApplyChefRecipes 文档使用 aws:downloadContent 插件下载说明书。要从中下载内容GitHub，请以 JSON 格式指定有关GitHub存储库的信息，如下例所示。将每个 example-resource-placeholder 替换为您自己的信息。


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

使用 HTTP 作为说明书源

您可以将Chef食谱存储在自定义 HTTP 位置，既可以是单个食谱，.zip也可以是tar.gz文件结构，也可以是目录结构。要从 HTTP 下载内容，请以 JSON 格式指定文件或目录的路径，如下例所示。将每个 example-resource-placeholder 替换为您自己的信息。


{
   "url":"https://my.website.com/chef-cookbooks/HelloWorld.zip",
   "allowInsecureDownload":"false",
   "authMethod":"Basic",
   "username":"{{ssm-secure:username-secure-string-parameter}}",
   "password":"{{ssm-secure:password-secure-string-parameter}}"
}

使用 Amazon S3 作为说明书源

您也可以在 Amazon S3 中以单个、tar.gz文件.zip或目录结构的形式存储和下载Chef食谱。要从 Amazon S3 下载内容，请以 JSON 格式指定文件的路径，如下例所示。将每个 example-resource-placeholder 替换为您自己的信息。

示例 1：下载特定说明书


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

示例 2：下载目录的内容


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

重要

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

创建运行Chef配方的关联（控制台）

以下过程介绍如何使用该AWS-ApplyChefRecipes文档使用 Systems Manager 控制台创建运行Chef食谱的State Manager关联。

打开 Amazon Systems Manager 控制台，网址为 https://console.aws.amazon.com/systems-manager/。
在导航窗格中，选择 State Manager。

-或者-

如果首先打开 Amazon Systems Manager 主页，请选择菜单图标 ( ) 以打开导航窗格，然后选择State Manager。
选择 State Manager，然后选择 Create Association。
对于 Name (名称)，请输入一个名称，该名称可帮助您记住关联的用途。
在 Document (文档) 列表中，选择 AWS-ApplyChefRecipes。
在参数中，对于源类型，选择 Git、GitHub、HTTP 或 S3。
对于源信息，请使用您在步骤 6 中选择的源类型的适当格式输入说明书源信息。有关更多信息，请参阅以下主题：
在 Run list (运行列表) 中，按以下格式列出要运行的配方，并用逗号将每个配方分隔开，如下所示。请不要在逗号后面包含空格。将每个 example-resource-placeholder 替换为您自己的信息。
```
recipe[cookbook-name1::recipe-name],recipe[cookbook-name2::recipe-name]
```
（可选）指定您希望Chef客户端传递给目标节点的自定义 JSON 属性。
1. 在 JSON 属性内容中，添加您希望Chef客户端传递给目标节点的所有属性。
2. 在 JSON 属性源中，添加您希望Chef客户端传递给目标节点的任何属性的路径。
有关更多信息，请参阅运行配方时向目标应用 JSON 属性。
对于Chef客户端版本，请指定Chef版本。有效值为 11 到 18 或 None。如果您指定介于 1118（含）之间的数字，则 Systems Manager 会在您的目标节点上安装正确的Chef客户端版本。如果您指定None，则在运行文档的配方之前，Systems Manager 不会在目标节点上安装Chef客户端。
（可选）对于Chef客户端参数，请指定Chef您正在使用的版本所支持的其他参数。要了解有关支持的参数的更多信息，请在运行Chef客户端的节点chef-client -h上运行。
（可选）启用 Why-run 以显示在配方运行时对目标节点进行的更改，这不会实际更改目标节点。
对于 Compliance severity (合规性严重性)，请选择要报告的 Systems Manager 合规性结果的严重性。合规性报告指示关联状态是合规还是不合规以及您在指定的严重级别。将合规性报告存储在一个 S3 存储桶中，您已将该存储桶指定为 Compliance report bucket (合规性报告存储桶) 参数的值（步骤 14）。有关合规性的更多信息，请参阅本指南中的使用 Compliance。

合规性扫描可测量Chef配方中指定的配置与节点资源之间的偏差。有效值为 Critical、High、Medium、Low、Informational、Unspecified 或 None。要跳过合规性报告，请选择 None。
对于 Compliance type (合规性类型)，请指定要报告其结果的合规性类型。有效值为 Association（对于 State Manager 关联）或 Custom: 自定义类型。默认值为 Custom:Chef。
在合规性报告存储桶中，输入 S3 存储桶的名称，该存储桶用于存储有关本文档执行的每次Chef运行的信息，包括资源配置和合规性结果。
在 Rate control（速率控制）中，配置用于在托管式节点机群中运行 State Manager 关联的选项。有关使用速率控制的信息，请参阅关于 State Manager 关联中的目标和速率控制。

在 Concurrency (并发) 中，选择一个选项：
- 选择 targets (目标) 输入可同时运行关联的目标的绝对数量。
- 选择 percentage (百分比) 输入可同时运行关联的目标集的百分比。
在 Error threshold (错误阈值) 中，选择一个选项：
- 选择 errors (错误) 以输入允许的错误绝对数量，超过该数量后 State Manager 停止对其他目标运行关联。
- 选择 percentage (百分比) 以输入允许的错误百分比，超过该百分比后 State Manager 停止对其他目标运行关联。
（可选）对于 Output options (输出选项)，要将命令输出保存到文件，请选中 Enable writing output to S3 (启用将输出写入 S3) 方框。在方框中输入存储桶和前缀（文件夹）名称。

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

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

以下过程介绍如何使用 Amazon Command Line Interface (Amazon CLI) 通过AWS-ApplyChefRecipes文档创建运行 Chef 食谱的State Manager关联。

安装并配置 Amazon Command Line Interface (Amazon CLI)（如果尚未安装）。

有关信息，请参阅安装或更新 Amazon CLI的最新版本。

运行以下命令之一来创建在具有指定标签的目标节点上运行Chef食谱的关联。使用适合您说明书源类型和操作系统的命令。将每个 example-resource-placeholder 替换为您自己的信息。

Git 源

Linux & macOS


aws ssm create-association --name "AWS-ApplyChefRecipes" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["Git"],"SourceInfo":["{\"repository\":\"repository-name\", \"getOptions\": \"branch:branch-name\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --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":["Git"],"SourceInfo":["{\"repository\":\"repository-name\", \"getOptions\": \"branch:branch-name\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' ^
    --association-name "name" ^
    --schedule-expression "cron-or-rate-expression"

GitHub 来源

下面是一个例子。

HTTP 源

Linux & macOS


aws ssm create-association --name "AWS-ApplyChefRecipes" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["HTTP"],"SourceInfo":["{\"url\":\"url-to-zip-file|directory|cookbook\", \"authMethod\": \"auth-method\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --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":["HTTP"],"SourceInfo":["{\"url\":\"url-to-zip-file|directory|cookbook\", \"authMethod\": \"auth-method\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --association-name "name" ^
    --schedule-expression "cron-or-rate-expression"

Amazon S3 源

下面是一个例子。

系统将创建关联，除非指定的 cron 或 rate 表达式阻止，否则系统将在目标节点上运行该关联。

注意

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

运行以下命令，查看您刚才创建的关联的状态。
```
aws ssm describe-association --association-id "ID"
```

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

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

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

合规性资源摘要部分显示失败的资源数。在以下示例中，ComplianceType为自定义:Chef，其中一个资源不合规。

注意

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

资源详细信息概述部分显示有关不合规的 Amazon 资源的信息。本节还包括运行合规性所依据的Chef资源类型、问题的严重性、合规性状态以及指向更多信息的链接（如果适用）。

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

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

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

如果 State Manager 关联失败，则不会报告合规性数据。例如，如果 Systems Manager 尝试从节点无权访问的 S3 存储桶下载一Chef本食谱，则关联将失败，Systems Manager 不会报告任何合规性数据。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

创建运行Ansible剧本的关联

自动更新 SSM Agent (CLI)