July 20th, 2015

Introducing Azure Resource Manager cmdlets for Azure PowerShell DSC Extension

PowerShell Team
PowerShell Team

Last August we introduced Azure Service Management (ASM) cmdlets for PowerShell Desired State Configuration (DSC). Through these cmdlets released in the Azure PowerShell SDK, you can upload and apply a PowerShell DSC Configuration to an Azure VM. Now, we are introducing new set of cmdlets for deploying DSC Extension with Azure Resource Manager (ARM). You can read more on using Azure PowerShell with ARM here

If you already have the Azure PowerShell SDK installed, you will need to update to version 0.9.5

 

Key differences in ASM and ARM cmdlets

  • In ARM, Resource group name, virtual machine name and storage account name are the new required parameters.
  • ARM cmdlets are synchronous as opposed to ASM which are asynchronous.

 

Let’s look at each cmdlet and the syntax in detail below:

 

NAME

Publish-AzureVMDscConfiguration

 

SYNOPSIS

Uploads a Desired State Configuration script to Azure blob storage, which later can be applied to Azure Virtual Machines using the Set-AzureVMDscExtension cmdlet.

 

 

ASM SYNTAX

Publish-AzureVMDscConfiguration [-ConfigurationPath] <String> [-ContainerName <String>] [-Force [<SwitchParameter>]] [-StorageContext <AzureStorageContext>] [-StorageEndpointSuffix <string>] [-WhatIf [<SwitchParameter>]] [-Confirm [<SwitchParameter>]] [<CommonParameters>]

Publish-AzureVMDscConfiguration [-ConfigurationPath] <String> [-Force [<SwitchParameter>]] [-ConfigurationArchivePath <String>] [-WhatIf [<SwitchParameter>]] [-Confirm [<SwitchParameter>]] [<CommonParameters>]

 

 

 

ARM SYNTAX

Publish-AzureVMDscConfiguration [-ResourceGroupName] <string> [-ConfigurationPath] <String> [[-ContainerName] <String>] [-Force [<SwitchParameter>]] [-StorageAccountName] <String> [-StorageEndpointSuffix <string>] [-WhatIf [<SwitchParameter>]] [-Confirm [<SwitchParameter>]] [<CommonParameters>]

 

Publish-AzureVMDscConfiguration [-ConfigurationPath] <String> [-Force [<SwitchParameter>]] [[-OutputArchivePath] <String>] [-WhatIf [<SwitchParameter>]] [-Confirm [<SwitchParameter>]] [<CommonParameters>]

 

 

 

 

 

As you can see from the ARM syntax above, ResourceGroupName (the name of the resource group that contains the storage account) and StorageAccountName (the Azure storage account name where the configuration would be uploaded) are required for uploading the configuration to the Azure storage.

Let’s take the IIS Install example from the previous blog.

Image 7457 image thumb 1B0BEE39

 

To upload configuration IISInstall.ps1 to Azure storage using ARM, we need a resource group (example-rg1) with a storage account (examplerg1stg).

Publish-AzureVMDscConfiguration -ResourceGroupName example-rg1 -ConfigurationPath “C:\examples\IISInstall.ps1” -StorageAccountName examplerg1stg

Output:

https://examplerg1stg.blob.core.windows.net/windows-powershell-dsc/IISInstall.ps1.zip

In the output above, https://examplerg1stg.blob.core.windows.net is the URL of the Azure blob, ‘windows-powershell-dsc’ is the default container and IISInstall.ps1.zip is the configuration archive created by the publishing cmdlet.

 

NAME

Set-AzureVMDSCExtension

 

SYNOPSIS

Configure the Windows PowerShell Desired State Configuration extension on a VM.

 

 

ASM SYNTAX

Set-AzureVMDscExtension [-ReferenceName <String>] [-ConfigurationArgument <Hashtable>] [-ConfigurationDataPath <String>] [-ConfigurationArchive] <String> [-ConfigurationName <String>] [-ContainerName <String>] [-Force [<SwitchParameter>]] [-StorageContext <AzureStorageContext>] [-Version <String>] [-StorageEndpointSuffix <String>] -VM <IPersistentVM> [-WhatIf [<SwitchParameter>]] [-Confirm [<SwitchParameter>]] [<CommonParameters>]

