Creating images with the Azure Image Builder
This sections gives you an overview on how to use the Azure Image Builder pipeline to deploy the required infrastructure for, and build images with the Azure Image Builder.
The image creation uses several components:
| Resource | Description | |
|---|---|---|
 |
Resource Group | The resource group hosting our image resources |
 |
Storage Account | The storage account that hosts our image customization scripts used by the Azure Image Building when executing the image template |
 |
User-Assigned Managed Identity | Azure Active Directory feature that eliminates the need for credentials in code, rotates credentials automatically, and reduces identity maintenance. In the context of the imaging solution, the managed identity (MSI) is used by the Image Builder Service. It requires contributor permissions on the subscription to be able to bake the image. |
 |
Azure Compute Gallery | Azure service that helps to build structure and organization for managed images. Provides global replication, versioning, grouping, sharing across subscriptions and scaling. The plain resource in itself is like an empty container. |
 |
Azure Compute Gallery Image | Created within a gallery and contains information about the image and requirements for using it internally. This includes metadata like whether the image is Windows or Linux, release notes and recommended compute resources. Like the image gallery itself it acts like a container for the actual images. |
 |
Image Template | A standard Azure Image Builder template that defines the parameters for building a custom image with AIB. The parameters include image source (Marketplace, custom image, etc.), customization options (i.e., Updates, scripts, restarts), and distribution (i.e., managed image, Azure Compute Gallery). The template is not an actual resource. Instead, when an image template is created, Azure stores all the metadata of the referenced Azure Compute Gallery Image alongside other image backing instructions as a hidden resource in a temporary resource group. This resource group is removed once an image creation is triggered based on the template. |
 |
