Azure DSC Extension 2.2 & Updates to Publish-AzureVMDscConfiguration cmdlet for ASM & ARM in Azure PowerShell SDK version 0.9.7

NOTE: For information on OS support, and other features, please refer to our release history.

Today we released version 2.2 of the Azure DSC Extension to support new functionality in the Publish-AzureVMDscConfiguration cmdlet. To get the latest changes in the publish cmdlet download Azure Powershell SDK version 0.9.7

In Azure Powershell SDK version 0.9.5 we introduced new set of cmdlets for deploying the Azure DSC Extension with Azure Resource Manager (ARM). You can read more on the DSC Extension ARM cmdlets here.

Changes in Publish-AzureVMDscConfiguration cmdlet

In the previous blog, we talked about adding the following functionality to the Publish-AzureVMDscConfiguration cmdlet:

• A switch parameter to skip packing of dependent modules in the configuration archive.
  • Allow configuration data in the configuration archive.

• • Allow additional content files or directories in the configuration archive.

As part of these changes we added some new parameters to the Publish-AzureVMDscConfiguration cmdlet for both ASM and ARM.

• • ConfigurationDataPath \You can now add a configuration data file to the configuration archive using publish cmdlet. Note that the configuration data file provided through Set-AzureVMDscExtension cmdlet takes precedence over the one added through publish cmdlet.

• • AdditionalPath (“The Publish cmdlet can now package any additional files or directories in the configuration archive using this parameter. Configurations that require additional content can benefit from this change. For example, while installing the Fourth Coffee website demo (documented below), FourthCoffee.ps1 requires the website’s content directory. By using the AdditionalPath parameter, that content can be packaged with the publish cmdlet. The additional content is downloaded to the VM along with the configuration.

• • SkipDependencyDetection “By default, the publish cmdlet packages dependent resources by parsing the configuration script in the archive it creates. If the resources are already available in the VM, you can use this switch to skip that step and avoid repackaging redundant content.

• • PassThru (“Outputs the blob url for the configuration archive path. Note that this parameter is only valid for ASM Publish-AzureVMDscConfiguration cmdlet. For ARM, publish cmdlet outputs the url by default.

Here are some examples on how to use the new parameters in publish cmdlet

For the purpose of this demo we will use the Fourth Coffee configuration and ASM syntax of Publish-AzureVmDscConfiguration cmdlet.

#FourthCoffee.ps1
Configuration WebSite { 
   Import-DscResource -Module xWebAdministration     
 #AllNodes defined in the FourthCoffee.psd1 file (below). This will select the node with property 'Role' as 'TestNode'
    Node $AllNodes.Where{$_.Role -eq 'TestNode'}.NodeName

        # Install the IIS role  
        WindowsFeature IIS  
        {  
            Ensure          = 'Present'  
            Name            = 'Web-Server'  
        }  

        # Install the ASP .NET 4.5 role  
        WindowsFeature AspNet45  
        {  
            Ensure          = 'Present'  
            Name            = 'Web-Asp-Net
45'          } 
        # Stop the default website  
       xWebsite DefaultSite   
        {  
            Ensure          = 'Present'  
            Name            = 'Default Web Site'  
            State           = 'Stopped'  
            PhysicalPath    = 'C:\\inetpub\\wwwroot'  
            DependsOn       = '[WindowsFeature]IIS'  
        }  

       # Copy the website content  
        File WebContent  
       {  
            Ensure          = 'Present'  
            SourcePath      = \"$PSScriptRoot\\BakeryWebsite\
            DestinationPath = 'C:\\inetpub\\FourthCoffee' 
            Recurse         = $true  
            Type            = 'Directory'  
            DependsOn       = '[WindowsFeature]AspNet45'  
  }  
       # Create a new website  
       xWebsite BakeryWebSite   

            Ensure          = 'Present'  
       Name            = 'FourthCoffee' 
           State           = 'Started'  
           PhysicalPath    = 'C:\\inetpub\\FourthCoffee' 
           DependsOn       = '[File]WebContent'  
      } 
    }
}  

#FourthCoffee.psd1
    AllNodes = @
        @{
            NodeName = \"localhost\";
            Role     = \"TestNode\"
        }\    );
}