ARM SYNTAX

Set-AzureVMDSCExtension [-ArchiveBlobName] <string> [-ResourceGroupName] <string> [-VMName] <string> [-ArchiveStorageAccountName] <string> [-Version] <string> [-ConfigurationArgument <hashtable>] [-ConfigurationData <string>] [-ConfigurationName <string>] [-ArchiveResourceGroupName <string>] [-ArchiveContainerName <string>] [-Force] -Location <string> [-Name <string>] [-ArchiveStorageEndpointSuffix <string>] [-AutoUpdate] [-Confirm] [-WhatIf] [<CommonParameters>]

 

 

 

 

 

 

In order to improve our user experience, we have changed the name of some parameters, and as a part of the ARM changes have added some new required parameters.

  • ResourceGroupName, VMName, ArchiveStorageAccountName, Version, Location are all new required parameters.
  • ArchiveResourceGroupName is a new optional parameter. You can specify this when your storage account belongs to a difference resource group than the one where the virtual machine is created.
  • ConfigurationArchive is now called ArchiveBlobName
  • ContainerName is now called ArchiveContainerName
  • StorageEndpointSuffix is now called ArchiveStorageEndpointSuffix
  • You can now use the –AutoUpdate switch to enable automatic updating of the extension handler to the latest version as and when it is available.

For more information on these parameters run Get-Help Set-AzureVMDscExtension –Detailed

 

Now let’s try to apply the configuration archive IISInstall.ps1.zip that we created using the Publish cmdlet to a virtual machine “example-rg1-vm1” in the resource group “example-rg1”

 

 

Set-AzureVMDscExtension -ResourceGroupName example-rg1 -VMName example-rg1-vm1 -ArchiveBlobName IISInstall.ps1.zip -ArchiveStorageAccountName examplerg1stg -ConfigurationName IISInstall -Version 2.0 -Location ‘West US’

 

Note that we are using the latest DSC Extension version 2.0 and have not specified the –AutoUpdate flag. This will ensure that the extension version is pinned to 2.0 unless it’s updated. Also, note that we are not using Update-AzureVM to update the VM as the Set-AzureVMDscExtension cmdlet for ARM is synchronous. On the flip side, it takes longer for the Set-AzureVMDscExtension cmdlet to finish the update operation. However, you can view the status of the extension using the Get-AzureVM cmdlet as described below:

 

 

 

 

PS C:\> $status = Get-AzureVM -ResourceGroupName example-rg1 -Name example-rg1  
-vm1 -Status -Verbose                                                           
PS C:\> $status.Extensions.Statuses                                             
                                                                                
                                                                                
Code          : ProvisioningState/transitioning                                 
DisplayStatus : Transitioning                                                   
Level         : Info                                                            
Message       : DSC configuration is in progress.                               
Time          :                                                                 
                                                                                
                                                                                
                                                                                
PS C:\> $status.Extensions.SubStatuses                                          
                                                                                
                                                                                
Code          : ComponentStatus/DscConfigurationLog/transitioning               
DisplayStatus : Transitioning                                                   
Level         : Info                                                            
Message       : Perform operation 'Invoke CimMethod' with following             
                parameters, ''methodName' = SendConfigurationApply,'className'  
                = MSFT_DSCLocalConfigurationManager,'namespaceName' =           

     root/Microsoft/Windows/DesiredStateConfiguration'.              
Time          :                                                                 
PS C:\> $status = Get-AzureVM -ResourceGroupName example-rg1 -Name example-rg1  
-vm1 -Status -Verbose                                                           
PS C:\> $status.Extensions.Statuses                                             
                                                                                
                                                                                
Code          : ProvisioningState/succeeded                                     
DisplayStatus : Provisioning succeeded                                          
Level         : Info                                                            
Message       : DSC configuration was applied successfully.                     
Time          :                                                                 
                                                                                
                                                                                
                                                                                
