Managing Azure Blueprints with PowerShell

Azure Blueprints provide a "one-stop shop" for Azure governance. By implementing JSON templates and a controlled, unified workflow, Azure administrators can define, deploy, enforce, and maintain standardized Azure environments.

For today's tutorial I need to assume you already know what Azure Blueprints are and how to create them in the Azure portal. If you need remedial assistance, I'll point you to the always-great Azure documentation.

My goal today is to teach you how to manage the Azure Blueprints service by using Azure PowerShell. Specifically, by the end of this article, you will know how to:

• Install the Azure Blueprint PowerShell commands
• Download an Azure Blueprint definition
• Modify Azure Blueprint source code
• Assign and publish Azure Blueprints programmatically

Let's get to work!

Setting Up Your Environment

I assume you've already installed the Azure PowerShell modules and are working from an elevated PowerShell console session. Your first order of business is to install the Azure Blueprints module from the PowerShell Gallery and then update your local help:

Install-Module -Name Az.Blueprint -Verbose ; Update-Help -Force -ErrorAction SilentlyContinue

As of this writing in October 2019, Azure Blueprints is in public preview status. Once the product reaches general availability (GA) status, I'm sure the Az.Blueprint module will be bundled with the rest of the Azure PowerShell modules.

Note: Generally speaking, Microsoft offers no service-level agreement (SLA) or support for preview features. You should use Azure Blueprints only in test/development environments until it reaches GA.

You'll also want to install Visual Studio Code and load up some helpful extensions:

• PowerShell
• Azure Resource Manager Tools
• Azure Resource Manager Snippets
• Azure Account
• ARM Template Viewer
• ARM Template Helper

Take a look at Figure 1, which shows an Azure Blueprint I created called ipswitch-std-vnet.

Figure 1. A published Azure Blueprint.

My ipswitch-std-vnet project combines all supported Azure Blueprint artifacts to define a standardized Azure virtual network (VNet) deployment. Those artifacts include:

• resource group
• Azure Resource Manager (ARM) template
• Role-based access control (RBAC) assignments
• Azure Policy definition

Viewing Azure Blueprint Source Code

In Figure 1 you should take note of the management group location ID and version fields. We need these to create a reference to the ipswitch-std-vnet blueprint:

$b = Get-AzBlueprint -Name 'ipswitch-std-vnet' -ManagementGroupId 'test-mg' -Version 1.0

Next, we'll pull down the blueprint's source code by invoking the Export-AzBlueprintWithArtifact cmdlet:

Export-AzBlueprintWithArtifact -Blueprint $b -OutputPath 'D:\blueprints'

In Figure 2 you can see what my ipswitch-std-vnet blueprint looks like on my local system. I was bummed that my artifact JSON files didn't have friendly names.

Figure 2. Azure Blueprint source code.

The blueprint definition file must be named blueprint.json. However, we can rename the artifacts. I actually renamed the artifacts files in my project to:

• json
• rbac-owner.json
• rbac-contributor.json

You'll note that there is nothing mystical, magical, or necessarily unfamiliar about any of these JSON files if you've worked with ARM templates in the past. In keeping with the "infrastructure as code" philosophy, I think the idea here is you and your team will maintain these blueprint definitions and artifact files in source code control, and then use a continuous integration/continuous deployment (CI/CD) pipeline to manage Azure Blueprint publication and assignment.

Creating a New Azure Blueprint Programmatically

The Az.Blueprint cmdlets cover the Azure Blueprints lifecycle pretty well. Recall that your blueprint is worthless without the blueprint.json definition file.

Assuming you have one of those (feel free to edit the one you downloaded a moment ago), we can capture a reference to a new blueprint like this:

$blueprint = New-AzBlueprint -Name 'ipswitch-std-vnet-new' -BlueprintFile .\blueprint.json

After modifying (or creating) artifact JSON files, we can then programmatically define them like so:

New-AzBlueprintArtifact -Blueprint $blueprint -Name 'rbac-owner-new' -ArtifactFile .\artifacts\rbac-owner-new.json

New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policy-new' -ArtifactFile .\artifacts\policy-new.json

The syntax is little different when creating an ARM template artifact:

New-AzBlueprintArtifact -Blueprint $blueprint -Type TemplateArtifact -Name 'std-vnet-subnet' -TemplateFile .\artifacts\std-vnet-subnet.json -ResourceGroupName 'myRG'

Now, please understand you don't have to use New-AzBlueprintArtifact unless you actually need to push individual artifacts to Azure. Thanks to Azure Blueprints Program Manager Alex Frankel for teaching me about the Import-AzBlueprintWithArtifact cmdlet, with which you can push the entire blueprint project (with artifacts) to Azure:

Import-AzBlueprintWithArtifact -Name 'ipswitch-blueprint' -SubscriptionId 00000000-1111-0000-1111-000000000000 -InputPath D:\Blueprints\ipswitch-blueprint

Note that in the preceding example I'm pushing the blueprint definition to the subscription rather than the management group scope.

Recall that Azure Blueprints follow a draft > publish > assign workflow. Let's publish version 1.0 of this new blueprint:

Publish-AzBlueprint -Blueprint $blueprint -Version '1.0'

Assigning an Azure Blueprint by using PowerShell can get a bit tricky if you authored the blueprint such that you need to provide parameter assignments rather than coding them statically in your blueprint documents.

If so, you need to create an assignment JSON file that provides the parameter names and values as well as the deployment location. Next, we do this:

New-AzBlueprintAssignment -Blueprint $blueprint -Name 'std-vnet-subnet-assignment' -AssignmentFile .\assign.json

Finally, you can push a local blueprint definition to your Azure subscription in draft mode (this is a good tip):

Import-AzBlueprintWithArtifact -Name 'test-blueprint' -ManagementGroupId 'myMG' -InputPath  '.\blueprints\test-blueprint'

Wrap-up

There you have it! Microsoft has clearly put much thought and effort behind Azure Blueprints. I have a feeling that we may see a trend towards managing all your Azure deployments through this service.

Check out the Azure team's wonderful Managing Blueprints as Code article for some great guidance in this regard.