使用 Amazon S3 存储构件解析 MOF 文件中的凭证在 MOF 文件中使用令牌先决条件创建运行 MOF 文件的关联问题排查查看 DSC 资源合规性详细信息

演练：创建运行 MOF 文件的关联

您可以使用 AWS-ApplyDSCMofs SSM 文档运行托管式对象格式 (MOF) 文件，以通过 State Manager（Amazon Systems Manager 的一种功能）在 Windows Server 托管式节点上强制执行期望状态。AWS-ApplyDSCMofs 文档有两种执行模式。在第一种模式下，您可以配置关联来扫描并报告托管式节点是否处于指定 MOF 文件中定义的期望状态。在第二种模式下，您可以运行 MOF 文件并根据 MOF 文件中定义的资源及其值更改节点的配置。AWS-ApplyDSCMofs 文档允许您从 Amazon Simple Storage Service (Amazon S3)、本地共享或具有 HTTPS 域的安全网站下载和运行 MOF 配置文件。

State Manager 在每个关联运行期间记录并报告每个 MOF 文件执行的状态。State Manager 还将每个 MOF 文件执行的输出报告为合规性事件，可在 Amazon Systems Manager 合规性页面上查看该事件。

MOF 文件执行基于 Windows PowerShell Desired State Configuration(PowerShell DSC) 构建而成。PowerShell DSC 是一个声明性平台，用于配置、部署和管理 Windows 系统。PowerShell DSC 允许管理员用名为 DSC 配置的简单文本文档来描述其需要的服务器配置方式。PowerShell DSC 配置是一个专门的 PowerShell 脚本，该脚本描述任务是什么但不描述如何执行任务。运行配置会生成一个 MOF 文件。该 MOF 文件可以应用于一台或多台服务器，以在这些服务器中实现所需配置。PowerShell DSC 资源执行强制实施配置的实际工作。有关更多信息，请参阅 Windows PowerShell Desired State Configuration Overview。

使用 Amazon S3 存储构件

如果使用 Amazon S3 存储 PowerShell 模块、MOF 文件、合规性报告或状态报告，则 Amazon Systems Manager SSM Agent使用的 Amazon Identity and Access Management (IAM) 角色必须拥有存储桶的 GetObject 和 ListBucket 权限。如果您不提供这些权限，系统将返回拒绝访问 错误。以下是有关在 Amazon S3 中存储构件的重要信息。

如果存储桶位于不同的 Amazon Web Services 账户中，请创建一个存储桶资源策略，向该账户（或 IAM 角色）授予 GetObject 和 ListBucket 权限。
如果要使用自定义 DSC 资源，则可从 Amazon S3 存储桶中下载这些资源。您也可以从 PowerShell 库中自动安装这些资源。
如果使用 Amazon S3 作为模块源，请以 Zip 文件形式上传该模块，采用以下区分大小写的格式：ModuleName_ModuleVersion.zip。例如：MyModule_1.0.0.zip。
所有文件都必须位于存储桶根中。不支持文件夹结构。

解析 MOF 文件中的凭证

可使用 Amazon Secrets Manager 或 Amazon Systems Manager Parameter Store 来解析凭证。这样，可以设置自动凭证轮换。DSC 也可以自动将凭证传播到服务器，而不必重新部署 MOF。

要在配置中使用 Amazon Secrets Manager 密钥，请创建一个 PSCredential 对象，其中用户名是包含凭证的密钥的 SecretId 或 SecretARN。可为密码指定任意值。该值将被忽略。以下为示例。


Configuration MyConfig
{
   $ss = ConvertTo-SecureString -String 'a_string' -AsPlaintext -Force
   $credential = New-Object PSCredential('a_secret_or_ARN', $ss)

    Node localhost
    {
       File file_name
       {
           DestinationPath = 'C:\MyFile.txt'
           SourcePath = '\\FileServer\Share\MyFile.txt'
           Credential = $credential
       }
    }
}

请使用配置数据中的 PsAllowPlaintextPassword 设置来编译 MOF。因为凭证只包含一个标签，所以可以这样做。

在 Secrets Manager 中，确保节点具有 IAM 托管式策略和（可选的）密钥资源策略（如果存在）中的 GetSecretValue 访问权限。要使用 DSC，密钥必须采用以下格式。


{ 'Username': 'a_name', 'Password': 'a_password' }

密钥可以具有其他属性（例如，用于轮换的属性），但它至少需具有用户名和密码属性。