PS C:\> $status.Extensions.SubStatuses                                          
                                                                                
                                                                                
Code          : ComponentStatus/DscConfigurationLog/succeeded                   
DisplayStatus : Provisioning succeeded                                          
Level         : Info                                                            
Message       : Perform operation 'Invoke CimMethod' with following             
                parameters, ''methodName' = SendConfigurationApply,'className'  
                = MSFT_DSCLocalConfigurationManager,'namespaceName' =           
                root/Microsoft/Windows/DesiredStateConfiguration'.              
                An LCM method call arrived from computer EXAMPLE-RG1-VM1 with   
                user sid S-1-5-18.                                              
                The -Force option was specified with the Stop operation. The    
                current configuration has been successfully cancelled.          
                An LCM method call arrived from computer EXAMPLE-RG1-VM1 with   
                user sid S-1-5-18.                                              
                [EXAMPLE-RG1-VM1]: LCM:  [ Start  Set      ]                    
                [EXAMPLE-RG1-VM1]: LCM:  [ Start  Resource ]                    
                [[WindowsFeature]IIS]                                           
                [EXAMPLE-RG1-VM1]: LCM:  [ Start  Test     ]                    
                [[WindowsFeature]IIS]                                           
                [EXAMPLE-RG1-VM1]:                                              
                [[WindowsFeature]IIS] The operation 'Get-WindowsFeature'        
                started: Web-Server                                             
                [EXAMPLE-RG1-VM1]:                                              
                [[WindowsFeature]IIS] The operation 'Get-WindowsFeature'        
                succeeded: Web-Server                                           
                [EXAMPLE-RG1-VM1]: LCM:  [ End    Test     ]                    
                [[WindowsFeature]IIS]  in 16.3710 seconds.                      
                [EXAMPLE-RG1-VM1]: LCM:  [ Skip   Set      ]                    
                [[WindowsFeature]IIS]                                           
                [EXAMPLE-RG1-VM1]: LCM:  [ End    Resource ]                    
                [[WindowsFeature]IIS]                                           
                [EXAMPLE-RG1-VM1]: LCM:  [ End    Set      ]                    
                [EXAMPLE-RG1-VM1]: LCM:  [ End    Set      ]    in  23.8520
  
                seconds.                                                        
                Operation 'Invoke CimMethod' complete.                          
                Time taken for configuration job to complete is 34.903 seconds  
Time          :                                                                 
                                                                                

 

**We are working on improving this experience of retrieving the configuration status. Stay tuned for more updates.

 

Output of the Set-AzureVMDscExtension cmdlet post configuration update.

 

 

 

PS C:\> Set-AzureVMDscExtension -ResourceGroupName example-rg1 -VMName example-r
g1-vm1 -ArchiveBlobName IISInstall.ps1.zip -ArchiveStorageAccountName examplerg1
stg -ConfigurationName IISInstall -Version 2.0 -Location 'West US'              
                                                                                
                                                                                
Status              : Succeeded                                                 
Output              :                                                           
Error               :                                                           
StartTime           : 7/20/2015 12:41:05 PM -07:00                              
EndTime             : 7/20/2015 12:45:05 PM -07:00                              
TrackingOperationId : 9bed9a33-da40-4933-941f-b7acbc1e38ba                      
                                                                                

Example: Use of Set cmdlet with arguments to the configuration function and -Autoupdate switch

Set-AzureVMDscExtension -ResourceGroupName example-rg1 -VMName example-rg1-vm1 -ArchiveBlobName IISSample.ps1.zip -ArchiveStorageAccountName examplerg1stg -ConfigurationName IISInstall -ConfigurationArgument @{arg=”val”} -ArchiveContainerName “Your_Container_Name” -ConfigurationData SampleData.psd1 -Version 1.10 -Location ‘West US’ –AutoUpdate

 

 

 

 

 

 

 

 

 

You can also use ARM templates to install the extension and use Set-AzureVMDscExtension cmdlet to apply configurations to the same VM. Note that the name of the extension provided in the –Name parameter of the cmdlet should match to that in the template. By default, value of the –Name parameter is ‘Microsoft.Powershell.DSC’. Also, name of the extension is case sensitive.

 

 

