ARM DSC Extension Settings

PowerShell Team

PowerShell Team

Update for the latest information regarding DSC Extension, refer to the product documentation.

……….

Overview

This is the schema for the settings portion of the Azure DSC extension in an ARM template.

Fast Reference

Details

Property NameTypeDescription
settings.wmfVersionstringSpecifies the version of the Windows Management Framework that should be installed on your VM. Setting this property to ‘latest’ will install the most updated version of WMF. The only current possible values for this property are ‘4.0’, ‘5.0’, and ‘latest’. These possible values are subject to updates. The default value is ‘latest’.
settings.configuration.urlstringSpecifies the URL location from which to download your DSC configuration zip file. 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. This property is required if settings.configuration.script and/or settings.configuration.function are defined.
settings.configuration.scriptstringSpecifies the file name of the script that contains the definition of your DSC configuration. This script must be in the root folder of the zip file downloaded from the URL specified by the configuration.url property. This property is required if settings.configuration.url and/or settings.configuration.script are defined.
settings.configuration.functionstringSpecifies the name of your DSC configuration. The configuration named must be contained in the script defined by configuration.script. This property is required if settings.configuration.url and/or settings.configuration.function are defined.
settings.configurationArgumentsCollectionDefines any parameters you would like to pass to your DSC configuration. This property will not be encrypted.
settings.configurationData.urlstringSpecifies the URL from which to download your configuration data (.pds1) file to use as input for your DSC configuration. 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.dataEnabledstringEnables or disables telemetry collection. The only possible values for this property are ‘Enable’, ‘Disable’, ”, or $null. Leaving this property blank or null will enable telemetry. The default value is ”. More Information
settings.advancedOptions.forcePullAndApplyBoolEnables the DSC Extension to update and enact DSC configurations when the refresh mode is Pull.
settings.advancedOptions.downloadMappingsCollectionDefines alternate locations to download dependencies such as WMF and .NET. More Information
protectedSettings.configurationArgumentsCollectionDefines any parameters you would like to pass to your DSC configuration. This property will be encrypted.
protectedSettings.configurationUrlSasTokenstringSpecifies the SAS token to access the URL defined by configuration.url. This property will be encrypted.
protectedSettings.configurationDataUrlSasTokenstringSpecifies the SAS token to access the URL defined by configurationData.url. This property will be encrypted.

Settings vs. ProtectedSettings

All of these settings will be saved in a settings text file on your VM.

Properties under ‘settings’ are considered public properties because they will not be encrypted in the settings text file.

Properties under ‘protectedSettings’ will be encrypted with a certificate and will not be shown in plain text in this file on your VM.

So, if your configuration needs credentials, and you would like these credentials to be encrypted on your VM, you can include them in protectedSettings like so:

Example

I have a simple configuration I made that looks like this:

I want to use the Azure DSC Extension in an ARM template to apply this configuration to my VM.

So, first, I save this configuration in a file named ‘WorldlyConfig.ps1’, zip it up, and post the zip file on my website at the URL ‘https://superworldtraveler.thisisnotarealURL/WorldlyConfig.zip’ (just an example, not a real URL).

This file on my website has restricted access, so I will need to provide a SAS token.

I generate the SAS Token ‘?flibberdigibbets’ so that the extension can access the file.

Now, in my ARM template, I use these settings to tell the DSC extension to run my configuration:

Updating from the Previous Format

Any settings in the previous format (containing the public properties ModulesUrl, ConfigurationFunction, SasToken, or Properties) will be automatically adapted to the current format and will run just as they did before.

The previous settings schema looked like this:

Here’s how the previous format adapts to the current format:

Property NamePrevious Schema Equivalent
settings.wmfVersionsettings.WMFVersion
settings.configuration.urlsettings.ModulesUrl
settings.configuration.script1st part of settings.ConfigurationFunction (before ‘\\’)
settings.configuration.function2nd part of settings.ConfigurationFunction (after ‘\\’)
settings.configurationArgumentssettings.Properties
settings.configurationData.urlprotectedSettings.DataBlobUri (without SAS token)
settings.privacy.dataEnabledsettings.Privacy.DataEnabled
settings.advancedOptions.downloadMappingssettings.AdvancedOptions.DownloadMappings
protectedSettings.configurationArgumentsprotectedSettings.Properties
protectedSettings.configurationUrlSasTokensettings.SasToken
protectedSettings.configurationDataUrlSasTokenSAS token from protectedSettings.DataBlobUri

Troubleshooting – Error Code 1100

Error Code 1100 indicates that there is a problem with the user input to the DSC extension.

The text of these errors is variable and may change.

Here are some of the errors you may run into and how you can fix them.

Invalid Values

“Privacy.dataCollection is ‘{0}’. The only possible values are ”, ‘Enable’, and ‘Disable'”

“WmfVersion is ‘{0}’. Only possible values are . and ‘latest'”

Problem: A provided value is not allowed.

Solution: Change the invalid value to a valid value. See the table in the Details section above.

Invalid URL

“ConfigurationData.url is ‘{0}’. This is not a valid URL”

“DataBlobUri is ‘{0}’. This is not a valid URL”

“Configuration.url is ‘{0}’. This is not a valid URL”

Problem: A provided URL is not valid.

Solution: Check all your provided URLs. Make sure they all resolve to valid URLs that the extension can access on the remote machine.

Invalid ConfigurationArgument Type

“Invalid configurationArguments type {0}”

Problem: The ConfigurationArguments property cannot resolve to a Hashtable object.

Solution: Make your ConfigurationArguments property a Hashtable. Follow the format provided in the example above. Watch out for quotes, commas, and braces.

Duplicate ConfigurationArguments

“Found duplicate arguments ‘{0}’ in both public and protected configurationArguments”

Problem: The ConfigurationArguments in public settings and the ConfigurationArguments in protected settings contain properties with the same name.

Solution: Remove one of the duplicate properties.

Missing Properties

“Configuration.function requires that configuration.url or configuration.module is specified”

“Configuration.url requires that configuration.script is specified”

“Configuration.script requires that configuration.url is specified”

“Configuration.url requires that configuration.function is specified”

“ConfigurationUrlSasToken requires that configuration.url is specified”

“ConfigurationDataUrlSasToken requires that configurationData.url is specified”

Problem: A defined property needs another property that is missing.

Solutions:

  • Provide the missing property.
  • Remove the property that needs the missing property.
PowerShell Team
PowerShell Team

Follow PowerShell Team   

No Comment.