建议使用多用户轮换方法，这样，您有两组不同的用户名和密码，轮换 Amazon Lambda 函数会轮流使用这两组用户名和密码。此方法允许您有多个活动账户，消除了在轮换期间锁定用户的风险。

在 MOF 文件中使用令牌

通过令牌可以在编译 MOF 之后修改资源属性值。这样，您可以在需要相似配置的多台服务器上重用通用 MOF 文件。

令牌替换仅适用于 String 类型的资源属性。但是，如果资源具有嵌套的 CIM 节点属性，它也会从该 CIM 节点的 String 属性中解析令牌。不能将令牌替换用于数字或数组。

例如，考虑以下场景：您使用的是 xComputerManagement 资源，并且您希望使用 DSC 重命名计算机。通常，您需要对该计算机使用一个专用的 MOF 文件。但是，有了令牌支持，您可以创建一个 MOF 文件并将其应用于您的所有节点。在 ComputerName 属性中，不必将计算机名称硬编码到 MOF 中，您可以使用实例标签类型的令牌。在 MOF 解析期间会解析此值。请参阅以下示例。


Configuration MyConfig
{
    xComputer Computer
    {
        ComputerName = '{tag:ComputerName}'
    }
}

然后，您可以在 Systems Manager 控制台中的托管式节点上设置标签，或在 Amazon EC2 控制台中设置 Amazon Elastic Compute Cloud (Amazon EC2) 标签。运行该文档时，脚本将 {tag:ComputerName} 令牌替换为实例标签的值。

您还可以将多个标签组合到单个属性中，如下面的示例所示。


Configuration MyConfig
{
    File MyFile
    {
        DestinationPath = '{env:TMP}\{tag:ComputerName}'
        Type = 'Directory'
    }
}

您可以使用以下 5 种不同类型的令牌：

标签：Amazon EC2 或托管式节点标签。
tagb64：与标签相同，但系统使用 base64 对值解码。这样您可以在标签值中使用特殊字符。
env：解析环境变量。
ssm：Parameter Store 值。仅支持字符串和安全字符串类型。
tagssm：与标签相同，但如果未在节点上设置标签，系统将尝试从同名的 Systems Manager 参数中解析值。如果需要“原定设置全局值”，但希望能够在单个节点（例如，一站式部署）中覆盖该值时，此令牌很有用。

以下是使用 ssm 令牌类型的 Parameter Store 示例。


File MyFile
{
    DestinationPath = "C:\ProgramData\ConnectionData.txt"
    Content = "{ssm:%servicePath%/ConnectionData}"
}

令牌通过使 MOF 文件变为通用和可重用，在减少冗余代码方面发挥了重要作用。如果可以避免特定于服务器的 MOF 文件，则无需 MOF 构建服务。MOF 构建服务会增加成本、减少调配时间并增加分组节点之间因编译其 MOF 时在编译服务器上安装的模块版本不同而产生配置偏差的风险。

先决条件

在创建用于运行 MOF 文件的关联之前，请验证托管式节点是否已安装以下必备组件：

Windows PowerShell 5.0 或更高版本。有关更多信息，请参阅 Microsoft.com 上的 Windows PowerShell 系统要求。
Amazon Tools for Windows PowerShell 1.5.13 版或更高版本。
SSM Agent 2.2 或更高版本。

创建运行 MOF 文件的关联

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

-或者-

如果首先打开 Amazon Systems Manager 主页，选择菜单图标（ ) 以打开导航窗格，然后选择 State Manager。
选择 State Manager，然后选择 创建关联。
在名称字段中指定名称。您可以自由选择，但我们建议您这样做。名称可以帮助了解您在创建关联时为关联考虑的用途。名称不得包含空格。
在 Command (文档) 列表中，选择 AWS-ApplyDSCMofs。
在 Parameters (参数) 部分中，指定您选择的必需和可选输入参数。
1. Mofs To Apply (要应用的 Mof)：指定要在此关联运行时运行的一个或多个 MOF 文件。使用逗号分隔 MOF 文件的列表。您可以指定以下用于查找 MOF 文件的选项。
  - Amazon S3 存储桶名。存储桶名称必须使用小写字母。可使用以下格式指定此信息：
```
s3:doc-example-bucket:MOF_file_name.mof
```
    如果要指定 Amazon Web Services 区域，请使用以下格式：
```
s3:bucket_Region:doc-example-bucket:MOF_file_name.mof
```
  - 安全的网站。可使用以下格式指定此信息。
