你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Desired State Configuration 扩展与 Azure 资源管理器模板

项目
12/19/2024

注意

在启用 DSC 扩展之前，我们希望你了解 DSC 的更新版本目前已正式发布，并由名为机器配置的功能进行管理。机器配置功能包含 Desired State Configuration (DSC) 扩展处理程序的功能以及客户反馈中最常请求的功能。机器配置还包括通过已启用 Arc 的服务器提供的混合计算机支持。

本文介绍 Desired State Configuration (DSC) 扩展处理程序的 Azure 资源管理器模板。

注意

你可能会遇到略有不同的架构示例。 2016 年 10 月发行版中发生了架构更改。有关详细信息，请参阅从以前的格式更新。

VM 的 Bicep 示例

DSC 扩展继承默认扩展属性。有关详细信息，请参阅 VirtualMachineExtension 类。

@description('URI of the configuration package')
param configUri string

@description('first configuration parameter')
param arg1 string

@description('second configuration parameter')
@secure()
param arg2 string

var configName = split(split(configUri, '/')[4], '.')[0]

resource vm 'Microsoft.Compute/virtualMachines@2023-09-01' existing = {
  name: srvName
}

resource configuration_dscext 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  name: 'configurationname_dscext'
  parent: vm
  location: location
  properties: {
    publisher: 'Microsoft.Powershell'
    type: 'DSC'
    typeHandlerVersion: '2.77'
    autoUpgradeMinorVersion: true
    settings: {
      wmfVersion: 'latest'
      configuration: {
        url: configUri
        script: 'configurationname_dscext.ps1'
        function: 'configurationname_dscext'
      }
      configurationArguments: {
        arg1: arg1
      }
      advancedOptions: {
        rebootNodeIfNeeded: true
      }
    }
    protectedSettings: {
      configurationArguements: {
        arg2: arg2
      }
    }
  }
}

Windows 虚拟机规模集的 Bicep 示例

虚拟机规模集节点具有一个包含 extensionProfile 特性的部分。在“扩展”下，添加 DSC 扩展的详细信息。

有关创作部署虚拟机规模集扩展的模板的最新详细信息，请参阅文档 Microsoft.Compute virtualMachineScaleSets

DSC 扩展继承默认扩展属性。有关详细信息，请参阅 VirtualMachineScaleSetExtension 类。

Settings 与 protectedSettings

所有设置保存在 VM 上的 settings 文本文件中。 settings 下面列出的属性是公共属性。公共属性未在 settings 文本文件中加密。 protectedSettings 下面列出的属性已使用证书加密，因此不会在 VM 上的 settings 文件中以明文显示。

如果配置需要凭据，可将凭据包含在 protectedSettings 中：

"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
               "userName": "UsernameValue1",
               "password": "PasswordValue1"
        }
    }
}

在 Azure 存储中使用配置脚本的示例

以下示例摘自 DSC 扩展处理程序概述。此示例使用 Resource Manager 模板而不是cmdlet 来部署该扩展。保存 IisInstall.ps1 配置，将它放在 .zip 文件（例如 iisinstall.zip）中，并将该文件上传到可访问的 URL 中。此示例使用 Azure Blob 存储，但可以从任意位置下载 .zip 文件。

在资源管理器模板中，以下代码指示 VM 下载正确的文件并运行适当的 PowerShell 函数：

"settings": {
    "configuration": {
        "url": "https://demo.blob.core.windows.net/iisinstall.zip",
        "script": "IisInstall.ps1",
        "function": "IISInstall"
    }
},
"protectedSettings": {
    "configurationUrlSasToken": "odLPL/U1p9lvcnp..."
}

从以前的格式更新

以前扩展格式中的所有设置（包含公共属性 ModulesUrl、ModuleSource、ModuleVersion、ConfigurationFunction、SasToken 或 Properties）会自动调整为当前扩展格式。它们按以前的相同方式运行。

以下架构显示了以前的 settings 架构的大致形式：