Use Get-AzureVMDscExtension to see the DSC Extension status of the configuration applied.

 

NAME

Get-AzureVMDscExtension

 

SYNOPSIS

Gets the settings of the DSC extension on a particular VM

 

 

ASM SYNTAX

Get-AzureVMDscExtension [-VM] <IPersistentVM> [[-Version] <string>] [<CommonParameters>]

 

 

ARM SYNTAX

Get-AzureVMDscExtension [-ResourceGroupName] <string> [-VMName] <string> [[-Name] <String>] [-Status] [<CommonParameters>]

 

 

Example: As you can see from the output of this cmdlet below, the IISInstall.ps1 was applied successfully to the virtual machine example-rg1-vm1 in the resource group “example-rg1”

 

PS C:\> Get-AzureVMDscExtension -ResourceGroupName example-rg1 -VMName example-r
g1-vm1 -Status                                                                  
                                                                                
                                                                                
ResourceGroupName     : example-rg1                                             
Name                  : Microsoft.Powershell.DSC                                
Publisher             : Microsoft.Powershell                                    
ExtensionType         : DSC                                                     
TypeHandlerVersion    : 2.0                                                     
ProvisioningState     : Succeeded                                               
Location              : westus                                                  
Id                    : /subscriptions/4c85cb83-4cad-46cd-a771-ff9d1c079de2/res 
                        ourceGroups/example-rg1/providers/Microsoft.Compute/virt
                       ualMachines/example-rg1-vm1/extensions/Microsoft.Powershe
                       ll.DSC                                                   
ModulesUrl            : https://examplesrg1stg.blob.core.windows.net/windows-pow
                        ershell-dsc/IISInstall.ps1.zip                          
ConfigurationFunction : IISInstall.ps1\IISInstall                               
Properties            : {}                                                      
Statuses              : [                                                       
                          {                                                     
                            "Code": "ProvisioningState/succeeded",              
                            "DisplayStatus": "Provisioning succeeded",          
                            "Level": "Info",                                    
                            "Message": "DSC configuration was applied           
                        successfully.",                                         
                            "Time": null                                        
                          }                                                     
                        ]                                                       
                                                                                

NAME

Remove-AzureVMDscExtension

 

SYNOPSIS

Removes DSC extension handler from a given virtual machine(s) in a cloud service. Output of this cmdlet needs to be piped to Update-AzureVM cmdlet. To get detailed output -Verbose flag need to be specified.

 

 

ASM SYNTAX

Remove-AzureVMDscExtension -VM <IPersistentVM> [<CommonParameters>]

 

NAME

Remove-AzureVMDscExtension

SYNOPSIS

Removes DSC extension handler from a VM in a resource group

 

 

ARM SYNTAX

Remove-AzureVMDscExtension [-ResourceGroupName] <String> [-VMName] <String> [[-Name] <String>] [<CommonParameters>]

 

 

 

 

Example:

PS C:\> Remove-AzureVMDscExtension -ResourceGroupName example-rg1 -VMName exampl
e-rg1-vm1 -Name 'Microsoft.Powershell.DSC'                                      
                                                                                
                                                                                
Status              : Succeeded                                                 
Output              :                                                           
Error               :                                                           
StartTime           : 1/1/0001 12:00:00 AM +00:00                               
EndTime             :                                                           
TrackingOperationId :                                                           
                                                                                

 

Note that unlike ASM the Remove operation in ARM is synchronous as well.

 

 

 

Upcoming Changes:

The functionalities we are considering working on for the next release of Azure PowerShell SDK release are the following:

  • A switch parameter to skip packing of dependent modules in the zip file.
  • Allow adding configuration data in the zip file.
  • Allow adding other additional content in the zip file.

Let us know what you think in the comments below!

Category
PowerShell

Author

PowerShell Team
PowerShell Team

PowerShell is a task-based command-line shell and scripting language built on .NET. PowerShell helps system administrators and power-users rapidly automate tasks that manage operating systems (Linux, macOS, and Windows) and processes.

0 comments

Discussion are closed.