```
https://domain_name/MOF_file_name.mof
```
    以下是示例。
```
https://www.example.com/TestMOF.mof
```
  - 本地共享中的文件系统。可使用以下格式指定此信息。
```
\server_name\shared_folder_name\MOF_file_name.mof
```
    以下是示例。
```
\StateManagerAssociationsBox\MOFs_folder\MyMof.mof
```
2. Service Path (服务路径)：（可选）服务路径可以是要将报告和状态信息写入到的 Amazon S3 存储桶前缀。服务路径也可以是用于基于 Parameter Store 参数的标签的路径。在解析基于参数的标签时，系统将使用 {ssm:%servicePath%/parameter_name} 将 servicePath 值注入参数名称中。例如，如果服务路径是“WebServers/Production”，则系统将该参数解析为：WebServers/Production/parameter_name。在同一账户中运行多个环境时，此服务路径很有用。
3. Report Bucket Name (报告存储桶名称)：（可选）输入要写入合规性数据的 Amazon S3 存储桶的名称。报告以 JSON 格式保存在此存储桶中。
  
  注意
  您可以用存储桶所在的区域作为存储桶名称的前缀。下面是一个示例：us-west-2:MyMOFBucket。如果对不包括 us-east-1 在内的特定区域中的 Amazon S3 端点使用代理，则用区域作为存储桶名称的前缀。如果存储桶名称不含前缀，它会使用 us-east-1 端点自动发现存储桶区域。
4. 操作模式：选择：选择 State Manager 行为时运行 AWS-ApplyDSCMofs 关联：
  - Apply（应用）：更正不合规的节点配置。
  - ReportOnly：不更正节点配置，但录入所有合规性数据并报告不合规节点。
5. Status Bucket Name (状态存储桶名称)：（可选）输入要将 MOF 执行状态信息写入到的 Amazon S3 存储桶的名称。这些状态报告是节点的最新合规性运行的单例摘要。这意味着，下次关联运行 MOF 文件时，将覆盖该报告。
  
  注意
  您可以用存储桶所在的区域作为存储桶名称的前缀。示例如下：us-west-2:doc-example-bucket。如果对不包括 us-east-1 在内的特定区域中的 Amazon S3 端点使用代理，则必须用区域作为存储桶名称的前缀。如果存储桶名称不含前缀，它会使用 us-east-1 端点自动发现存储桶区域。
6. Module Source Bucket Name (模块源存储桶名称)：（可选）输入包含 PowerShell 模块文件的 Amazon S3 存储桶的名称。如果您指定无中，为下一个选项选择真，允许 PS Gallery 模块源。
  
  注意
  您可以用存储桶所在的区域作为存储桶名称的前缀。示例如下：us-west-2:doc-example-bucket。如果对不包括 us-east-1 在内的特定区域中的 Amazon S3 端点使用代理，则必须用区域作为存储桶名称的前缀。如果存储桶名称不含前缀，它会使用 us-east-1 端点自动发现存储桶区域。
7. Allow PS Gallery Module Source (允许 PS 库模块源)：（可选）选择 True 从 https://www.powershellgallery.com/ 下载 PowerShell 模块。如果选择假，请为上一个选项 ModuleSourceBucketName 指定源。
8. Proxy Uri (代理 URI)：（可选）使用此选项可从代理服务器下载 MOF 文件。
9. Reboot Behavior ()：（可选）如果 MOF 文件执行需要重启，请指定以下重启行为之一：
  - AfterMof：在所有 MOF 执行完成后重启节点。即使多个 MOF 执行请求重启，系统也会等到所有 MOF 执行完成才重启。
  - Immediately（立即）：只要 MOF 执行请求，即重启节点。如果实例运行请求重启的多个 MOF 文件，则会多次重启该节点。
  - Never（从不）：即使 MOF 执行明确请求重启，节点也不重启。
10. Use Computer Name For Reporting (将计算机名称用于报告)：（可选）启用此选项可在报告合规性信息时使用计算机的名称。原定设置值为 false，这意味着系统在报告合规性信息时会使用节点 ID。
11. Enable Verbose Logging (启用详细日志记录)：（可选）建议在首次部署 MOF 文件时启用详细日志记录。
  
  重要
  启用后，详细日志记录会向 Amazon S3 存储桶中写入比标准关联执行日志记录更多的数据。这可能会导致性能变慢，并且 Amazon S3 的存储费用可能会变高。要缓解存储大小问题，建议在 Amazon S3 存储桶中启用生命周期策略。有关更多信息，请参阅 Amazon Simple Storage Service 用户指南中的如何为 S3 Bucket 创建生命周期策略？。
