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.
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 examplerg1stgOutput:
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 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!