PowerShell How-To

Using PowerShell for Parametrized Azure Resource Manager Templates

• By Adam Bertram
• 07/16/2019

Developers and administrators have many ways to deploy resources to Microsoft Azure. But when deploying many resources at once that consist of a full "stack" of resources, Azure Resource Manager (ARM) templates are a great way to make it happen.

ARM templates are text files written in JSON that provide the ability to define what Azure resources should be deployed, not how to do it. An everyday use case for using an ARM template is when needing to deploy a full stack of components -- like everything necessary to build a Web application. Web apps can include resources like app services, SQL servers and databases, load balancers and more. It requires a lot more to build a Web app than just a Web app resource!

Using Parameters
One way ARM templates can be built is with parameters. Parameters in ARM templates allow us to reuse templates for common purposes passing in values when the template is deployed to Azure. This prevents having to create multiple templates to perform similar actions.

To demonstrate a parameterized ARM template, let's start with an example. You can find this example in a GitHub gist. This template contains some common resources like a Web app, app service, a SQL server and database, along with a SQL Server firewall rule.

Notice on lines 4 to 11 that you'll see a parameters{} node. This is where all of the template parameters are defined. Each parameter has a name with an associated type (string, in this case) and other optional attributes. In this example, we have two string parameters called webAppName and sqlDbName.

"parameters": {
    "webAppName": {
        "type": "string"
    },
    "sqlDbName": {
        "type": "string"
    }
}

These two attributes are parameters because it's entirely possible to deploy more than one Web app using this configuration with a different Web app and SQL database name.

Deploying ARM Templates
Once we have the ARM template defined, we then need a way to deploy it to our Azure subscription. One way to do that is with PowerShell and the Azure PowerShell module. If you don't already have the Azure PowerShell modules, run Install-Module -Name Az to get it downloaded. Once downloaded, connect to your Azure subscription by running Connect-AzAccount.

Once authenticated, you'll then need to run the New-AzResourceGroupDeployment cmdlet. This cmdlet kicks off Azure's resource group deployments from ARM templates.

You can invoke deployments with parameters one of two ways: with a parameter file and with a parameter object.

Using a Parameter File
A parameter file is another JSON file that contains the values to pass to the parameters in the ARM template. The parameter file has a single parameters node with each parameter name and value defined inside, as shown below. In this example, we're passing in the value of MyWebApp to the webAppName parameter and the value of MyDb to the sqlDbName parameter.

{ 
    "$schema": "",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "webAppName": {
            "value": "MyWebApp"
        },
        "sqlDbName": {
            "value": "MyDb"
        }
    }
}

I'll save this file as parameters.json.

Now I can pass this parameters file to the New-AzResourceGroupDeployment cmdlet with the other required parameters specifying the name of the deployment, the resource group to deploy the resources to, the path to the ARM template, and finally the path to the parameter file as represented by TemplateParameterFile.

$parameters = @{
    'Name' = 'ContosoWebAppDeployment'
    'ResourceGroupName' = 'ContosoWebApp'
    'TemplateFile'      = 'C:\\armtemplate.json'
    'TemplateParameterFile' = 'C:\\parameters.json'
    'Verbose' = $true
}

New-AzResourceGroupDeployment @parameters

This command should then invoke the deployment, and since we're using the Verbose parameter, we'll get information as the deployment happens.

Using a Parameter Object
Similar to using the parameters file, you can also use a hashtable called a parameter object to pass in parameter values. Instead of defining JSON in a file, you can build a PowerShell hashtable. The only difference in deploying a parameterized ARM template with a parameter object rather than a file is a single parameter, as you can see below.

$paramObject = @{
    'webAppName' = 'AdbPluralsightWebApp'
    'sqlDbName'  = 'webappdb'
}
$parameters = @{
    'Name'                  = 'ContosoWebAppDeployment'
    'ResourceGroupName'     = 'ContosoWebApp'
    'TemplateFile'          = 'C:\\armtemplate.json'
    'TemplateParameterObject'    = $paramObject
    'Verbose'               = $true
}

New-AzResourceGroupDeployment @parameters

To sum up, building ARM templates with parameters allows those deploying Azure resources to reuse ARM templates for different purposes. Building parameters to templates prevents having to create multiple templates for small differences.

PowerShell is a great way to deploy your parameterized templates using the Azure PowerShell module and the New-AzResourceGroupDeployment cmdlet.