12. Enable Debug Logging (启用调试日志记录)：（可选）建议启用调试日志记录排除 MOF 故障。我们还建议您在正常使用时禁用此选项。
  
  重要
  启用后，调试日志记录会向 Amazon S3 存储桶中写入比标准关联执行日志记录更多的数据。这可能会导致性能变慢，并且 Amazon S3 的存储费用可能会变高。要缓解存储大小问题，建议在 Amazon S3 存储桶中启用生命周期策略。有关更多信息，请参阅 Amazon Simple Storage Service 用户指南中的如何为 S3 Bucket 创建生命周期策略？。
13. Compliance Type (合规性类型)：（可选）指定要在报告合规性信息时使用的合规性类型。默认的合规性类型为 Custom:DSC (自定义:DSC)。如果创建多个运行 MOF 文件的关联，请确保为每个关联指定不同的合规性类型。否则，使用 Custom:DSC 的每个其他关联都将覆盖现有的合规性数据。
14. Pre Reboot Script (重启前脚本)：（可选）指定在配置指示需要重启时要运行的脚本。该脚本将在重启之前运行。该脚本必须为单行。使用分号分隔其他行。
在 Targets (目标) 部分中，选择 Specifying tags (指定标签) 或 Manually Selecting Instance (手动选择实例)。如果选择使用标签将资源设置为目标，请在提供的字段中输入标签键和标签值。有关使用目标的更多信息，请参阅关于 State Manager 关联中的目标和速率控制。
在 Specify schedule (指定计划) 部分中，选择 On Schedule (按计划) 或 No schedule (无计划)。如果选择 On Schedule (按计划)，则可使用提供的按钮为关联创建 cron 或 rate 计划。
在 Advanced options (高级选项) 部分中：
- 在 Compliance severity (合规性严重级别) 中，选择关联的严重级别。合规性报告指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息，请参阅关于 State Manager 关联合规性。
在 Rate control（速率控制）部分，配置用于跨托管式节点机群运行 State Manager 关联的选项。有关这些选项的详细信息，请参阅关于 State Manager 关联中的目标和速率控制。

在并发部分中，选择一个选项：
- 选择 targets (目标) 输入可同时运行关联的目标的绝对数量。
- 选择 percentage (百分比) 输入可同时运行关联的目标集的百分比。
在错误阈值部分中，选择一个选项：
- 选择 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 服务角色具有写入该存储桶的所需权限。
选择创建关联。

State Manager 在指定的节点或目标中创建并立即运行关联。在初始执行后，关联根据定义的计划和以下规则按间隔运行：

State Manager 对间隔开启时处于线上状态的节点运行关联，并跳过离线节点。
State Manager 在间隔期间会尝试对所有已配置的节点运行关联。
如果在某个周期内未运行某一关联（例如，由于并发值限制了可以同时处理关联的节点数），State Manager 将尝试在下一个周期运行该关联。
State Manager 会记录所有已跳过间隔的历史记录。可在 Execution History (执行历史记录) 选项卡上查看历史记录。

注意

AWS-ApplyDSCMofs 是 Systems Manager 命令文档这意味着，您也可以使用 Run Command （Amazon Systems Manager 的一种功能）运行此文档。有关更多信息，请参阅Amazon Systems Manager Run Command。

问题排查

本部分包含的信息可帮助您解决在创建运行 MOF 文件的关联时遇到的问题。

启用增强的日志记录

解决问题的第一步是启用增强型日志记录。具体来说，是执行以下操作：

验证关联是否配置是将命令输出写入 Amazon S3 或 Amazon CloudWatch Logs (CloudWatch)。
将 Enable Verbose Logging (启用详细日志记录) 参数设置为 True。
将 Enable Debug Logging (启用调试日志记录) 参数设置为 True。

启用详细和调试日志记录后，Stdout 输出文件将包含有关脚本执行的详细信息。此输出文件可帮助您确定脚本失败的位置。Stderr 输出文件包含在脚本执行期间发生的错误。

常见问题

本节包含有关在创建运行 MOF 文件的关联时出现的常见问题的信息以及解决这些问题的步骤。

我的 MOF 未应用

