Edit

Share via

Understand the lifecycle of an Azure Blueprint

  • Article

Important

On July 11, 2026, Blueprints (Preview) will be deprecated. Migrate your existing blueprint definitions and assignments to Template Specs and Deployment Stacks. Blueprint artifacts are to be converted to ARM JSON templates or Bicep files used to define deployment stacks. To learn how to author an artifact as an ARM resource, see:

Like many resources within Azure, a blueprint in Azure Blueprints has a typical and natural lifecycle. They're created, deployed, and finally deleted when no longer needed or relevant. Azure Blueprints supports standard lifecycle operations. It then builds upon them to provide additional levels of status that support common continuous integration and continuous deployment pipelines for organizations that manage their Infrastructure as Code - a key element in DevOps.

To fully understand a blueprint and the stages, we'll cover a standard lifecycle:

  • Creating and editing a blueprint
  • Publishing the blueprint
  • Creating and editing a new version of the blueprint
  • Publishing a new version of the blueprint
  • Deleting a specific version of the blueprint
  • Deleting the blueprint

Creating and editing a blueprint

To create a blueprint, add artifacts to it, save the definition to the management group or subscription scope, and provide a unique name version. The blueprint is now in a Draft mode and can't yet be assigned. While in the Draft mode, it can continue to be updated and changed.

A never published blueprint in Draft mode displays a different icon on the Blueprint Definitions page than ones that have been Published. The Latest Version is displayed as Draft for these never published blueprints.

Create and edit a blueprint with the Azure portal or REST API.

Publishing a blueprint

Once all planned changes have been made to a blueprint in Draft mode, it can be Published and made available for assignment. The Published version of the blueprint can't be altered. Once Published, the blueprint displays with a different icon than Draft blueprints and displays the provided version number in the Latest Version column.

Publish a blueprint with the Azure portal or REST API.

Creating and editing a new version of the blueprint

A Published version of a blueprint can't be altered. However, a new version of the blueprint can be added to the existing blueprint and modified as needed. Make changes to an existing blueprint by editing it. When the new changes are saved, the blueprint now has Unpublished Changes. These changes are a new Draft version of the blueprint.

Edit a blueprint with the Azure portal.

Publishing a new version of the blueprint

Each edited version of a blueprint must be Published before it can be assigned. When Unpublished Changes have been made to a blueprint but not Published, the Publish Blueprint button is available on the edit blueprint page. If the button isn't visible, the blueprint has already been Published and has no Unpublished Changes.

Note

A single blueprint can have multiple Published versions that can each be assigned to subscriptions.

To publish a blueprint with Unpublished Changes, use the same steps for publishing a new blueprint.

Deleting a specific version of the blueprint

Each version of a blueprint is a unique object and can be individually Published. As such, each version of a blueprint can also be deleted. Deleting a version of a blueprint doesn't have any impact on other versions of that blueprint.

Note

It's not possible to delete a blueprint that has active assignments. Delete the assignments first and then delete the version you wish to remove.

  1. Select All services in the left pane. Search for and select Blueprints.

  2. Select Blueprint definitions from the page on the left and use the filter options to locate the blueprint you want to delete a version of. Select it to open the edit page.

  3. Select the Published versions tab and locate the version you wish to delete.

  4. Right-click on the version to delete and select Delete this version.

Deleting the blueprint

The core blueprint can also be deleted. Deleting the core blueprint also deletes any blueprint versions of that blueprint, including both Draft and Published blueprints. As with deleting a version of a blueprint, deleting the core blueprint doesn't remove the existing assignments of any of the blueprint versions.

Note

It's not possible to delete a blueprint that has active assignments. Delete the assignments first and then delete the version you wish to remove.

Delete a blueprint with the Azure portal or REST API.

Assignments

There's several points during the lifecycle a blueprint can be assigned to a subscription. When the mode of a version of the blueprint is Published, then that version can be assigned to a subscription. This lifecycle enables versions of a blueprint to be used and actively assigned while a newer version is being developed.

As versions of blueprints are assigned, it's important to understand where they're assigned and with what parameters they've been assigned with. The parameters can either be static or dynamic. To learn more, see static and dynamic parameters.

Updating assignments

When a blueprint is assigned, the assignment can be updated. There are several reasons for updating an existing assignment, including:

To learn how, see update existing assignments.

Unassigning assignments

If the blueprint is no longer needed, it can be unassigned from the management group or subscription. During blueprint unassignment, the following occurs:

  • Removal of blueprint resource locking
  • Deletion of the blueprint assignment object
  • (Conditional) If a system-assigned managed identity was used, it's also deleted

Note

All resources deployed by the blueprint assignment remain in place, but are no longer protected by Azure Blueprints.

Next steps