Configure Managed DevOps Pools images

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

The following images are being deprecated in Managed DevOps Pools:

Azure Pipelines - Windows Server 2019
Ubuntu 20.04

For more information, see Managed DevOps Pools image deprecation schedule.

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.

Select your pool's image

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.

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-01-21",
            "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-01-21' = {
  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 images list in the fabricProfile section.
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 DevOpsInfrastructure service principal for the Azure Compute Gallery images that you want to use. For more information, see Grant Reader role access to the DevOpsInfrastructure service principal.

Azure Pipelines images

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.

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"
    }
]

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 - Windows Server 2019	Included software
Azure Pipelines - Ubuntu 24.04	Included software
Azure Pipelines - Ubuntu 22.04	Included software

Important

The following images are being deprecated in Managed DevOps Pools:

Azure Pipelines - Windows Server 2019
Ubuntu 20.04

For more information, see Managed DevOps Pools image deprecation schedule.

Selected marketplace images

Managed DevOps Pools provides a curated set of Microsoft-published marketplace VM images to use in your pools.

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'
  }
]

Azure Compute Gallery images

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.

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'
  }
]

Grant Reader role access to the DevOpsInfrastructure service principal

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

Setting	Value
Role	Reader
Assign access to	service principal
Members	`DevOpsInfrastructure`

Use multiple images per pool with aliases

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.

Use templates: Change the order of the images in the images list in the fabricProfile section.
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.

Configure image aliases

To add and manage image aliases, go to the Images section of pool settings and select ... > Add alias.

Add any desired aliases to the Alias list, and then select Save.

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.

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'
    ]
  }
]

Azure Pipelines image predefined aliases

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 - Windows Server 2019	`windows-2019`
Azure Pipelines - Ubuntu 24.04	`ubuntu-24.04`
Azure Pipelines - Ubuntu 22.04	`ubuntu-22.04`

Use demands to specify an image

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-gen2

Important

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-2022

Image lifecycle

Managed 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.

Image deprecation schedule

Azure Pipelines - Windows Server 2019 image deprecation schedule
Ubuntu 20.04 image deprecation schedule

Azure Pipelines - Windows Server 2019 image deprecation schedule

Managed DevOps Pools is removing the Azure Pipelines – Windows Server 2019 image.

Creation of new pools that use the Azure Pipelines – Windows Server 2019 image is 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 will be 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 image deprecation schedule

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.

Configure pool settings

Feedback

Was this page helpful?

Last updated on 2025-11-04

Share via

Configure Managed DevOps Pools images

Select your pool's image

Azure Pipelines images

Selected marketplace images

Azure Compute Gallery images

Grant Reader role access to the DevOpsInfrastructure service principal

Use multiple images per pool with aliases

Configure image aliases

Azure Pipelines image predefined aliases

Use demands to specify an image

Image lifecycle

Image deprecation schedule

Azure Pipelines - Windows Server 2019 image deprecation schedule

Ubuntu 20.04 image deprecation schedule

Related content

Feedback

Additional resources