AWS Systems Manager
用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

创建运行 MOF 文件的关联

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

状态管理器 在每个关联运行期间记录并报告每个 MOF 文件执行的状态。状态管理器 还将每个 MOF 文件执行的输出报告为合规性事件,可在 AWS 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 文件、合规性报告或状态报告,则 SSM 代理使用的 IAM 角色必须拥有存储桶的 GetObjectListBucket 权限。如果您不提供这些权限,系统将返回拒绝访问 错误。另外,请注意以下有关在 Amazon S3 中存储构件的重要信息。

  • 如果存储桶位于不同的 AWS 账户中,则必须创建一个存储桶资源策略,向该账户(或 IAM 角色)授予 GetObjectListBucket 权限。

  • 如果要使用自定义 DSC 资源,则可从 Amazon S3 存储桶中下载这些资源。您也可以从 PowerShell 库中自动安装这些资源。

  • 如果使用 Amazon S3 作为模块源,则需要以 Zip 文件形式上传该模块,采用以下区分大小写的格式:ModuleName_ModuleVersion.zip。例如:MyModule_1.0.0.zip。

  • 所有文件都必须位于存储桶根中。不支持文件夹结构。

解析 MOF 文件中的凭证

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

要在配置中使用 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' }

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

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

在 MOF 文件中使用令牌

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

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

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

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

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

您还可以将多个标签组合到单个属性中,例如:

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

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

  • tag:Amazon EC2 或托管实例标签

  • tagb64:与标签相同,但系统使用 base64 对值解码。这样您可以在标签值中使用特殊字符。

  • env:解析环境变量。

  • ssm:参数仓库值。仅支持 String 和 SecureString 类型。

  • tagssm:与标签相同,但如果未在实例上设置标签,系统将尝试从同名的 SSM 参数中解析值。如果需要“默认全局值”,但希望能够在单个实例(例如,一站式部署)中覆盖该值时,此令牌很有用。

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

先决条件

在创建用于运行 MOF 文件的关联之前,请验证托管实例是否已安装以下必备组件:

创建运行 MOF 文件的关联

创建运行 MOF 文件的关联

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

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

  3. Name (名称) 字段中指定名称。您可以自由选择,但我们建议您这样做。名称可以帮助了解您在创建关联时为关联考虑的用途。名称不得包含空格。

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

  5. Parameters (参数) 部分中,指定您选择的必需和可选输入参数。

    1. Mofs To Apply (要应用的 Mof):指定要在此关联运行时运行的一个或多个 MOF 文件。使用逗号分隔 MOF 文件的列表。您可以指定以下用于查找 MOF 文件的选项。

      • Amazon S3 存储桶名称。存储桶名称必须使用小写字母。可使用以下格式指定此信息:

        s3:bucket_name:MOF_file_name.mof

        如果要指定 AWS 区域,请使用以下格式:

        s3:bucket_Region:bucket_name:MOF_file_name.mof
      • 安全的网站。可使用以下格式指定此信息:

        https://domain_name/MOF_file_name.mof

        示例如下:

        https://AWS.Amazon.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. Mof Operation Mode (Mof 操作模式):在运行 AWS-ApplyDSCMofs 关联时选择 状态管理器 行为:

      • Apply (应用):更正不合规的实例配置。

      • ReportOnly:不更正实例配置,但记录所有合规性数据并报告不合规实例。

    5. Status Bucket Name (状态存储桶名称):(可选)输入要将 MOF 执行状态信息写入到的 Amazon S3 存储桶的名称。这些状态报告是实例的最新合规性运行的单例摘要。这意味着,下次关联运行 MOF 文件时,将覆盖该报告。

      注意

      您可以用存储桶所在的区域作为存储桶名称的前缀。下面是一个示例:us-west-2:MyMOFBucket。如果对不包括 us-east-1 在内的特定区域中的 Amazon S3 终端节点使用代理,则必须用区域作为存储桶名称的前缀。如果存储桶名称不含前缀,它会使用 us-east-1 终端节点自动发现存储桶区域。

    6. Module Source Bucket Name (模块源存储桶名称):(可选)输入包含 PowerShell 模块文件的 Amazon S3 存储桶的名称。如果指定 None (无),则必须对下一个选项 Allow PS Gallery Module Source (允许 PS 库模块源) 选择 True

      注意

      您可以用存储桶所在的区域作为存储桶名称的前缀。下面是一个示例:us-west-2:MyMOFBucket。如果对不包括 us-east-1 在内的特定区域中的 Amazon S3 终端节点使用代理,则必须用区域作为存储桶名称的前缀。如果存储桶名称不含前缀,它会使用 us-east-1 终端节点自动发现存储桶区域。

    7. Allow PS Gallery Module Source (允许 PS 库模块源):(可选)选择 Truehttps://www.powershellgallery.com/ 下载 PowerShell 模块。如果选择 False,则必须为上一个选项 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 Console User Guide 中的如何为 S3 存储桶创建生命周期策略?

    12. Enable Debug Logging (启用调试日志记录):(可选)如果需要排除 MOF 故障,建议启用调试日志记录。我们还建议您在正常使用时禁用此选项。

      重要

      启用后,调试日志记录会向 Amazon S3 存储桶中写入比标准关联执行日志记录更多的数据。这可能会导致性能变慢,并且 Amazon S3 的存储费用可能会变高。要缓解存储大小问题,建议在 Amazon S3 存储桶中启用生命周期策略。有关更多信息,请参阅 Amazon Simple Storage Service Console User Guide 中的如何为 S3 存储桶创建生命周期策略?

    13. Compliance Type (合规性类型):(可选)指定要在报告合规性信息时使用的合规性类型。默认的合规性类型为 Custom:DSC (自定义:DSC)。如果创建多个运行 MOF 文件的关联,请确保为每个关联指定不同的合规性类型。否则,使用 Custom:DSC (自定义:DSC) 的每个其他关联都将覆盖现有的合规性数据。

    14. Pre Reboot Script (重启前脚本):(可选)指定在配置指示需要重启时要运行的脚本。该脚本将在重启之前运行。该脚本必须为单行。如果需要添加额外的行,请使用分号分隔行。

  6. Targets (目标) 部分中,选择 Specifying tags (指定标签)Manually Selecting Instance (手动选择实例)。如果选择使用标签将资源设置为目标,请在提供的字段中输入标签键和标签值。有关使用目标的更多信息,请参阅将目标和速率控制与 状态管理器 关联结合使用

  7. Specify schedule (指定计划) 部分中,选择 On Schedule (按计划)No schedule (无计划)。如果选择 On Schedule (按计划),则可使用提供的按钮为关联创建 cron 或 rate 计划。

  8. Advanced options (高级选项) 部分中:

    • Compliance severity (合规性严重级别) 中,选择关联的严重级别。合规性报告将指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息,请参阅 关于 状态管理器 关联合规性

  9. Rate control (速率控制) 部分,配置用于跨托管实例队列运行 状态管理器 关联的选项。有关这些选项的详细信息,请参阅 将目标和速率控制与 状态管理器 关联结合使用

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

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

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

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

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

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

  10. Output options (输出选项) 部分中,如果要将创建关联的命令的输出写入到 Amazon S3 存储桶,请选择 Enable writing output to S3 (启用将输出写入 S3)

  11. 选择创建关联

