Azure Desired State Configuration 扩展处理程序简介Introduction to the Azure Desired State Configuration extension handler

Azure VM 代理和关联的扩展是 Azure 基础结构服务的一部分。The Azure VM Agent and associated extensions are part of Azure infrastructure services. VM 扩展是软件组件,可以扩展 VM 功能并简化各种 VM 管理操作。VM extensions are software components that extend VM functionality and simplify various VM management operations.

Azure Desired State Configuration (DSC) 扩展的主要用例是让 VM 启动到 Azure Automation State Configuration (DSC) 服务The primary use case for the Azure Desired State Configuration (DSC) extension is to bootstrap a VM to the Azure Automation State Configuration (DSC) service. 该服务带来的好处包括:持续管理 VM 的配置,并与其他操作工具(例如 Azure 监视)集成。The service provides benefits that include ongoing management of the VM configuration and integration with other operational tools, such as Azure Monitoring. 使用扩展将 VM 注册到该服务可以提供一个甚至可跨 Azure 订阅工作的灵活解决方案。Using the extension to register VM's to the service provides a flexible solution that even works across Azure subscriptions.

可以独立于 Automation DSC 服务使用 DSC 扩展。You can use the DSC extension independently of the Automation DSC service. 但是,这只会将配置推送到 VM。However, this will only push a configuration to the VM. 系统不会提供持续的报告,只能在 VM 本地执行此类操作。No ongoing reporting is available, other than locally in the VM.

本文提供有关两种方案的信息:使用 DSC 扩展进行自动化加入,以及使用 DSC 扩展作为工具,通过 Azure SDK 将配置分配给 VM。This article provides information about both scenarios: using the DSC extension for Automation onboarding, and using the DSC extension as a tool for assigning configurations to VMs by using the Azure SDK.

先决条件Prerequisites

  • 本地计算机 :若要与 Azure VM 扩展交互,必须使用 Azure 门户或 Azure PowerShell SDK。Local machine : To interact with the Azure VM extension, you must use either the Azure portal or the Azure PowerShell SDK.
  • 来宾代理 :使用 DSC 配置进行配置的 Azure VM 必须采用支持 Windows Management Framework (WMF) 4.0 或更高版本的 OS。Guest Agent : The Azure VM that's configured by the DSC configuration must be an OS that supports Windows Management Framework (WMF) 4.0 or later. 有关支持的 OS 版本的完整列表,请参阅 DSC 扩展版本历史记录For the full list of supported OS versions, see the DSC extension version history.

术语和概念Terms and concepts

本指南假设读者熟悉以下概念:This guide assumes familiarity with the following concepts:

  • 配置 :DSC 配置文档。Configuration : A DSC configuration document.
  • 节点 :DSC 配置的目标。Node : A target for a DSC configuration. 在本文档中,“节点”一律指 Azure VM。In this document, node always refers to an Azure VM.
  • 配置数据 :包含配置的环境数据的 psd1 文件。Configuration data : A .psd1 file that has environmental data for a configuration.

体系结构Architecture

Azure DSC 扩展使用 Azure VM 代理框架来传送、启用和报告 Azure VM 上运行的 DSC 配置。The Azure DSC extension uses the Azure VM Agent framework to deliver, enact, and report on DSC configurations running on Azure VMs. DSC 扩展接受配置文档和一组参数。The DSC extension accepts a configuration document and a set of parameters. 如果未提供任何文件,默认配置脚本会嵌入到扩展中。If no file is provided, a default configuration script is embedded with the extension. 默认配置脚本仅用于在本地配置管理器中设置元数据。The default configuration script is used only to set metadata in Local Configuration Manager.

