PowerShell DSC 扩展PowerShell DSC Extension

概述Overview

适用于 Windows 的 PowerShell DSC 扩展由 Azure 发布和提供支持。The PowerShell DSC Extension for Windows is published and supported by Azure. 扩展在 Azure VM 中上传和应用 PowerShell DSC 配置。The extension uploads and applies a PowerShell DSC Configuration on an Azure VM. DSC 扩展可调用 PowerShell DSC,在 VM 上启用收到的 DSC 配置。The DSC Extension calls into PowerShell DSC to enact the received DSC configuration on the VM. 本文档详细介绍适用于 Windows 的 DSC 虚拟机扩展支持的平台、配置和部署选项。This document details the supported platforms, configurations, and deployment options for the DSC virtual machine extension for Windows.

必备条件Prerequisites

操作系统Operating system

DSC 扩展支持以下 OS:The DSC Extension supports the following OS's

Windows Server 2019、Windows Server 2016、Windows Server 2012R2、Windows Server 2012、Windows Server 2008 R2 SP1、Windows Client 10Windows Server 2019, Windows Server 2016, Windows Server 2012R2, Windows Server 2012, Windows Server 2008 R2 SP1, Windows Client 10

Internet 连接Internet connectivity

适用于 Windows 的 DSC 扩展要求目标虚拟机能够与 Azure 以及配置文件包(.zip 文件)的位置(如果它存储在 Azure 之外的位置)通信。The DSC extension for Windows requires that the target virtual machine is able to communicate with Azure and the location of the configuration package (.zip file) if it is stored in a location outside of Azure.

扩展架构Extension schema

以下 JSON 显示用于 Azure 资源管理器模板中 DSC 扩展的设置部分的架构。The following JSON shows the schema for the settings portion of the DSC Extension in an Azure Resource Manager template.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "Microsoft.Powershell.DSC",
  "apiVersion": "2018-10-01",
  "location": "<location>",
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "wmfVersion": "latest",
        "configuration": {
            "url": "http://validURLToConfigLocation",
            "script": "ConfigurationScript.ps1",
            "function": "ConfigurationFunction"
        },
        "configurationArguments": {
            "argument1": "Value1",
            "argument2": "Value2"
        },
        "configurationData": {
            "url": "https://foo.psd1"
        },
        "privacy": {
            "dataCollection": "enable"
        },
        "advancedOptions": {
            "forcePullAndApply": false,
            "downloadMappings": {
                "specificDependencyKey": "https://myCustomDependencyLocation"
            }
        } 
    },
    "protectedSettings": {
        "configurationArguments": {
            "parameterOfTypePSCredential1": {
                "userName": "UsernameValue1",
                "password": "PasswordValue1"
            },
            "parameterOfTypePSCredential2": {
                "userName": "UsernameValue2",
                "password": "PasswordValue2"
            }
        },
        "configurationUrlSasToken": "?g!bber1sht0k3n",
        "configurationDataUrlSasToken": "?dataAcC355T0k3N"
    }
  }
}

属性值Property values

名称Name 值/示例Value / Example 数据类型Data Type
apiVersionapiVersion 2018-10-012018-10-01 datedate
发布者publisher Microsoft.Powershell.DSCMicrosoft.Powershell.DSC 字符串string
typetype DSCDSC 字符串string
typeHandlerVersiontypeHandlerVersion 2.772.77 intint

设置属性值Settings Property values

名称Name 数据类型Data Type 说明Description
settings.wmfVersionsettings.wmfVersion 字符串string 指定应在 VM 上安装的 Windows Management Framework 版本。Specifies the version of the Windows Management Framework that should be installed on your VM. 将此属性设置为“latest”可安装最新版本的 WMF。Setting this property to 'latest' will install the most updated version of WMF. 目前,此属性的可能值只有“4.0”、“5.0”和“latest”。The only current possible values for this property are '4.0', '5.0', and 'latest'. 这些可能值将来可能会更新。These possible values are subject to updates. 默认值为“latest”。The default value is 'latest'.
settings.configuration.urlsettings.configuration.url 字符串string 指定要从中下载 DSC 配置 zip 文件的 URL 位置。Specifies the URL location from which to download your DSC configuration zip file. 如果提供的 URL 需要 SAS 令牌才能访问,必须将 protectedSettings.configurationUrlSasToken 属性设置为 SAS 令牌的值。If the URL provided requires a SAS token for access, you will need to set the protectedSettings.configurationUrlSasToken property to the value of your SAS token. 如果已定义 settings.configuration.script 和/或 settings.configuration.function,则需要此属性。This property is required if settings.configuration.script and/or settings.configuration.function are defined.
settings.configuration.scriptsettings.configuration.script 字符串string 指定包含 DSC 配置定义的脚本的文件名。Specifies the file name of the script that contains the definition of your DSC configuration. 此脚本必须位于从 configuration.url 属性所指定的 URL 下载的 zip 文件的根文件夹中。This script must be in the root folder of the zip file downloaded from the URL specified by the configuration.url property. 如果已定义 settings.configuration.url 和/或 settings.configuration.script,则需要此属性。This property is required if settings.configuration.url and/or settings.configuration.script are defined.
settings.configuration.functionsettings.configuration.function 字符串string 指定 DSC 配置的名称。Specifies the name of your DSC configuration. 命名的配置必须包含在 configuration.script 定义的脚本中。The configuration named must be contained in the script defined by configuration.script. 如果已定义 settings.configuration.url 和/或 settings.configuration.function,则需要此属性。This property is required if settings.configuration.url and/or settings.configuration.function are defined.
settings.configurationArgumentssettings.configurationArguments 集合Collection 定义想要传递到 DSC 配置的任何参数。Defines any parameters you would like to pass to your DSC configuration. 不会加密此属性。This property will not be encrypted.
settings.configurationData.urlsettings.configurationData.url 字符串string 指定 URL,将从中下载配置数据 (.pds1) 文件用作 DSC 配置的输入。Specifies the URL from which to download your configuration data (.pds1) file to use as input for your DSC configuration. 如果提供的 URL 需要 SAS 令牌才能访问,必须将 protectedSettings.configurationDataUrlSasToken 属性设置为 SAS 令牌的值。If the URL provided requires a SAS token for access, you will need to set the protectedSettings.configurationDataUrlSasToken property to the value of your SAS token.
settings.privacy.dataEnabledsettings.privacy.dataEnabled 字符串string 启用或禁用遥测数据收集。Enables or disables telemetry collection. 此属性的可能值只有“Enable”、“Disable”、" 或 $null。The only possible values for this property are 'Enable', 'Disable', ", or $null. 将此属性留空,否则 null 将启用遥测Leaving this property blank or null will enable telemetry
settings.advancedOptions.forcePullAndApplysettings.advancedOptions.forcePullAndApply BoolBool 此设置旨在增强使用扩展将节点注册到 Azure Automation DSC 的体验。This setting is designed to enhance the experience of working with the extension to register nodes with Azure Automation DSC. 如果值为 $true,则扩展会等待从服务拉取的配置完成第一次运行,然后返回成功/失败。If the value is $true, the extension will wait for the first run of the configuration pulled from the service before returning success/failure. 如果值设置为 $false,则扩展返回的状态仅指节点是否已成功注册到 Azure Automation State Configuration,而在注册过程中不会运行节点配置。If the value is set to $false, the status returned by the extension will only refer to whether the node was registered with Azure Automation State Configuration successfully and the node configuration will not be run during the registration.
settings.advancedOptions.downloadMappingssettings.advancedOptions.downloadMappings 集合Collection 定义用于下载依赖项(如 WMF 和 .NET)的备用位置Defines alternate locations to download dependencies such as WMF and .NET