Image Version | An image version is what you use to create a VM when using a gallery. You can have multiple versions of an image as needed for your environment. This value cannot be influenced. E.g. 0.24322.55884
|
NOTE: The solution was build with multiple environments and staging in mind. To this end, pipeline variable files contain one variable per suggested environment (for example
vmImage_sbx&vmImage_dev) which is automatically referenced by the corresponding stage. For details on how to working with and configure these variables, please refer to this section.For the rest of the documentation we will ignore these environments and just refer to the simple variable or parameter file to avoid confusion around which file we refer to. All concepts apply to all files, no matter the environment/stage.
This section explains how to deploy the image pipeline solution and use it on a continuous basis.
To deploy and use the solution you have to perform two fundamental steps:
For this step you have to update three files to your needs:
.azuredevops\azureDevOpsScaleSet\variables.ymlconstructs\azureImageBuilder\Parameters\imageInfra.parameters.jsonconstructs\azureImageBuilder\Parameters\imageTemplate.parameters.json
The first file, variables.yml, is a pipeline variable file. You should update at least the values
-
vmImage: Set this to for exampleubuntu-latestto leverage Microsoft-hosted agents. Leave it empty ('') if you use self-hosted agents. Do not remove it. -
poolName: Set this to for examplemyHostPoolto leverage your self-hosted agent pool. Leave it empty ('') if you use Microsoft-hosted agents. Do not remove it. -
serviceConnection: This refers to your Azure DevOps service connection you use for your deployments. It should point into the subscription you want to deploy into. -
location: The location to store deployment metadata in. This variable is also used as a default location to deploy into, if no location is provided in the parameter files.
Next, we have two parameter files, imageInfra.parameters.json & imageTemplate.parameters.json that corresponding to the two phases in the deployment: Deploy all infrastructure components & build the image.
2. Register the pipeline
The creation of the image alongside its resources is handled by the pipeline.image.yml pipeline. Given the proper configuration, it creates all required resources in the designated environment and optionally triggers the image creation right after.
So let's take a look at the different configuration options when running the pipeline:
-
'Only removal' selection: Have the pipeline only cleanup resources, if any. This includes all Image Templates that match the naming schema defined in the parameter file - as long es their built is not in state
running. -
'Environment to deploy to' selection: The environment you want to start to deploy into. If you select for example
SBX(sandbox), the pipeline would, upon triggering, start in theSBXstage and continue withDEV(development) if it succeeds. If you instead selectDEV, it would start from this stage directly, and so one. The stages are implemented by default and should be configured with an approver. If you don't want to leverage environments/stages, you can simply remove the excess ones and any reference to them. -
'Scope of the deployment' selection: Select whether you want to deploy all resources, all resources without triggering the image build, or only the image build. When triggering the pipeline for the first time, set the
Scope of the deploymentto deploy all resources.If the script that is used during the image backing (i.e is referenced in the image template parameters) has changed, make sure you always also include the storage step in the pipeline run (
Only Storage & Image) to make sure the updated file is uploaded to the storage account. -
'Wait for image build' switch: Specify whether to wait for the image build process during the pipeline run or not. The process itself is triggered asynchronously. If not selected, you can use the 'Wait-ForImageBuild' script to check the status yourself (located at:
PipelineAgentsScaleSet/scripts/image/Wait-ForImageBuild.ps1). To trigger it you will need the image template name (output value of the image template deployment) and the resource group of your image template deployment. -
'Pre-remove Image Template Resource Group' switch: Specify whether to remove previous image resources. This includes all Image Templates that match the naming schema defined in the parameter file - as long es their built is not in state
running.
For the first deployment make sure all parameters in the parameter file for the target location (e.g. sbx) are properly configured and available in the 'Parameters' folder. The pipeline decides which parameter files to choose based on the environment and uses it as a suffix to find the correct file. For example, the name sbx.image.parameters.json implies a the SBX environment while the DEV deployment would search for a file dev.image.parameters.windows.json in the same folder.
When triggering the pipeline first the first time for an environment, make sure you either select 'All' or 'Only Infrastructure' for the first run. In either case the pipeline will deploy all resources and scripts you will subsequently need to create the images. For any subsequent run, you can go with any option you need.
To update an image you first have to decide whether you want to build an image from the ground up (using e.g. a marketplace image as the basis) or build on an existing one. In either case you have to configure the image template parameter file in question with regards to the imageSource parameter.
To reference a marketplace image use the syntax:
@{
"imageSource": {
"value": {
"type": "PlatformImage",
"publisher": "MicrosoftWindowsDesktop",
"offer": "Windows-10",
"sku": "19h2-evd",
"version": "latest"
}
}
}To reference a custom image use the syntax (where the ID is the resourceId of the image version in the Azure Compute Gallery):
@{
"imageSource": {
"value": {
"type": "SharedImageVersion",
"imageVersionID": "/subscriptions/c64d2kd9-4679-45f5-b17a-e27b0214acp4d/resourceGroups/scale-set-rg/providers/Microsoft.Compute/galleries/mygallery/images/mydefinition/versions/0.24457.34028"
}
}
}The steps the Azure Image Builder performs on the image are defined by elements configured in the customizationSteps parameter of the image template parameter file. In our setup we reference one or multiple custom scripts that are uploaded by the pipeline to a storage account ahead of the image deployment.
The scripts are different for the type of OS and hence are also stored in two different folders in the PipelineAgentsScaleSet module:
- Windows:
PipelineAgentsScaleSet\Scripts\Uploads\windows - Linux:
PipelineAgentsScaleSet\Scripts\Uploads\linux
One of the main tasks perform in these scripts are the installation of the baseline modules and software we want to have installed on the image. Prime candidates are for example the Az-Modules.
| OS | Windows | Linux | ||
|---|---|---|---|---|
| Base Image | Windows-10 19h2-evd |
UbuntuServer 18.04-LTS |
||
| Software | Choco |
✔️ | ||
Azure-CLI |
✔️ | ✔️ | ||
PowerShell Core (7.*) |
✔️ | ✔️ | ||
.NET SDK |
✔️ | |||
.NET Runtime |
✔️ | |||
Nuget Package Provider |
✔️ | ✔️ (dotnet nuget) |
||
Terraform |
✔️ (latest) |
✔️ (0.12.30) |
||
azcopy |
✔️ (latest) |
✔️ (latest) |