首次调用扩展时,该扩展使用以下逻辑安装某个版本的 WMF:When the extension is called for the first time, it installs a version of WMF by using the following logic:

  • 如果 Azure VM OS 是 Windows Server 2016,则不执行任何操作。If the Azure VM OS is Windows Server 2016, no action is taken. Windows Server 2016 上已安装最新版本的 PowerShell。Windows Server 2016 already has the latest version of PowerShell installed.
  • 如果已指定 wmfVersion 属性,除非该 WMF 版本与 VM 的 OS 不兼容,否则将安装该版本。If the wmfVersion property is specified, that version of WMF is installed, unless that version is incompatible with the VM's OS.
  • 如果未指定 wmfVersion 属性,则安装 WMF 的最新适用版本。If no wmfVersion property is specified, the latest applicable version of WMF is installed.

安装 WMF 需要重启。Installing WMF requires a restart. 重启后,扩展将下载 modulesUrl 属性中指定的 .zip 文件(若已提供)。After restarting, the extension downloads the .zip file that's specified in the modulesUrl property, if provided. 如果此位置在 Azure Blob 存储中,则可以在 sasToken 属性中指定 SAS 令牌来访问该文件。If this location is in Azure Blob storage, you can specify an SAS token in the sasToken property to access the file. 下载并解压缩 .zip 之后,将运行 configurationFunction 中定义的配置函数以生成 .mof( 托管对象格式)文件。After the .zip is downloaded and unpacked, the configuration function defined in configurationFunction runs to generate an .mof(Managed Object Format) file. 扩展然后通过使用生成的 .mof 文件来运行 Start-DscConfiguration -ForceThe extension then runs Start-DscConfiguration -Force by using the generated .mof file. 扩展将捕获输出并将其写入 Azure 状态通道。The extension captures output and writes it to the Azure status channel.

默认配置脚本Default configuration script

Azure DSC 扩展包括一个默认配置脚本,该脚本计划在对 Azure Automation DSC 服务载入 VM 时使用。The Azure DSC extension includes a default configuration script that's intended to be used when you onboard a VM to the Azure Automation DSC service. 脚本参数符合本地配置管理器的可配置属性。The script parameters are aligned with the configurable properties of Local Configuration Manager. 有关脚本参数,请参阅 Desired State Configuration 扩展与 Azure 资源管理器模板中的默认配置脚本For script parameters, see Default configuration script in Desired State Configuration extension with Azure Resource Manager templates. 有关完整脚本,请参阅 GitHub 中的 Azure 快速入门模板For the full script, see the Azure quickstart template in GitHub.

有关注册到 Azure Automation State Configuration (DSC) 服务的信息Information for registering with Azure Automation State Configuration (DSC) service

使用 DSC 扩展将节点注册到 State Configuration 服务时,需要提供三个值。When using the DSC Extension to register a node with the State Configuration service, three values will need to be provided.

  • RegistrationUrl - Azure 自动化帐户的 https 地址RegistrationUrl - the https address of the Azure Automation account
  • RegistrationKey - 用于将节点注册到服务的共享机密RegistrationKey - a shared secret used to register nodes with the service
  • NodeConfigurationName - 从服务中提取的,用于配置服务器角色的节点配置 (MOF) 的名称NodeConfigurationName - the name of the Node Configuration (MOF) to pull from the service to configure the server role

可以在 Azure 门户中或者使用 PowerShell 查看此信息。This information can be seen in the Azure portal or you can use PowerShell.

(Get-AzAutomationRegistrationInfo -ResourceGroupName <resourcegroupname> -AutomationAccountName <accountname>).Endpoint
(Get-AzAutomationRegistrationInfo -ResourceGroupName <resourcegroupname> -AutomationAccountName <accountname>).PrimaryKey

对于节点配置名称,请确保在 Azure State Configuration 中存在节点配置。For the Node Configuration name, make sure the node configuration exists in Azure State Configuration. 如果不存在,扩展部署将返回失败。If it does not, the extension deployment will return a failure. 另外,请确保使用“节点配置”的名称而不是“配置”的名称。Also make sure you are using the name of the Node Configuration and not the Configuration. 配置在用于编译节点配置(MOF 文件)的脚本中定义。A Configuration is defined in a script that is used to compile the Node Configuration (MOF file). 该名称始终为 Configuration 后接句点 . 以及 localhost 或特定计算机名。The name will always be the Configuration followed by a period . and either localhost or a specific computer name.

