Rediger

Del via

Deploy Bicep files with Azure PowerShell

  • Artikkel

This article explains how to use Azure PowerShell with Bicep files to deploy your resources to Azure. If you aren't familiar with the deploying and managing your Azure solutions, see What is Bicep?.

Prerequisites

You need a Bicep file to deploy, and the file must be local. You also need Azure PowerShell and to be connected to Azure:

If you don't have PowerShell installed, you can use Azure Cloud Shell. For more information, see Deploy Bicep files with Azure Cloud Shell.

Required permissions

To deploy a Bicep file or ARM template, you need write access on the resources you're deploying and access to all operations on the Microsoft.Resources/deployments resource type. For example, to deploy a virtual machine, you need Microsoft.Compute/virtualMachines/write and Microsoft.Resources/deployments/* permissions. The what-if operation has the same permission requirements.

For a list of roles and permissions, see Azure built-in roles.

Deployment scope

You can target your deployment to a resource group, subscription, management group, or tenant. Depending on the scope of the deployment, you use different commands, and the user deploying the Bicep file must have the required permissions to create resources for every scope.

Deploy local Bicep file

This section describes how to deploy a local Bicep file. You can deploy a Bicep file from your local machine or an external one.

If you're deploying to a resource group that doesn't exist, create the resource group. The name of the resource group can only include alphanumeric characters, periods, underscores, hyphens, and parenthesis. It can be up to 90 characters and can't end in a period.

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

To deploy a local Bicep file, use the -TemplateFile switch in the deployment command:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile <path-to-bicep>

The deployment can take several minutes to complete.

Deploy remote Bicep file

Azure PowerShell doesn't currently support deploying remote Bicep files. You can use the Bicep CLI to build the Bicep file to a JSON template and then load the JSON file to a remote location. For more information, see Deploy remote template.

Parameters

To pass parameter values, you can use either inline parameters or a parameters file. The parameters file can be either a Bicep parameters file or a JSON parameters file.

Inline parameters

To pass inline parameters, provide the names of the parameter with the New-AzResourceGroupDeployment command. For example, to pass a string and array to a Bicep file, use:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -exampleString "inline string" `
  -exampleArray $arrayParam

You can use the TemplateParameterObject parameter to pass through a hashtable that contains the parameters for the template:

$params = @{
  exampleString = "inline string"
  exampleArray = "value1", "value2"
}

New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -TemplateParameterObject $params

You can also get the contents of file and provide that content as an inline parameter:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -exampleString $(Get-Content -Path c:\MyTemplates\stringcontent.txt -Raw) `
  -exampleArray $arrayParam

Getting a parameter value from a file is helpful when you need to provide configuration values. For example, you can provide cloud-init values for a Linux virtual machine.

If you need to pass in an array of objects, create hash tables in Azure PowerShell and add them to an array. Pass that array as a parameter during deployment:

$hash1 = @{ Name = "firstSubnet"; AddressPrefix = "10.0.0.0/24"}
$hash2 = @{ Name = "secondSubnet"; AddressPrefix = "10.0.1.0/24"}
$subnetArray = $hash1, $hash2
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -exampleArray $subnetArray

Bicep parameters files

Rather than passing parameters as inline values in your script, you might find it easier to use a Bicep parameters file or a JSON parameters file that contains the parameter values. The Bicep parameters file must be a local file, while the JSON template file can be located somewhere online. For more information about parameters files, see Create parameters files for Bicep deployment.

You can use a Bicep parameters file to deploy a Bicep file with Azure PowerShell version 10.4.0 or later and Bicep CLI version 0.22.X or later. With the using statement within the Bicep parameters file, there's no need to provide the -TemplateFile switch when specifying a Bicep parameters file for the -TemplateParameterFile switch.

The following example shows a parameters file named storage.bicepparam. The file is in the same directory where the command runs:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateParameterFile storage.bicepparam

JSON parameters files

The JSON parameters file can local or an external file with an accessible URI.

To pass a local parameters file, use the TemplateParameterFile switch with a JSON parameters file:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\BicepFiles\storage.bicep `
  -TemplateParameterFile c:\BicepFiles\storage.parameters.json

To pass an external parameters file, use the TemplateParameterUri parameter:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\BicepFiles\storage.bicep `
  -TemplateParameterUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.parameters.json

Since the TemplateParameterUri parameter only supports JSON parameters files, it doesn't support .bicepparam files.

You can use inline parameters and a location parameters file in the same deployment operation. For more information, see Parameter precedence.

Preview changes

Before deploying your Bicep file, you can preview the changes the Bicep file will make to your environment. Use the what-if operation to verify that the Bicep file makes the changes that you expect. What-if also validates the Bicep file for errors.

Deploy template specs

Azure PowerShell doesn't currently provide Bicep files to help create template specs. However, you can create a Bicep file with the Microsoft.Resources/templateSpecs resource to deploy a template spec. The Create template spec sample shows how to create a template spec in a Bicep file. You can also build your Bicep file to JSON by using the Bicep CLI and then a JSON template to create a template spec.

Deployment name

When deploying a Bicep file, you can give the deployment a name. This name can help you retrieve the deployment from the deployment history. If you don't provide a name for the deployment, its name becomes the name of the Bicep file. For example, if you deploy a Bicep file named main.bicep and don't specify a deployment name, the deployment is named main.

Every time you run a deployment, an entry is added to the resource group's deployment history with the deployment name. If you run another deployment and give it the same name, the earlier entry is replaced with the current deployment. If you want to maintain unique entries in the deployment history, give each deployment a unique name.

To create a unique name, you can assign a random number:

$suffix = Get-Random -Maximum 1000
$deploymentName = "ExampleDeployment" + $suffix

Or, add a date value:

$today=Get-Date -Format "MM-dd-yyyy"
$deploymentName="ExampleDeployment"+"$today"

If you run concurrent deployments to the same resource group with the same deployment name, only the last deployment is completed. Any deployments with the same name that haven't finished are replaced by the last deployment. For example, if you run a deployment named newStorage that deploys a storage account named storage1 and run another deployment named newStorage that deploys a storage account named storage2 at the same time, you deploy only one storage account. The resulting storage account is named storage2.

However, if you run a deployment named newStorage that deploys a storage account named storage1 and immediately run another deployment named newStorage that deploys a storage account named storage2 after the first deployment finishes, then you have two storage accounts. One is named storage1, and the other is named storage2. But, you only have one entry in the deployment history.

When you specify a unique name for each deployment, you can run them concurrently without conflict. If you run a deployment named newStorage1 that deploys a storage account named storage1 and run another deployment named newStorage2 that deploys a storage account named storage2 at the same time, then you have two storage accounts and two entries in the deployment history.

To avoid conflicts with concurrent deployments and to ensure unique entries in the deployment history, give each deployment a unique name.

Next steps

To learn how to define parameters in your file, see Understand the structure and syntax of Bicep files.