受保护设置属性值Protected Settings Property values

名称Name 数据类型Data Type 说明Description
protectedSettings.configurationArgumentsprotectedSettings.configurationArguments 字符串string 定义想要传递到 DSC 配置的任何参数。Defines any parameters you would like to pass to your DSC configuration. 将加密此属性。This property will be encrypted.
protectedSettings.configurationUrlSasTokenprotectedSettings.configurationUrlSasToken 字符串string 指定用于访问 configuration.url 所定义的 URL 的 SAS 令牌。Specifies the SAS token to access the URL defined by configuration.url. 将加密此属性。This property will be encrypted.
protectedSettings.configurationDataUrlSasTokenprotectedSettings.configurationDataUrlSasToken 字符串string 指定用于访问 configurationData.url 所定义的 URL 的 SAS 令牌。Specifies the SAS token to access the URL defined by configurationData.url. 将加密此属性。This property will be encrypted.

模板部署Template deployment

可使用 Azure 资源管理器模板部署 Azure VM 扩展。Azure VM extensions can be deployed with Azure Resource Manager templates. 部署需要部署后配置的一个或多个虚拟机时,模板是理想选择。Templates are ideal when deploying one or more virtual machines that require post deployment configuration. 包含 Windows 的 DSC 扩展的示例资源管理器模板可以在 Azure 快速入门库中找到。A sample Resource Manager template that includes the DSC extension for Windows can be found on the Azure Quick Start Gallery.

故障排除和支持Troubleshoot and support

故障排除Troubleshoot

有关扩展部署状态的数据可以从 Azure 门户和使用 Azure CLI 进行检索。Data about the state of extension deployments can be retrieved from the Azure portal, and by using the Azure CLI. 若要查看给定 VM 的扩展部署状态,请使用 Azure CLI 运行以下命令。To see the deployment state of extensions for a given VM, run the following command using the Azure CLI.

az vm extension list --resource-group myResourceGroup --vm-name myVM -o table

下载扩展包并将其部署到 Azure VM 上的此位置Extension package is downloaded and deployed to this location on the Azure VM

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}

扩展状态文件包含子状态和状态成功/错误代码以及每个扩展运行的详细错误和说明。Extension status file contains the sub status and status success/error codes along with the detailed error and description for each extension run.

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}\Status\{0}.Status  -> {0} being the sequence number

扩展输出日志会记录到以下目录:Extension output logs are logged to the following directory:

C:\WindowsAzure\Logs\Plugins\{Extension_Name}\{Extension_Version}

错误代码及其含义Error codes and their meanings

错误代码Error Code 含义Meaning 可能的操作Possible Action
10001000 常规错误Generic error 此错误消息由扩展日志中的特定异常提供The message for this error is provided by the specific exception in extension logs
5252 扩展安装错误Extension Install Error 此错误消息由特定异常提供The message for this error is provided by the specific exception
10021002 WMF 安装错误Wmf Install Error 安装 WMF 时出错。Error while installing WMF.
10041004 Zip 包无效Invalid Zip Package zip 无效; 解压缩 zip 时出错Invalid zip ; Error unpacking the zip
11001100 参数错误Argument Error 指示用户提供的输入中的问题。Indicates a problem in the input provided by the user. 此错误消息由特定异常提供The message for the error is provided by the specific exception

支持Support

如果对本文中的任何观点存在疑问,可以联系 Azure 支持上的 Azure 专家。If you need more help at any point in this article, you can contact the Azure experts on the Azure support. 或者,你也可以提出 Azure 支持事件。Alternatively, you can file an Azure support incident. 请转到 Azure 支持站点提交请求。Go to the Azure support site and submit your request. 有关使用 Azure 支持的信息,请阅读 Azure 支持常见问题For information about using Azure Support, read the Azure support FAQ.