资源管理器模板中的 DSC 扩展DSC extension in Resource Manager templates

在大多数情况下,应该通过 Azure 资源管理器部署模板来使用 DSC 扩展。In most scenarios, Resource Manager deployment templates are the expected way to work with the DSC extension. 有关详细信息以及如何在资源管理器部署模板中包含 DSC 扩展的示例,请参阅 Desired State Configuration 扩展与 Azure 资源管理器模板For more information and for examples of how to include the DSC extension in Resource Manager deployment templates, see Desired State Configuration extension with Azure Resource Manager templates.

DSC 扩展 PowerShell cmdletDSC extension PowerShell cmdlets

用于管理 DSC 扩展的 PowerShell cmdlet 最适合用于交互式故障排除和信息收集方案。The PowerShell cmdlets that are used to manage the DSC extension are best used in interactive troubleshooting and information-gathering scenarios. 可以使用 cmdlet 来打包、发布和监视 DSC 扩展部署。You can use the cmdlets to package, publish, and monitor DSC extension deployments. DSC 扩展的 cmdlet 尚未更新,无法使用默认配置脚本Cmdlets for the DSC extension aren't yet updated to work with the default configuration script.

Publish-AzVMDscConfiguration cmdlet 检索配置文件,扫描其中是否有依赖的 DSC 资源,然后创建一个 .zip 文件。The Publish-AzVMDscConfiguration cmdlet takes in a configuration file, scans it for dependent DSC resources, and then creates a .zip file. 该 .zip 文件包含启用配置所需的配置和 DSC 资源。The .zip file contains the configuration and DSC resources that are needed to enact the configuration. 该 cmdlet 还可以使用 -OutputArchivePath 参数在本地创建包。The cmdlet can also create the package locally by using the -OutputArchivePath parameter. 否则,该 cmdlet 会将 .zip 文件发布到 Blob 存储,然后使用 SAS 令牌保护该文件。Otherwise, the cmdlet publishes the .zip file to blob storage, and then secures it with an SAS token.

该 cmdlet 创建的 .ps1 配置脚本位于存档文件夹根目录中的 .zip 文件内。The .ps1 configuration script that the cmdlet creates is in the .zip file at the root of the archive folder. 模块文件夹位于资源的存档文件夹中。The module folder is placed in the archive folder in resources.

Set-AzVMDscExtension cmdlet 将 PowerShell DSC 扩展所需的设置注入 VM 配置对象。The Set-AzVMDscExtension cmdlet injects the settings that the PowerShell DSC extension requires into a VM configuration object.

Get-AzVMDscExtension cmdlet 检索特定 VM 的 DSC 扩展状态。The Get-AzVMDscExtension cmdlet retrieves the DSC extension status of a specific VM.

Get-AzVMDscExtensionStatus cmdlet 检索由 DSC 扩展处理程序启用的 DSC 配置的状态。The Get-AzVMDscExtensionStatus cmdlet retrieves the status of the DSC configuration that's enacted by the DSC extension handler. 可在一个或一组 VM 上执行此操作。This action can be performed on a single VM or on a group of VMs.

Remove-AzVMDscExtension cmdlet 从特定的 VM 中删除扩展处理程序。The Remove-AzVMDscExtension cmdlet removes the extension handler from a specific VM. 此 cmdlet 不会删除配置、卸载 WMF 或更改 VM 上已应用的设置。This cmdlet does not remove the configuration, uninstall WMF, or change the applied settings on the VM. 而只删除扩展处理程序。It only removes the extension handler.