状态管理器 在指定的实例或目标中创建并立即运行关联。在初始执行后,关联根据定义的计划和以下规则按间隔运行:

  • 关联仅在间隔开始时处于在线状态的实例上运行。将跳过离线实例。

  • 状态管理器 在间隔期间会尝试在所有已配置的实例上运行关联。

  • 如果在间隔期间未运行某一关联(例如,由于并发值限制了一次可以处理关联的实例数),状态管理器 将尝试在下一个间隔期间运行该关联。

  • 状态管理器 会记录所有已跳过间隔的历史记录。可在 Execution History (执行历史记录) 选项卡上查看历史记录。

注意

AWS-ApplyDSCMofs 是 Systems Manager 命令文档。这意味着,您也可以使用 Run Command 运行此文档。有关更多信息,请参阅使用 Systems ManagerRun Command 运行命令

故障排除

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

启用增强型日志记录

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

  • 验证关联是否配置为将命令输出写入到 Amazon S3 或 Amazon CloudWatch Logs。

  • Enable Verbose Logging (启用详细日志记录) 参数设置为 True。

  • Enable Debug Logging (启用调试日志记录) 参数设置为 True。

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

常见问题

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

我的 MOF 未应用

如果 状态管理器 未能将关联应用到您的实例,请首先查看 Stderr 输出文件。此文件可以帮助您了解问题的根本原因。另外,请确认:

  • 此实例对与 MOF 相关的所有 Amazon S3 存储桶具有所需访问权限。具体来说:

    • s3:GetObject permissions (s3:GetObject 权限):这是私有 Amazon S3 存储桶中的 MOF 文件和 Amazon S3 存储桶中的自定义模块必需的权限。

    • s3:PutObject permission (s3:PutObject 权限):在将合规性报告和合规性状态写入 Amazon S3 存储桶时需要此权限。

  • 如果使用标签,则需确保该实例具有所需的 IAM 策略。使用标签需要实例 IAM 角色的策略允许 ec2:DescribeInstancesssm:ListTagsForResource 操作。

  • 确保该实例已分配预期的标签或 SSM 参数。

  • 请确保标签或 SSM 参数不包含拼写错误。

  • 尝试在实例本地应用 MOF,以确保 MOF 文件本身没有问题。

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

如果 AWS-ApplyDSCMofs 文档成功运行,则 Systems Manager 执行状态将显示 Success (成功)。此状态并不反映实例针对 MOF 文件中的配置要求的合规性状态。要查看实例的合规性状态,请查看合规性报告。您可以查看 Amazon S3 报告存储桶中的 JSON 报告。这适用于 Run Command 和 状态管理器 执行。此外,对于 状态管理器,您可以在 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:my-bucket:my-mof.mof

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

    bucket-region:bucket-name。下面是一个示例:us-west-1:my-bucket

  • 如果特定于区域的语法无法解决此问题,请确保目标实例可以访问所需区域中的 Amazon S3。对此进行确认:

    1. 在所需区域中查找用于 Amazon S3 的终端节点名称。

    2. 登录目标实例并运行以下 ping 命令:

      ping s3.s3-region.amazonaws.com

      如果 ping 命令失败,则意味着 Amazon S3 已关闭或防火墙/透明代理阻止访问 Amazon S3 区域,或实例无法访问 Internet。