Az.DevOps.Blueprint

Introduction

This Azure DevOps Project contains information for the PowerShell Module Az.DevOps.Blueprint which has been designed to use in Azure DevOps to release a Blueprint into Management Groups and/or Subscriptions via a Pipeline.

Documentation of the cmdlets can be found in the Project Wiki.

Pipeline Status

You can review the status of every stage of the pipeline below.

Stage	Status
Build
Publish to PowerShell Gallery

Requirements

• Access to Azure and Azure DevOps
• A Service Connection to Azure with the Service Principal requiring the minimum of Owner for a Management Group to Create, Publish and Assign the Blueprint.
• A Self-hosted or Hosted Azure DevOps Agent with:
  • Az and Az.Blueprint Modules.
  • Azure PowerShell Task Version 5.0 with PowerShell Core enabled

Installation

Install this module from the PowerShell Gallery

Module Dependencies

• Az.Blueprint (0.2.13)

How Does It Work?

The PowerShell Module Az.DevOps.Blueprint can:

• Analyse a Blueprint for Resource Groups, Parameters and Secure Parameters that require values
• Analyse a Blueprint for Resource Groups, Parameters and Secure Parameters that do not require values
• Create Azure DevOps Variable Groups and Variables for Resource Groups, Parameters and Secure Parameters found in a Blueprint
• Match Blueprint Resource Groups, Parameters and Secure Parameters with Azure DevOps Variables When Assigning a Blueprint in a Pipeline
• Removes Blueprint Assignment

Blueprint Parameters

There are three types of Parameters:

1. Resource Groups
2. Parameters (Top level Blueprint Parameters or Parameters for Artifacts)
3. Secure Parameters (ResourceId for a Key Vault and secret name)

NOTE:
Secure Parameters must have a ResourceId of Key Vault and name of a secret.
The Reference is either an existing Key Vault and secret or a Key Vault and Secret that will be created by the Blueprint

The Parameters and Secure Parameters of a Blueprint, follow a pattern where the first part of the parameter matches a Blueprint artifact. For example, a parameter for the keyvault artifact looks like the following:

keyvault_ad-domain-admin-user-password

All other Parameters are Top-level Blueprint Parameters.

To determine what Blueprint parameters are required, execute the following in Azure DevOps or Locally against the exported version of the Blueprint:

In a PowerShell Task in Azure DevOps:

Get-AzDevOpsBlueprintParameters `
    -InputPath '$(env:BUILD_SOURCESDIRECTORY)\myRepo\Blueprints\Small_ISO27001_Shared-Services' `
    -DevOpsUri $env:SYSTEM_TEAMFOUNDTIONCOLLECTIONURI `
    -DevOpsProject $env:SYSTEM_TEAMPROJECT `
    -DevOpsPAT $env:PAT

NOTE:
Use the Predefined Variables in Azure DevOps for the DevOpsUri, DevOpsProject and DevOpsPAT Parameters
REMEMBER: Pass the the Predefined Variable System.AccessToken as a Secure Variable in the PowerShell Task
See PowerShell task for more information

In PowerShell locally:

Get-AzDevOpsBlueprintParameters `
    -InputPath 'C:\Repos\myRepo\Blueprints\Small_ISO27001_Shared-Services' `
    -DevOpsUri "https://dev.azure.com/myOrg/" `
    -DevOpsProject "myProject" `
    -DevOpsPAT "mznfvtttfntej3abrdjfcpwh2fp33elyei4i3oykj2ww3vgoan2az"

The following Variable Groups will be created in a specified Azure DevOps project:

1. BLUEPRINT_Resource_Groups - Contains the variables for all Resource Group Parameters for the Blueprint
2. BLUEPRINT_Parameters_Required - Contains the variables for all Parameters in the Blueprint that require values. These variables must be updated with a value. The value field of the variable contains guidance on format of the value required.
3. BLUEPRINT_Parameters_Not_Required - Contains the variables for all Parameters in the Blueprint that have a default value assigned and don't require values to be configured.

You can use these Variable Groups in your Pipeline or Create new Variable Groups to suit your Requirements

Updating the values of the Variables

Sometimes there might be a Blueprint parameter that requires an empty array or object. Azure DevOps Variables can't (I haven't found a way) contain an empty array, object etc. By determining the type of Blueprint parameters, the Find-AzDevOpsBlueprintParameter command-let will configure the appropriate empty value type. For example:

• A Blueprint parameter needs to have an input, but an empty array
• The Azure DevOps Variable must be configured with a value of a space e.g. " " (excluding the quotes)
• Find-AzDevOpsBlueprintParameter will find the Blueprint parameter and create a temporary variable containing the new value.

If a Blueprint parameter requires a secret from a Key Vault either existing or built as part the Blueprint, the Azure DevOps Variable requires a particular format to ensure the Blueprint assignment is successfully.

The Azure DevOps Variable must have the ResourceId reference to the Key Vault and the Secret Name. These must be separated by a "," (excluding the quotes). For example:

/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx/resourceGroups/rg-keyvault/providers/Microsoft.KeyVault/vaults/mykeyvault,mysecretname

Blueprint Export, Import, and Publish

This Module complements the PowerShell Module Az.Blueprint developed by Microsoft. The Az.Blueprint module is used natively to manage the Export, Import and Publish of a Blueprint. See Az.Blueprint for more information.

Blueprint Assignment

This Module also utilises some information from Using blueprints with Azure DevOps pipelines which helped create the Az.DevOps.Blueprint Module that implements a Blueprint via an Azure DevOps pipeline.

Thank you and have fun!

Versioning

We use Azure DevOps for version control.

Authors

Paul Towler - Initial work - 30/04/2019
Paul Towler - Release v1.1.0 - 1/05/2020

See also the list of contributors who participated in this project.