ARM DSC Extension Settings

Overview

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

Fast Reference

"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"
}

Details

Property Name Type Description
settings.wmfVersion string Specifies 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.url string Specifies 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.script string Specifies 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.function string Specifies 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.configurationArguments Collection Defines any parameters you would like to pass to your DSC configuration. This property will not be encrypted.
settings.configurationData.url string Specifies 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.dataEnabled string Enables 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.forcePullAndApply Bool Enables the DSC Extension to update and enact DSC configurations when the refresh mode is Pull.
settings.advancedOptions.downloadMappings Collection Defines alternate locations to download dependencies such as WMF and .NET. More Information
protectedSettings.configurationArguments Collection Defines any parameters you would like to pass to your DSC configuration. This property will be encrypted.
protectedSettings.configurationUrlSasToken string Specifies the SAS token to access the URL defined by configuration.url. This property will be encrypted.
protectedSettings.configurationDataUrlSasToken string Specifies 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:

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

Example

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

Configuration TestConfig
{
    param ( 
        $CountryName
    )
    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    File TestFile
    {
        Ensure = "Present"
        DestinationPath = "C:\TestFile"
        Contents = "Hello there fair traveler! Welcome to $CountryName!"
    }
}

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:

"settings": {
    "configuration": {
        "url": "https://superworldtraveler.thisisnotarealURL/WorldlyConfig.zip'",
        "script": "WorldlyConfig.ps1",
        "function": "TestConfig"
    },
    "configurationArguments": {
        "CountryName": "Canada"
    } 
},
"protectedSettings": {
    "configurationUrlSasToken": "?flibberdigibbets"
}

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:

"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"
        }
    }
    "Privacy": {
        "DataCollection": "enable"
    },
    "AdvancedOptions": {
        "DownloadMappings": {
            "specificDependencyKey": "https://myCustomDependencyLocation"
        }
    }
},
"protectedSettings": { 
    "Items": { 
        "Key1": "PasswordValue1", 
        "Key2": "PasswordValue2" 
    }, 
    "DataBlobUri": "https://UrlToConfigurationDataWithOptionalSasToken.psd1"
}

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

Property Name Previous Schema Equivalent
settings.wmfVersion settings.WMFVersion
settings.configuration.url settings.ModulesUrl
settings.configuration.script 1st part of settings.ConfigurationFunction (before ‘\\’)
settings.configuration.function 2nd part of settings.ConfigurationFunction (after ‘\\’)
settings.configurationArguments settings.Properties
settings.configurationData.url protectedSettings.DataBlobUri (without SAS token)
settings.privacy.dataEnabled settings.Privacy.DataEnabled
settings.advancedOptions.downloadMappings settings.AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments protectedSettings.Properties
protectedSettings.configurationUrlSasToken settings.SasToken
protectedSettings.configurationDataUrlSasToken SAS 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.