What is Azure Blueprints?

Just as a blueprint allows an engineer or an architect to sketch a project's design parameters, Azure Blueprints enables cloud architects and central information technology groups to define a repeatable set of Azure resources that implements and adheres to an organization's standards, patterns, and requirements. Azure Blueprints makes it possible for development teams to rapidly build and stand up new environments with trust they're building within organizational compliance with a set of built-in components -- such as networking -- to speed up development and delivery.

Blueprints are a declarative way to orchestrate the deployment of various resource templates and other artifacts such as:

  • Role Assignments
  • Policy Assignments
  • Azure Resource Manager templates
  • Resource Groups

The Azure Blueprints service is backed by the globally distributed Azure Cosmos DB. Blueprint objects are replicated to multiple Azure regions. This replication provides low latency, high availability, and consistent access to your blueprint objects, regardless of which region Blueprints deploys your resources to.

How it's different from Resource Manager templates

The service is designed to help with environment setup. This setup often consists of a set of resource groups, policies, role assignments, and Resource Manager template deployments. A blueprint is a package to bring each of these artifact types together and allow you to compose and version that package -- including through a CI/CD pipeline. Ultimately, each is assigned to a subscription in a single operation that can be audited and tracked.

Nearly everything that you want to include for deployment in Blueprints can be accomplished with a Resource Manager template. However, a Resource Manager template is a document that doesn't exist natively in Azure – each is stored either locally or in source control. The template gets used for deployments of one or more Azure resources, but once those resources deploy there's no active connection or relationship to the template.

With Blueprints, the relationship between the blueprint definition (what should be deployed) and the blueprint assignment (what was deployed) is preserved. This connection supports improved tracking and auditing of deployments. Blueprints can also upgrade several subscriptions at once that are governed by the same blueprint.

There's no need to choose between a Resource Manager template and a blueprint. Each blueprint can consist of zero or more Resource Manager template artifacts. This support means that previous efforts to develop and maintain a library of Resource Manager templates are reusable in Blueprints.

How it's different from Azure Policy

A blueprint is a package or container for composing focus-specific sets of standards, patterns, and requirements related to the implementation of Azure cloud services, security, and design that can be reused to maintain consistency and compliance.

A policy is a default allow and explicit deny system focused on resource properties during deployment and for already existing resources. It supports cloud governance by validating that resources within a subscription adhere to requirements and standards.

Including a policy in a blueprint enables the creation of the right pattern or design during assignment of the blueprint. The policy inclusion makes sure that only approved or expected changes can be made to the environment to protect ongoing compliance to the intent of the blueprint.

A policy can be included as one of many artifacts in a blueprints definition. Blueprints also support using parameters with policies and initiatives.

Blueprint definition

A blueprint is made up of artifacts. Blueprints currently support the following resources as artifacts:

Resource Hierarchy options Description
Resource Groups Subscription Create a new resource group for use by other artifacts within the blueprint. These placeholder resource groups enable you to organize resources exactly the way you want them structured and provides a scope limiter for included policy and role assignment artifacts and Azure Resource Manager templates.
Azure Resource Manager template Subscription, Resource Group Templates are used to compose complex environments. Example environments: a SharePoint farm, Azure Automation State Configuration, or a Log Analytics workspace.
Policy Assignment Subscription, Resource Group Allows assignment of a policy or initiative to the subscription the blueprint is assigned to. The policy or initiative must be within the scope of the blueprint (in the blueprint management group or below). If the policy or initiative has parameters, these parameters are assigned at creation of the blueprint or during blueprint assignment.
Role Assignment Subscription, Resource Group Add an existing user or group to a built-in role to make sure the right people always have the right access to your resources. Role assignments can be defined for the entire subscription or nested to a specific resource group included in the blueprint.

Blueprints and management groups

When creating a blueprint definition, you'll define where the blueprint is saved. Currently, blueprints can only be saved to a management group that you have Contributor access to. The blueprint is available to assign to any child subscription of that management group.

Important

If you don't have access to any management groups or any management groups configured, loading the list of blueprint definitions shows that none are available and clicking on Scope opens a window with a warning about retrieving management groups. To resolve this, ensure a subscription you have appropriate access to is part of a management group.

Blueprint parameters

Blueprints can pass parameters to either a policy/initiative or an Azure Resource Manager template. When adding either artifact to a blueprint, the author decides to provide a defined value for each blueprint assignment or to allow each blueprint assignment to provide a value at assignment time. This flexibility provides the option to define a pre-determined value for all uses of the blueprint or to enable that decision to be made at the time of assignment.

Note

A blueprint can have its own parameters, but these can currently only be created if a blueprint is generated from REST API instead of through the Portal.

For more information, see blueprint parameters.

Blueprint publishing

When a blueprint is first created, it's considered to be in Draft mode. When it's ready to be assigned, it needs to be Published. Publishing requires defining a Version string (letters, numbers, and hyphens with a max length of 20 characters) along with optional Change notes. The Version differentiates it from future changes to the same blueprint and allows each version to be assigned. This versioning also means different Versions of the same blueprint can be assigned to the same subscription. When additional changes are made to the blueprint, the Published Version still exists, as do the Unpublished changes. Once the changes are complete, the updated blueprint is Published with a new and unique Version and can now also be assigned.

Blueprint assignment

Each Published Version of a blueprint can be assigned to an existing subscription. In the portal, the blueprint defaults the Version to the one Published most recently. If there are artifact parameters (or blueprint parameters), then the parameters are defined during the assignment process.

Permissions in Azure Blueprints

To use blueprints, you must be granted permissions through Role-based access control (RBAC). To create blueprints, your account needs the following permissions:

  • Microsoft.Blueprint/blueprints/write - Create a blueprint definition
  • Microsoft.Blueprint/blueprints/artifacts/write - Create artifacts on a blueprint definition
  • Microsoft.Blueprint/blueprints/versions/write - Publish a blueprint

To delete blueprints, your account needs the following permissions:

  • Microsoft.Blueprint/blueprints/delete
  • Microsoft.Blueprint/blueprints/artifacts/delete
  • Microsoft.Blueprint/blueprints/versions/delete

Note

As blueprint definitions are created at a management group, the blueprint definition permissions must be granted on a management group scope or be inherited onto a management group scope.

To assign or unassign a blueprint, your account needs the following permissions:

  • Microsoft.Blueprint/blueprintAssignments/write - Assign a blueprint
  • Microsoft.Blueprint/blueprintAssignments/delete - Unassign a blueprint

Note

As blueprint assignments are created on a subscription, the blueprint assign and unassign permissions must be granted on a subscription scope or be inherited onto a subscription scope.

All of the above permissions are included in the Owner role. The Contributor role has create blueprint and delete blueprint permissions, but does not have blueprint assignment permissions. If these built-in roles don't fit your security needs, consider creating a custom role.

Note

The service principal for Azure Blueprint requires the Owner role on the assigned subscription in order to enable deployment. If using the portal, this role is automatically granted and revoked for the deployment. If using the REST API, this role must be manually granted, but is still automatically revoked after the deployment completes.

Next steps