先决条件：设置您的关联、存储库和说明书运行配方时向目标应用 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（Chef 11 到 Chef 18）。
在目标节点上自动安装 Chef 客户端软件。
（可选）在目标节点上运行 Systems Manager 合规性检查，并将合规性检查的结果存储在 Amazon Simple Storage Service (Amazon S3) 存储桶中。
在文档的单次运行中运行多个说明书和配方。
（可选）在 why-run 模式下运行配方，以显示哪些配方会在未进行更改的情况下在目标节点上发生更改。
（可选）将自定义 JSON 属性应用于 chef-client 运行。
（可选）应用存储在指定位置源文件中的自定义 JSON 属性。

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

注意

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

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

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

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

说明书应支持您的目标 Systems Manager 托管式节点的基于 Linux 的操作系统。
说明书将适用于您使用的 Chef 客户端版本（Chef 11 到 Chef 18）。
说明书与 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 关联之前需注意，文档运行时会在 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 。有关更多信息，请参阅在 Systems Manager 中使用关联。。

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

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

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

覆盖少量属性

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

使用自定义 JSON 指定可能随运行而变化的值。例如，如果您的 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 作为说明书源

您可以在自定义 HTTP 位置将 Chef 说明书存储为单个 .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 作为说明书源

您还可以将 Chef 说明书作为单个 .zip 或 tar.gz 文件或者目录结构存储和下载到 Amazon S3 中。要从 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"
}

重要

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

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

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

访问 https://console.aws.amazon.com/systems-manager/，打开 Amazon 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。如果您指定 11 到 18 之间的一个数字（包含这两个数字），则 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) 创建 State Manager 关联，以便使用 AWS-ApplyChefRecipes 文档运行 Chef 说明书。

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

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

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

注意

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

Details overview for resources (资源的详细概述)部分显示有关不合规的 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 Playbook 的关联

自动更新 SSM Agent (CLI)