有关资源管理器 DSC 扩展 cmdlet 的重要信息:Important information about Resource Manager DSC extension cmdlets:

  • Azure Resource Manager cmdlet 是同步的。Azure Resource Manager cmdlets are synchronous.
  • ResourceGroupNameVMNameArchiveStorageAccountNameVersionLocation 都是必需的参数。The ResourceGroupName , VMName , ArchiveStorageAccountName , Version , and Location parameters are all required.
  • ArchiveResourceGroupName 是可选参数。ArchiveResourceGroupName is an optional parameter. 如果用户的存储帐户所属的资源组与创建 VM 的资源组不同,用户可以指定此参数。You can specify this parameter when your storage account belongs to a different resource group than the one where the VM is created.
  • 使用 AutoUpdate 开关可在有最新版本可用时将扩展处理程序自动更新为最新版本。Use the AutoUpdate switch to automatically update the extension handler to the latest version when it's available. 当发布了新版本的 WMF 时,此参数可能会导致 VM 重启。This parameter has the potential to cause restarts on the VM when a new version of WMF is released.

cmdlet 入门Get started with cmdlets

Azure DSC 扩展可在部署过程中使用 DSC 配置文档直接配置 Azure VM。The Azure DSC extension can use DSC configuration documents to directly configure Azure VMs during deployment. 此步骤不会将节点注册到自动化。This step doesn't register the node to Automation. 不会集中管理节点。The node is not centrally managed.

下面是一个简单的配置示例。The following example shows a simple example of a configuration. 在本地将配置保存为 iisInstall.ps1。Save the configuration locally as iisInstall.ps1.

configuration IISInstall
{
    node "localhost"
    {
        WindowsFeature IIS
        {
            Ensure = "Present"
            Name = "Web-Server"
        }
    }
}

以下命令将 iisInstall.ps1 脚本放在指定的 VM 上。The following commands place the iisInstall.ps1 script on the specified VM. 这些命令还会执行配置,然后报告状态。The commands also execute the configuration, and then report back on status.

$resourceGroup = 'dscVmDemo'
$vmName = 'myVM'
$storageName = 'demostorage'
#Publish the configuration script to user storage
Publish-AzVMDscConfiguration -ConfigurationPath .\iisInstall.ps1 -ResourceGroupName $resourceGroup -StorageAccountName $storageName -force
#Set the VM to run the DSC configuration
Set-AzVMDscExtension -Version '2.76' -ResourceGroupName $resourceGroup -VMName $vmName -ArchiveStorageAccountName $storageName -ArchiveBlobName 'iisInstall.ps1.zip' -AutoUpdate -ConfigurationName 'IISInstall'

Azure CLI 部署Azure CLI deployment

可以使用 Azure CLI 将 DSC 扩展部署到现有的虚拟机。The Azure CLI can be used to deploy the DSC extension to an existing virtual machine.

对于运行 Windows 的虚拟机:For a virtual machine running Windows:

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name Microsoft.Powershell.DSC \
  --publisher Microsoft.Powershell \
  --version 2.77 --protected-settings '{}' \
  --settings '{}'

对于运行 Linux 的虚拟机:For a virtual machine running Linux:

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name DSCForLinux \
  --publisher Microsoft.OSTCExtensions \
  --version 2.7 --protected-settings '{}' \
  --settings '{}'

Azure 门户功能Azure portal functionality

在门户中设置 DSC:To set up DSC in the portal:

  1. 转到某个 VM。Go to a VM.
  2. 在“设置”下选择“扩展”。Under Settings , select Extensions .
  3. 在创建的新页面中,依次选择“添加”、“PowerShell Desired State Configuration” 。In the new page that's created, select + Add , and then select PowerShell Desired State Configuration .
  4. 在扩展信息页面底部,单击“创建”。Click Create at the bottom of the extension information page.