如果 State Manager 未能将关联应用到您的节点，请首先查看 Stderr 输出文件。此文件可以帮助您了解问题的根本原因。另外，请确认：

此节点具有与 MOF 相关的所有 Simple Storage Service (Amazon S3) 存储桶所需访问权限。具体来说：
- s3:GetObject permissions (s3:GetObject 权限)：这是私有 Amazon S3 存储桶中的 MOF 文件和 Amazon S3 存储桶中的自定义模块必需的权限。
- s3:PutObject permission (s3:PutObject 权限)：在将合规性报告和合规性状态写入 Amazon S3 存储桶时需要此权限。
如果使用标签，则需确保该节点具有所需的 IAM policy。使用标签需要实例 IAM 角色具有允许 ec2:DescribeInstances 和 ssm:ListTagsForResource 操作的策略。
确保该节点已分配预期的标签或 SSM 参数。
请确保标签或 SSM 参数不包含拼写错误。
尝试对节点本地应用 MOF，以确保 MOF 文件本身没有问题。

我的 MOF 似乎失败了，但 Systems Manager 执行成功

如果 AWS-ApplyDSCMofs 文档成功运行，则 Systems Manager 执行状态将显示 Success (成功)。此状态并不反映节点针对 MOF 文件中的配置要求的合规性状态。要查看节点的合规性状态，请查看合规性报告。您可以查看 Amazon S3 报告存储桶中的 JSON 报告。这适用于 Run Command 和 State Manager 执行。此外，对于State Manager ，您可以在 Systems Manager 合规性页面上查看合规性详细信息。

Stderr 状态：尝试访问服务时名称解析失败

此错误指示脚本无法访问远程服务。最有可能的情况是，该脚本无法访问 Amazon S3 。当脚本尝试将合规性报告或合规性状态写入文档参数中提供的 Amazon S3 存储桶时，通常会发生此问题。通常，当计算环境使用包含允许清单的防火墙或透明代理时，会出现此错误。要解决此问题，请执行以下操作：

将特定于区域的存储桶语法用于所有 Amazon S3 存储桶参数。例如，Mofs to Apply (要应用的 Mof) 参数的格式应如下所示：

s3:bucket-region:bucket-name:mof-file-name.mof。

示例如下：s3:us-west-2:doc-example-bucket:my-mof.mof

报告、状态和模块源存储桶名称的格式应如下所示：

bucket-region:bucket-name。下面是一个示例：us-west-1:doc-example-bucket
如果特定于区域的语法无法解决此问题，请确保目标节点可以访问所需区域中的 Simple Storage Service (Amazon S3)。对此进行确认：
1. 在相应的 Amazon S3 区域中查找 Amazon S3 的端点名称。有关更多信息，请参阅《Amazon Web Services 一般参考》中的 Amazon S3 Service Endpoints。
2. 登录目标节点并运行以下 ping 命令。
```
ping s3.s3-region.amazonaws.com
```
  如果 ping 命令失败，则意味着 Simple Storage Service (Amazon S3) 已关闭或防火墙/透明代理阻止访问 Simple Storage Service (Amazon S3) 区域，或节点无法访问 Internet。

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

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

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

注意

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

Details overview for resources (资源的详细概述) 部分显示有关具有不合规 DSC 资源的 Amazon 资源的信息。该部分还包括 MOF 名称、脚本执行步骤以及用于查看详细状态信息的查看输出链接（如果适用）。

查看输出链接显示详细状态的最后 4,000 个字符。Systems Manager 将异常作为第一个元素，然后将扫描详细消息，并在前面添加尽可能多的内容，直至达到 4,000 个字符的配额。该过程显示在引发异常之前输出的日志消息，这些消息是用于故障排除的最相关消息。

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

影响合规性报告的情况

如果 State Manager 关联失败，则不会报告合规性数据。更具体地说，如果 MOF 无法处理，则 Systems Manager 不会报告任何合规性项目，因为关联失败。例如，如果 Systems Manager 尝试从节点没有权限访问的 Simple Storage Service (Amazon S3) 存储桶中下载 MOF，则关联失败，并且不会报告合规性数据。

如果第二个 MOF 中的资源失败， Systems Manager 将不会报告合规性数据。例如，如果 MOF 尝试在不存在的驱动器上创建一个文件，Systems Manager 将报告合规性，因为 AWS-ApplyDSCMofs 文档可以完全处理，这意味着关联成功运行。

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

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

State Manager 演练

创建运行Ansible剧本的关联