Using the new Azure PowerShell Az module in automation runbooks

Microsoft released a new Azure module for PowerShell at the end of 2018, and its name is Az module. All updates will be applied to this new module. The previous module was called AzureRM and the last version available is 6.13.1. When creating a new automation account, all initial PowerShell runbooks use the AzureRM module. In this article, we are going to cover the required changes that need to be performed to start using the new Az module with automation accounts.

You may be wondering: Is it just a matter of renaming the cmdlets that we have in our scripts? There are two small complications: First, they don’t work together, so in general, we should use one or the other. Second, the Az module is the future, and they are receiving constant updates. That being said, we should make sure that any available and required parameters are the same or at least compatible with the previous module. An example to illustrate our scenario — by just changing a single cmdlet between AzureRM and Az module gives the following error.

The golden rule is the name convention for the cmdlets: When we change AzureRM to AZ. For example, Get-AzureRMVM in the new module is Get-azVM, that’s it! There are some exceptions but not a lot.

Creating a new automation account in Microsoft Azure

The first step is to create a new Azure automation account. Logged on Azure Portal, type Automation Accounts on the search button. In the new blade, click on Add and define a name, resource group, and make sure to leave yes in the Create an Azure RunAs Account? Section. Click on Create and wait for the completion of the creation process.

Click on the newly created Automation Account, and then click on Runbooks item. The default ones that come with any new Automation Account will be listed, double click on AzureAutomationTutorialScript which is a PowerShell Runbook type. In the new blade which is specific for that given runbook, click on Edit to see the code, and the result will be similar to the image depicted below.

We highlighted all the cmdlets that are using previous modules, and they need to be replaced to use AZ Module.

As you start switching from AzureRM to Az module, most of the cmdlets are just a matter of following our golden rule (replace AzureRM for Az). It is recommended to check if the replaced cmdlets have the same parameter requirements to be safe.

However, if you are not sure, the best way is to check the online documentation. For every single cmdlet, Microsoft informs the module as depicted in the image below. That gives you enough information to decide which module is in use and the required parameters.

I used the first rule that we can use to transition modules. So, I look for Get-AzResourceGroup (just replaced AzureRM string for AZ), and I found the cmdlet and the parameters.

Loading the Az modules in your automation account

When using automation accounts, the goal is to keep it as simple as possible, which includes loading only the required modules for your runbooks. To use Az Modules, we need to install the Az.Accounts module, which is a requirement for any other Az module that we may require.

Go back to the first blade of your automation account, click on Modules item on the left side. Click on Browse Gallery, in the new blade, type Az.Accounts and click on the first item, then click Import. In the new blade that will be displayed, click OK, and wait for the completion.

We should repeat the same process for any other module that we need. Because we want to manage Azure resources, we are going ahead, and we will be adding the modules: Az.Compute, Az.Resources and Az.Automation.

After downloading the module into your automation account, we can always check the properties of the module, and a list of all cmdlets that are part of the module will be listed.

Performing the changes to use Az module

In this first runbook, which comes with any new automation account, we need to add/change the items in red to get the runbook running with the Az module. If you want a copy of this script below, you can get it from GitHub here.

Import-Module Az.Accounts
Import-Module Az.Automation
Import-Module Az.Compute
$connectionName = "AzureRunAsConnection"
try
{
    # Get the connection "AzureRunAsConnection "
    $servicePrincipalConnection = Get-AutomationConnection -Name $connectionName       
    "Logging in to Azure..."
    Connect-AzAccount `
        -ServicePrincipal `
        -TenantId $servicePrincipalConnection.TenantId `
        -ApplicationId $servicePrincipalConnection.ApplicationId `
        -CertificateThumbprint $servicePrincipalConnection.CertificateThumbprint 
}
catch {
    if (!$servicePrincipalConnection)
    {
        $ErrorMessage = "Connection $connectionName not found."
        throw $ErrorMessage
    } else{
        Write-Error -Message $_.Exception
        throw $_.Exception
    }
}
#Get all ARM resources from all resource groups
$ResourceGroups = Get-AzResourceGroup 
foreach ($ResourceGroup in $ResourceGroups)
{    
    Write-Output ("Showing resources in resource group " + $ResourceGroup.ResourceGroupName)
    $Resources = Get-AzResource -ResourceGroupName $ResourceGroup.ResourceGroupName | Select ResourceName, ResourceType
    ForEach ($Resource in $Resources)
    {
        Write-Output ($Resource.ResourceName + " of type " +  $Resource.ResourceType)
    }
    Write-Output ("")
} 

Some notes from the field

Overall the process is not difficult, and it is more an exercise of patience and validation of the existing scripts when using the new Az module cmdlets. Here are some key points that I would like to bring it up to your attention:

• At this time, any new automation account has the built-in runbooks using AzureRM module. So, if you switched over to Az modules, keep it, and don’t use the built-in runbooks, or change them accordingly to use the new module.
• Make sure to upgrade your current AzureRM module to the latest version available (6.13.1, to be precise). You must validate that your existing scripts are working correctly in the latest version of AzureRM before performing any transition
• We can take advantage of Enable-AzureRMAlias cmdlet to keep compatibility with Az module to be able to recognize the legacy cmdlets. There are some caveats that you need to aware of. This cmdlet does not work in modules, just cmdlets.
• Some modules changed their names, and the most conspicuous one is the AzureRM.Profile changed to Az.Accounts.
• The Get-AutomationAccount cannot be replaced at this point by Get-AZAutomationAccount. There is a known error that makes hard to use in an automation script.

Featured image: Shutterstock