採用 Azure Resource Manager 範本的預期狀態設定延伸模組

發行項
12/18/2024

注意

啟用 DSC 擴充功能之前，我們希望您知道較新版本的 DSC 現已正式推出，由名為電腦設定的功能管理。計算機設定功能包含 Desired 狀態設定（DSC）擴充功能處理程式的功能，以及客戶意見反應中最常要求的功能。機器設定也包含混合機器支援 (透過已啟用 Arc 的伺服器提供)。

本文說明適用於預期狀態設定 (DSC) 延伸模組處理常式的 Azure Resource Manager 範本。

注意

您可能會遇到略為不同的結構描述範例。結構描述變更出現在 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 屬性的區段。在 extensions 下方新增 DSC 擴充功能的詳細資料。

如需有關撰寫部署擴充功能之虛擬機器擴展集範本的最新詳細數據，請參閱檔 Microsoft.Compute virtualMachineScaleSets

DSC 延伸模組會繼承預設的延伸模組屬性。如需詳細資訊，請參閱 VirtualMachineScaleSetExtension 類別(英文\)。

設定與 protectedSettings

所有設定都會儲存在 VM 上的 settings 文字檔中。列在 settings 底下的屬性是公用屬性。公用屬性在設定文字檔中不會加密。列在 protectedSettings 底下的屬性會以憑證加密，而不會在 VM 上的設定檔案中以純文字顯示。

如果設定需要認證，您可以將認證包含在 protectedSettings中：

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

在 Azure 儲存體中使用設定指令碼的範例

下列範例來自 DSC 延伸模組處理常式概觀。此範例使用 Resource Manager 範本 (而不是Cmdlet) 來部署擴充功能。請儲存 IisInstall.ps1 設定、將其放在 .zip 檔案 (例如：iisinstall.zip) 中，然後以可存取的 URL 上傳此檔案。此範例會使用 Azure Blob 儲存體，但您可以從任意位置下載 .zip 檔案。

在 Resource Manager 範本中，下列程式碼會指示 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 的第一個部分 (在 \\ 之前)
settings.configuration.function	settings.ConfigurationFunction 的第二個部分 (在 \\ 之後)
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	SAS token from protectedSettings.DataBlobUri

疑難排解

以下是一些您可能遇到的錯誤與其修正方式。

無效的值

「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 文件中心。

共用方式為