| title | Configure images |
|---|---|
| description | Learn how to configure agent images for Managed DevOps Pools. |
| ms.date | 01/14/2026 |
| ms.topic | how-to |
Managed DevOps Pools provides you with several options for virtual machine (VM) images for running pipelines in your pool. You can create your pool by using selected marketplace VM images, use your own custom Azure Compute Gallery images, or use the same images as Azure Pipelines Microsoft-hosted agents.
Important
[!INCLUDE image-deprecation]
You can configure a pool with a single image or multiple images. When your pool has multiple images, your pipelines specify the image they want to run on by using aliases.
A default image is selected when you create a Managed DevOps Pool. You can keep the default choice, or change it during pool creation. To configure the image after pool creation, go to Settings > Pool. Select Add from Image Library, and then select one or more images for your pool.
:::image type="content" source="./media/configure-images/configure-pool-image.png" alt-text="Screenshot that shows how to configure an image.":::
You can configure images in the fabricProfile section of the Managed DevOps Pools resource properties.
The following example specifies three images. For more information on the schema for images, see the following sections in this article.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"resources": [
{
"name": "fabrikam-managed-pool",
"type": "microsoft.devopsinfrastructure/pools",
"apiVersion": "2025-09-20",
"location": "eastus",
"properties": {
...
"fabricProfile": {
...
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest",
"aliases": [
"ubuntu-24.04-gen2"
]
},
{
"wellKnownImageName": "windows-2022"
},
{
"wellKnownImageName": "ubuntu-22.04"
}
]
}
}
}
]
}Each image can have the following properties:
| Property | Description |
|---|---|
aliases |
An optional list of aliases. You can refer to the image by using the aliases instead of the full resource ID of the image. |
resourceID |
The resource ID of the image to use. Required when you use Azure Compute Gallery images or selected marketplace images. |
wellKnownImageName |
The alias of the Azure Pipelines image. Required when you use Azure Pipelines images. |
buffer |
When you enable standby agents, the buffer value designates which percentage of standby agents to allocate to this image. The total of all image buffer values must equal 100. |
The following example defines three images. Standby agents are enabled, and 100% of the standby agents are allocated to the windows-2022 image.
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest",
"aliases": [
"ubuntu-24.04-gen2"
],
"buffer": "0"
},
{
"buffer": "100",
"wellKnownImageName": "windows-2022"
},
{
"buffer": "0",
"wellKnownImageName": "ubuntu-22.04"
}
]You can configure images in the fabric-profile section of the Managed DevOps Pools resource properties.
az mdp pool create \
--fabric-profile fabric-profile.json
# other parameters omitted for space
The following example shows the images section of the fabric-profile.json file and specifies three images. For more information on the schema for images, see the following sections in this article.
{
"vmss": {
"sku": {...},
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest",
"aliases": [
"ubuntu-24.04-gen2"
],
"buffer": "0"
},
{
"buffer": "100",
"wellKnownImageName": "windows-2022"
},
{
"buffer": "0",
"wellKnownImageName": "ubuntu-22.04"
}
],
"osProfile": {...},
"storageProfile": {...}
}
}Each image can have the following properties:
| Property | Description |
|---|---|
aliases |
An optional list of aliases. You can refer to the image by using the aliases instead of the full resource ID of the image. |
resourceID |
The resource ID of the image to use. Required when you use Azure Compute Gallery images or selected marketplace images. |
wellKnownImageName |
The alias of the Azure Pipelines image. Required when you use Azure Pipelines images. |
buffer |
When you enable standby agents, the buffer value designates which percentage of standby agents to allocate to this image. The total of all image buffer values must equal 100. |
The following example defines three images. Standby agents are enabled and 100% of the standby agents are allocated to the windows-2022 image.
{
"vmss": {
"sku": {...},
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest",
"aliases": [
"ubuntu-24.04-gen2"
],
"buffer": "0"
},
{
"buffer": "100",
"wellKnownImageName": "windows-2022"
},
{
"buffer": "0",
"wellKnownImageName": "ubuntu-22.04"
}
],
"osProfile": {...},
"storageProfile": {...}
}
}You can configure images in the fabricProfile section of the Managed DevOps Pools resource properties.
The following example specifies three images. For more information on the schema for images, see the following sections in this article.
resource managedDevOpsPools 'Microsoft.DevOpsInfrastructure/pools@2025-09-20' = {
name: 'fabrikam-managed-pool'
location: 'eastus'
properties: {
...
fabricProfile: {
...
images: [
{
resourceId: '/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest'
aliases: [
'ubuntu-24.04-gen2'
]
}
{
wellKnownImageName: 'windows-2022'
}
{
wellKnownImageName: 'ubuntu-22.04'
}
]
}
}
}Each image can have the following properties:
| Property | Description |
|---|---|
aliases |
An optional list of aliases. You can refer to the image by using the aliases instead of the full resource ID of the image. |
resourceID |
The resource ID of the image to use. Required when you use Azure Compute Gallery images or selected marketplace images. |
wellKnownImageName |
The alias of the Azure Pipelines image. Required when you use Azure Pipelines images. |
buffer |
When you enable standby agents, the buffer value designates which percentage of standby agents to allocate to this image. The total of all image buffer values must equal 100. |
The following example defines three images. Standby agents are enabled and 100% of the standby agents are allocated to the windows-2022 image.
images: [
{
resourceId: '/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest'
aliases: [
'ubuntu-24.04-gen2'
]
buffer: 0
}
{
buffer: 100
wellKnownImageName: 'windows-2022'
}
{
buffer: 0
wellKnownImageName: 'ubuntu-22.04'
}
]If you select a single image, all pipelines in your pool run by using that image. If you select multiple images, you can specify the image to use on a per-pipeline basis. For more information, see Use multiple images per pool.
If you have multiple images in your pool, and don't use demands in your pipelines to designate an image, the pipelines run by using the first listed image in your pool. You can change the order of the images in your pool in the following two ways:
- Use templates: Change the order of the images in the
imageslist in thefabricProfilesection. - Use dragging: Order the images in the images list in the Azure portal.
You can select from the following types of images:
- Azure Pipelines images: Select from the same images that Microsoft-hosted agents use.
- Selected marketplace images: Select from a curated set of Microsoft-published marketplace VM images.
- Azure Compute Gallery images: Select from your own Azure Compute Gallery images. You must assign the Reader role to the
DevOpsInfrastructureservice principal for the Azure Compute Gallery images that you want to use. For more information, see Grant Reader role access to theDevOpsInfrastructureservice principal.
Managed DevOps Pools provides several preconfigured images that have the same software as selected Microsoft-hosted agents for Azure Pipelines.
The lifecycle of Azure Pipelines images offered in Managed DevOps Pools follows the lifecycle of the Microsoft-hosted agent images. If an image in Microsoft-hosted agents is deprecated, the corresponding Managed DevOps Pools image is also deprecated on a similar timeframe. The version of images available in Microsoft-hosted agents might be slightly different from the version of images available in Managed DevOps Pools for the same image type.
For more information on Managed DevOps Pools images lifecycle, see Image lifecycle.
When you specify an Azure Pipelines image by using the Azure portal, the latest version of the image is always used.
:::image type="content" source="./media/configure-images/image-library-azure-pipelines-images.png" alt-text="Screenshot that shows Azure Pipelines images.":::
To specify an Azure Pipelines image, provide the alias of the image by using the wellKnownImageName property. See a list of predefined aliases for Azure Pipelines images.
"images": [
{
"wellKnownImageName": "windows-2022"
}
]You can specify a version in your wellKnownImageName setting (for example "wellKnownImageName": "windows-2022/latest" or "wellKnownImageName": "windows-2022/20250427.1.0"). If you don't specify a version, latest is used.
To specify an Azure Pipelines image, provide the predefined alias of the image by using the wellKnownImageName property. See a list of predefined aliases for Azure Pipelines images.
"images": [
{
"wellKnownImageName": "windows-2022"
}
]You can specify a version in your wellKnownImageName setting (for example "wellKnownImageName": "windows-2022/latest" or "wellKnownImageName": "windows-2022/20250427.1.0"). If you don't specify a version, latest is used.
To specify an Azure Pipelines image, provide the alias of the image by using the wellKnownImageName property. See a list of predefined aliases for Azure Pipelines images.
images: [
{
wellKnownImageName: 'windows-2022'
}
]You can specify a version in your wellKnownImageName setting (for example wellKnownImageName: 'windows-2022/latest' or wellKnownImageName: 'windows-2022/20250427.1.0'). If you don't specify a version, latest is used.
Each image includes the following installed software:
| Image | Included software |
|---|---|
| Azure Pipelines - Windows Server 2025 | Included software |
| Azure Pipelines - Windows Server 2022 | Included software |
| Azure Pipelines - Ubuntu 24.04 | Included software |
| Azure Pipelines - Ubuntu 22.04 | Included software |
Important
[!INCLUDE image-deprecation]
Managed DevOps Pools provides a curated set of Microsoft-published marketplace VM images to use in your pools.
:::image type="content" source="./media/configure-images/image-library-marketplace-images.png" alt-text="Screenshot that shows selected marketplace images.":::
Choose Selected marketplace images. Select the desired image, and then select the desired version. To always use the latest version of an image, select latest.
To specify a selected marketplace image, provide the resource ID of the image by using the resourceId property.
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/Publishers/canonical/ArtifactTypes/VMImage/Offers/ubuntu-24_04-lts/Skus/server/versions/latest"
}
]To specify a selected marketplace image, provide the resource ID of the image by using the resourceId property.
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/Publishers/canonical/ArtifactTypes/VMImage/Offers/ubuntu-24_04-lts/Skus/server/versions/latest"
}
]To specify a selected marketplace image, provide the resource ID of the image by using the resourceId property.
images: [
{
resourceId: '/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest'
}
]Select Azure Compute Gallery images to specify an image from any gallery available in your subscriptions. Generalized images with the following operating systems are supported:
- Windows Server 2025
- Windows Server 2022
- Windows 11
- Ubuntu 24.04
- Ubuntu 22.04
- Debian 9
- RHEL 9
- RHEL 8
- SUSE 15
- SUSE 12
Important
Managed DevOps Pools supports only generalized Azure Compute Gallery images.
Managed DevOps Pools doesn't support Azure Compute Gallery images that you create by using a paid base image. If you receive an error like "Image Base is not supported, since it's a paid image. Please provide a different image that is free," select a different Azure Compute Gallery image based on a VM that you create by using a free pricing plan for the base image.
:::image type="content" source="./media/configure-images/image-library-compute-gallery-images.png" alt-text="Screenshot that shows Azure Compute Gallery images.":::
To specify an Azure Compute Gallery image, provide the resource ID of the image by using the resourceId property.
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/resourceGroups/resource_group_placeholder/providers/Microsoft.Compute/galleries/my_images/images/Ubuntu2404"
}
]To specify an Azure Compute Gallery image, provide the resource ID of the image by using the resourceId property.
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/resourceGroups/resource_group_placeholder/providers/Microsoft.Compute/galleries/my_images/images/Ubuntu2404"
}
]To specify an Azure Compute Gallery image, provide the resource ID of the image by using the resourceId property.
images: [
{
resourceId: '/subscriptions/subscription_id_placeholder/resourceGroups/resource_group_placeholder/providers/Microsoft.Compute/galleries/my_images/images/Ubuntu2404'
}
]Important
Assign the Reader role to the DevOpsInfrastructure service principal for the Azure Compute Gallery images that you want to use. If you select an Azure Compute Gallery image that doesn't have this access configured, pool creation fails. You can assign the Reader role individually at the image level, or at the image gallery level for all images in the gallery.
-
Go to the desired resource in the Azure portal. To use all images in a gallery, go to Azure Compute Gallery in the Azure portal. To only use a specific image, go to that image.
-
Select Access control (IAM).
-
Select Add > Add role assignment to open the Add role assignment page.
-
Assign the following role. For detailed steps, see Assign Azure roles by using the Azure portal.
Setting Value Role Reader Assign access to service principal Members DevOpsInfrastructure:::image type="content" source="./media/configure-images/add-role-assignment-button.png" alt-text="Screenshot that shows Add role assignment."
If you have multiple images in your pool, you can configure your Azure DevOps pipeline to use a specific image by referencing an alias for that image.
If you have multiple images in your pool, and don't use demands in your pipelines to designate an image, the pipelines run by using the first listed image in your pool. You can change the order of the images in your pool in the following ways:
- Use templates: Change the order of the images in the
imageslist in thefabricProfilesection. - Use dragging: Order the images in the images list in the Azure portal.
If your pipelines experience problems after adding a new image to your pool, check the ordering of the images in the list. Consider using demands and aliases to explicitly designate which image each pipeline should use.
To add and manage image aliases, go to the Images section of pool settings and select ... > Add alias.
:::image type="content" source="./media/configure-images/add-alias-menu.png" alt-text="Screenshot that shows the Add alias menu option."
Add any desired aliases to the Alias list, and then select Save.
:::image type="content" source="./media/configure-images/add-alias-pane.png" alt-text="Screenshot that shows the Alias pane."
The following example shows a pool with two Azure Pipelines images and one selected marketplace image. The Azure Pipeline images show their default aliases, and the selected marketplace image shows a single configured alias named ubuntu-24.04-gen2.
:::image type="content" source="./media/configure-images/multiple-images-with-aliases.png" alt-text="Screenshot that shows a pool with multiple images with aliases."
To configure aliases, specify them in the aliases list. The following example defines one image with a single alias named ubuntu-24.04-gen2.
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest",
"aliases": [
"ubuntu-24.04-gen2"
]
}
]To configure aliases, specify them in the aliases list. The following example defines one image with a single alias named ubuntu-24.04-gen2.
"images": [
{
"resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest",
"aliases": [
"ubuntu-24.04-gen2"
]
}
]To configure aliases, specify them in the aliases list. The following example defines one image with a single alias named ubuntu-24.04-gen2.
images: [
{
resourceId: '/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest'
aliases: [
'ubuntu-24.04-gen2'
]
}
]In addition to any aliases that you configure, Azure Pipelines images have the following predefined aliases.
| Azure Pipelines image | Predefined alias |
|---|---|
| Azure Pipelines - Windows Server 2025 | windows-2025 |
| Azure Pipelines - Windows Server 2022 | windows-2022 |
| Azure Pipelines - Ubuntu 24.04 | ubuntu-24.04 |
| Azure Pipelines - Ubuntu 22.04 | ubuntu-22.04 |
If you have multiple images in your pool, you can configure a pipeline to run on a specific image by using a demand named ImageOverride. When you specify the ImageOverride demand in your pipeline, Managed DevOps Pools sends the job only to agents that are using that image.
To run a pipeline on the Ubuntu 24.04 image from the previous example that had an ubuntu-24.04-gen2 alias, specify the following demand in the pool section of your pipeline.
pool:
name: fabrikam-dev-pool # Name of Managed DevOps Pool
demands:
- ImageOverride -equals ubuntu-24.04-gen2Important
Don't put quotation marks around the alias name in the ImageOverride demand, even if it has spaces in the name.
To run a pipeline by using an Azure Pipelines image in your pool, use the alias in the previous table. To run a pipeline on the Azure Pipelines Windows Server 2022 image from the previous example, specify the following demand in the pool section of your pipeline:
pool:
name: fabrikam-dev-pool # Name of Managed DevOps Pool
demands:
- ImageOverride -equals windows-2022Managed DevOps Pools agent images are retired when the image's operating system reaches the end of its support lifecycle. Images based on older versions of operating systems might be retired when images based on new versions of the operating systems are released.
- Azure Pipelines images offers the same images and follows a similar deprecation schedule as Microsoft-hosted agents.
- Selected marketplace images are typically retired when the image's operating system reaches the end of its support lifecycle.
- Azure Pipelines - Windows Server 2019 image deprecation schedule
- Ubuntu 20.04 image deprecation schedule
Managed DevOps Pools has removed the Azure Pipelines – Windows Server 2019 Azure pipelines image.
- Creation of new pools that use the Azure Pipelines – Windows Server 2019 image was disabled as of November 1, 2025, but existing pools on these images will continue to run until December 31, 2025.
- On December 31, 2025, use of the Azure Pipelines – Windows Server 2019 image was disabled. Agents that use this image don't provision and pipelines don't run.
To keep your pools running if you use the Azure Pipelines – Windows Server 2019 image, update to the Azure Pipelines - Windows Server 2022 image. You can also use the Windows Server 2019 image from selected marketplace images or your own Azure Compute Gallery Windows 2019 image. The marketplace image doesn't include the preinstalled software from the Azure Pipelines image.
Ubuntu 20.04 LTS Standard Support ended May 31, 2025, and Managed DevOps Pools removed the Ubuntu 20.04 images from selected marketplace images and Azure Pipelines images.
The creation of new pools by using Ubuntu 20.04 selected marketplace images or Azure Pipelines images was disabled on July 15, 2025. As of August 30, 2025, pipelines that were previously configured to use these images are unsupported.
To keep your pools that currently use Ubuntu 20.04 running, update your Ubuntu 20.04 images to Ubuntu 22.04 or 24.04 (recommended). For more information, see Select your pool's image. If you have multiple images in your pool, update your aliases for your Ubuntu images so that your pipelines that require Ubuntu run by using the desired image.