门户收集以下输入:The portal collects the following input:

  • 配置模块或脚本 :这是必填字段( 默认配置脚本的窗体尚未更新。Configuration Modules or Script : This field is mandatory (the form has not been updated for the default configuration script). 配置模块和脚本需要一个包含配置脚本的 .ps1 文件,或者需要一个 .zip 文件,其中的 .ps1 配置脚本位于根目录。Configuration modules and scripts require a .ps1 file that has a configuration script or a .zip file with a .ps1 configuration script at the root. 如果使用 .zip 文件,则必须将所有依赖资源包含在 .zip 的模块文件夹中。If you use a .zip file, all dependent resources must be included in module folders in the .zip. 可以使用 Azure PowerShell SDK 随附的 Publish-AzureVMDscConfiguration -OutputArchivePath cmdlet 来创建 .zip 文件。You can create the .zip file by using the Publish-AzureVMDscConfiguration -OutputArchivePath cmdlet that's included in the Azure PowerShell SDK. 系统会将 .zip 文件上传到用户 Blob 存储中,并使用 SAS 令牌对其进行保护。The .zip file is uploaded to your user blob storage and secured by an SAS token.

  • 配置的模块限定名称 :可以在 .ps1 文件中包含多个配置函数。Module-qualified Name of Configuration : You can include multiple configuration functions in a .ps1 file. 请输入配置 .ps1 脚本的名称,后跟 \ 和配置函数的名称。Enter the name of the configuration .ps1 script followed by \ and the name of the configuration function. 例如,如果 .ps1 脚本的名称为 configuration.ps1,而配置为 IisInstall ,请输入 configuration.ps1\IisInstallFor example, if your .ps1 script has the name configuration.ps1 and the configuration is IisInstall , enter configuration.ps1\IisInstall .

  • 配置参数 :如果配置函数采用参数,请使用 argumentName1=value1,argumentName2=value2 格式在此处输入。Configuration Arguments : If the configuration function takes arguments, enter them here in the format argumentName1=value1,argumentName2=value2 . 此格式与 PowerShell cmdlet 或资源管理器模板中接受的配置参数格式不同。This format is a different format in which configuration arguments are accepted in PowerShell cmdlets or Resource Manager templates.

  • 配置数据 PSD1 文件 :如果配置要求 .psd1 中有配置数据文件,请使用此字段来选择数据文件,然后将它上传到用户 Blob 存储。Configuration Data PSD1 File : If your configuration requires a configuration data file in .psd1, use this field to select the data file and upload it to your user blob storage. 配置数据文件在 Blob 存储中受 SAS 令牌的保护。The configuration data file is secured by an SAS token in blob storage.

  • WMF 版本 :指定应在 VM 上安装的 Windows Management Framework (WMF) 版本。WMF Version : Specifies the version of Windows Management Framework (WMF) that should be installed on your VM. 将此属性设置为“latest”可安装最新版本的 WMF。Setting this property to latest installs the most recent version of WMF. 目前,此属性的可能值只有“4.0”、“5.0”、“5.1”和“latest”。Currently, the only possible values for this property are 4.0, 5.0, 5.1, and latest. 这些可能值将来可能会更新。These possible values are subject to updates. 默认值为 latestThe default value is latest .

  • 数据收集 :确定扩展是否将收集遥测数据。Data Collection : Determines if the extension will collect telemetry. 有关详细信息,请参阅 Azure DSC 扩展数据集合For more information, see Azure DSC extension data collection.

  • 版本 :指定要安装的 DSC 扩展的版本。Version : Specifies the version of the DSC extension to install. 有关版本信息,请参阅 DSC 扩展版本历史记录For information about versions, see DSC extension version history.

  • 自动升级次要版本 :此字段映射到 cmdlet 中的 AutoUpdate 开关,使扩展能够在安装过程中自动更新到最新版本。Auto Upgrade Minor Version : This field maps to the AutoUpdate switch in the cmdlets and enables the extension to automatically update to the latest version during installation. “是”将指示扩展处理程序使用最新可用版本,“否”将强制安装指定的版本。Yes will instruct the extension handler to use the latest available version and No will force the Version specified to be installed. 既不选择“是”也不选择“否”相当于选择“否”。Selecting neither Yes nor No is the same as selecting No .

日志Logs

扩展的日志存储在以下位置:C:\WindowsAzure\Logs\Plugins\Microsoft.Powershell.DSC\<version number>Logs for the extension are stored in the following location: C:\WindowsAzure\Logs\Plugins\Microsoft.Powershell.DSC\<version number>

后续步骤Next steps