Note that in the ‘WebContent’ File resource you can now specify source path as $PSScriptRoot\\BakeryWebsite. We can package ‘Bakery Website’ directory as additional content in the configuration archive using the Publish cmdlet. Once we publish Fourth Coffee configuration archive, DSC extension will unpack it and copy the website content to the same directory as the configuration.

Using ConfigurationDataPath and AdditonalContent parameter without -SkipDependencyDetection switch

Archive your configuration script, configuration data and any additional content together using publish cmdlet. By default, all DSC resources gets copied over to $env:ProgramFiles\\Windows Powershell\\Modules and configuration data along with any additional content to the configuration directory on the VM.

PS C:\\> Publish-AzureVMDscConfiguration -ConfigurationPath 'C:\\data\\dscsolutions\\dsc-azure-ext\\tests\\data\\configurations\\FourthCoffee.ps1' -ConfigurationArchivePath 'C:\\demo\\FourthCoffee.ps1.zip' \-ConfigurationDataPath 'C:\\data\\dscsolutions\\dsc-azure-ext\\tests\\data\\configurations\\FourthCoffee.psd1' -AdditionalPath @(\"C:\\data\\dscsolutions\\dsc-azure-ext\\tests\\data\\BakeryWebsite\") -Force -Verbose\

If you open the ZIP package using the file explorer, you will see it contains dscmetadata.json, FourthCoffee.ps1, FourthCoffee.psd1, xWebAdministration and BakeryWebsite directory.

‘Metadata dscmetadata.json’ file and its use

The file ‘dscmetadata.json’ contains information about the configuration data path, DSC resources and other files/directories as additional content. It is created and copied to the archive based on the input parameters by the publish cmdlet.

Here are the contents of the dscmetadata.json file for the Fourth Coffee configuration:

{\"ConfigurationData\":\"FourthCoffee.psd1\",\"AdditionalContent\":[\"BakeryWebsite\"],\"Modules\":[\"xWebAdministration\"]}

ConfigurationData – ‘FourthCoffee.psd1’ is the configuration data file that was passed to the publish cmdlet. This data file is used by DSC extension unless it is overwritten by a data file through set cmdlet. AdditionalContent – represents a list of files and directories passed to the publish cmdlet through the AdditionalPath parameter. In this example, the Fourth Coffee configuration requires website content to complete successfully, so the metadata file points to the ‘BakeryWebsite’ directory as additional content. Modules – are DSC resources required by the configuration script. Fourth Coffee requires ‘xWebAdministration’ DSC resource to run.

Using ConfigurationDataPath and Ad ditionalContent parameter with -SkipDependencyDetection switch

If you already have DSC resources required by the configuration script on the VM, you can use ‘SkipDependencyDetection’ switch to skip adding it in the archive.

PS C:\\> Publish-AzureVMDscConfiguration -ConfigurationPath 'C:\\data\\dscsolutions\\dsc-azure-ext\\tests\\data\\configurations\\FourthCoffee.ps1' -ConfigurationArchivePath 'C:\\demo\\FourthCoffee.ps1.zip' \-ConfigurationDataPath 'C:\\data\\dscsolutions\\dsc-azure-ext\\tests\\data\\configurations\\FourthCoffee.psd1' -AdditionalPath @(\"C:\\data\\dscsolutions\\dsc-azure-ext\\tests\\data\\BakeryWebsite\") -SkipDependencyDetection -Force -Verbose\

If you open the ZIP package using the file explorer, you will see it contains dscmetadata.json, FourthCoffee.ps1, FourthCoffee.psd1 and BakeryWebsite directory. The DSC resource module ‘xWebAdministration’ does not exist in the archive.

Here are the contents of the dscmetadata.json file with ‘SkipDependencyDetection’ switch. Since ‘xWebAdministration’ module does not exist in the archive, its entry is also missing from the metadata file.

{\"ConfigurationData\":\"FourthCoffee.psd1\",\"AdditionalContent\":[\"BakeryWebsite\"]}

If the publish cmdlet is used to upload or create the configuration archive, it will generate and package the metadata file to the archive. However, if you are creating the ZIP file on your own and would like to package configuration data and any other additional files then you need to create a metadata file just like the sample below.

Sample:

{\"ConfigurationData\":\"ConfigData.psd1\",\"AdditionalContent\":[\"Directory1\",\"File1.txt\"],\"Modules\":[\"Module1\"]}