"settings": {
    "WMFVersion": "latest",
    "ModulesUrl": "https://UrlToZipContainingConfigurationScript.ps1.zip",
    "SasToken": "SAS Token if ModulesUrl points to private Azure Blob Storage",
    "ConfigurationFunction": "ConfigurationScript.ps1\\ConfigurationFunction",
    "Properties": {
        "ParameterToConfigurationFunction1": "Value1",
        "ParameterToConfigurationFunction2": "Value2",
        "ParameterOfTypePSCredential1": {
            "UserName": "UsernameValue1",
            "Password": "PrivateSettingsRef:Key1"
        },
        "ParameterOfTypePSCredential2": {
            "UserName": "UsernameValue2",
            "Password": "PrivateSettingsRef:Key2"
        }
    }
},
"protectedSettings": {
    "Items": {
        "Key1": "PasswordValue1",
        "Key2": "PasswordValue2"
    },
    "DataBlobUri": "https://UrlToConfigurationDataWithOptionalSasToken.psd1"
}

以前的格式调整为当前格式后的情况如下所示：

当前属性名称	以前架构的等效值
settings.wmfVersion	settings.WMFVersion
settings.configuration.url	settings.ModulesUrl
settings.configuration.script	settings.ConfigurationFunction 的第 1 部分（在“\\”之前）
settings.configuration.function	settings.ConfigurationFunction 的第 2 部分（在“\\”之后）
settings.configuration.module.name	settings.ModuleSource
settings.configuration.module.version	settings.ModuleVersion
settings.configurationArguments	settings.Properties
settings.configurationData.url	protectedSettings.DataBlobUri（没有 SAS 令牌）
settings.privacy.dataCollection	settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings	settings.AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	settings.SasToken
protectedSettings.configurationDataUrlSasToken	protectedSettings.DataBlobUri 中的 SAS 令牌

故障排除

下面是可能会遇到的一些错误及其解决方法。

无效值

“Privacy.dataCollection 为‘{0}’。可能的值只有 ''、'Enable' 和 'Disable'”。 “WmfVersion 为‘{0}’。唯一的可能值为 ... 和 'latest'”。

问题：不允许使用提供的值。

解决方案；将无效值更改为有效值。

无效的 URL

“ConfigurationData.url 为‘{0}’。这不是有效的 URL”。“DataBlobUri 为‘{0}’。这不是有效的 URL”。“Configuration.url 为‘{0}’。这不是有效的 URL”

问题：提供的 URL 无效。

解决方案；检查提供的所有 URL。确保所有 URL 都解析为扩展可在远程计算机上访问的有效位置。

无效的 ConfigurationArgument 类型

“无效的 configurationArguments 类型 {0}”

问题：ConfigurationArguments 属性无法解析为哈希表对象。

解决方案；将 ConfigurationArguments 属性设置为哈希表。遵循上述示例中提供的格式。请注意引号、逗号和括号。

重复的 ConfigurationArguments

“在公共和受保护的 configurationArguments 中发现重复的参数‘{0}’”

问题：公共设置中的 ConfigurationArguments 和受保护设置中的 ConfigurationArguments 包含同名属性。

解决方案；删除其中一个重复的属性。

缺少属性

“settings.Configuration.function 要求指定 settings.configuration.url 或 settings.configuration.module”

“settings.Configuration.url 要求指定 settings.configuration.script”

“settings.Configuration.script 要求指定 settings.configuration.url”

“settings.Configuration.url 要求指定 settings.configuration.function”

“protectedSettings.ConfigurationUrlSasToken 要求指定 settings.configuration.url”

“protectedSettings.ConfigurationDataUrlSasToken 要求指定 settings.configurationData.url”

问题：定义的属性需要另一个缺少的属性。

解决方法：

提供缺少的属性。
删除需要缺失属性的属性。

后续步骤

了解如何将虚拟机规模集与 Azure DSC 扩展配合使用。
了解有关 DSC 的安全凭据管理的更多详细信息。
获取 Azure DSC 扩展处理程序简介。
有关 PowerShell DSC 的详细信息，请转到 PowerShell 文档中心。

通过