Configure Managed DevOps Pools images

Managed DevOps Pools provides you with several options for virtual machine images for running pipelines in your pool. You can create your pool using selected Azure Marketplace VM images, use your own custom Azure Compute Gallery images, or use the same images as Azure Pipelines Microsoft-hosted agents.

Managed DevOps Pools can be configured with a single image or multiple images. When your pool has multiple images, your pipelines specify the image they want to run on using aliases.

Choose your pool's image

Azure portal

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, choose Add from Image Library, and select one or more images for your pool.

ARM template

Images are configured 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": "2024-10-19",
            "location": "eastus",
            "properties": {
                ...
                "fabricProfile": {
                    ...
                    "images": [
                        {
                            "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest",
                            "aliases": [
                                "ubuntu-20.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 then refer to the image using the aliases instead of the full resource ID of the image.
resourceID	The resource ID of the image to use. Required when using Azure Compute Gallery images or selected marketplace images.
wellKnownImageName	The alias of the Azure Pipelines image. Required when using Azure Pipelines images.
buffer	When standby agents are enabled, buffer designates which percentage of standby agents to be allocated to this image. The total of all image buffer values must equal 100.

The following example defines three images. Standby agents are enabled, with 100% of the standby agents allocated to the windows-2022 image.

"images": [
    {
        "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest",
        "aliases": [
            "ubuntu-20.04-gen2"
        ],
        "buffer": "0"
    },
    {
        "buffer": "100",
        "wellKnownImageName": "windows-2022"
    },
    {
        "buffer": "0",
        "wellKnownImageName": "ubuntu-22.04"
    }
]

Azure CLI

Images are configured 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/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest",
            "aliases": [
                "ubuntu-20.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 then refer to the image using the aliases instead of the full resource ID of the image.
resourceID	The resource ID of the image to use. Required when using Azure Compute Gallery images or selected marketplace images.
wellKnownImageName	The alias of the Azure Pipelines image. Required when using Azure Pipelines images.
buffer	When standby agents are enabled, buffer designates which percentage of standby agents to be allocated to this image. The total of all image buffer values must equal 100.

The following example defines three images. Standby agents are enabled, with 100% of the standby agents allocated to the windows-2022 image.

{
  "vmss": {
    "sku": {...},
    "images": [
        {
            "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest",
            "aliases": [
                "ubuntu-20.04-gen2"
            ],
            "buffer": "0"
        },
        {
            "buffer": "100",
            "wellKnownImageName": "windows-2022"
        },
        {
            "buffer": "0",
            "wellKnownImageName": "ubuntu-22.04"
        }
    ],
    "osProfile": {...},
    "storageProfile": {...}
  }
}

If you choose a single image, all pipelines run in your pool use that image. If you choose multiple images, you can specify the image to use on a per-pipeline basis. For more information, see Use multiple images per pool.

You can choose from the following types of images.

• Azure Pipelines images - Choose from the same images that Microsoft-hosted agents use.
• Selected marketplace images - Choose from a set of curated Microsoft published Azure Marketplace VM images.
• Azure Compute Gallery images - Choose from your own Azure Compute Galleries images. You must assign the Reader role to the DevOpsInfrastructure Service Principal for the Azure Compute Gallery images 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.

Azure portal

ARM template

To specify an Azure Pipelines image, provide the alias of the image using the wellKnownImageName property. See a list of Azure Pipelines image predefined aliases.

"images": [
    {
        "wellKnownImageName": "windows-2022"
    }
]

Azure CLI

To specify an Azure Pipelines image, provide the alias of the image using the wellKnownImageName property. See a list of Azure Pipelines image predefined aliases.

"images": [
    {
        "wellKnownImageName": "windows-2022"
    }
]

Each image includes the following installed software.

Image	Included software
Azure Pipelines - Windows Server 2022	Included software
Azure Pipelines - Windows Server 2019	Included software
Azure Pipelines - Ubuntu 22.04	Included software
Azure Pipelines - Ubuntu 20.04	Included software

Selected marketplace images

Managed DevOps Pools provides a set of curated Microsoft published Azure Marketplace VM images for use in your pools.

Azure portal

Choose Selected marketplace images, choose the desired image, and choose the desired version. Choose latest to always use the latest version of the image.

ARM template

To specify a selected marketplace image, provide the resource ID of the image using the resourceId property.

"images": [
    {
        "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest"
    }
]

Azure CLI

To specify selected marketplace image, provide the resource ID of the image using the resourceId property.

"images": [
    {
        "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest"
    }
]

Azure Compute Gallery images

Choose Azure Compute Gallery images to specify an image from any Azure Compute Galleries that are available in your subscriptions. Generalized images with the following operating systems are supported.

• Windows Server 2019
• Windows Server 2022
• Windows 11
• Ubuntu 20.04
• Ubuntu 22.04
• Ubuntu 24.04
• Debian 9
• RHEL 8
• RHEL 9
• SUSE 12
• SUSE 15

Important

Managed DevOps Pools supports only generalized Azure Compute Gallery images.

Azure portal

ARM template

To specify an Azure Compute Gallery image, provide the resource ID of the image using the resourceId property.

"images": [
    {
        "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest"
    }
]

Azure CLI

To specify selected marketplace image, provide the resource ID of the image using the resourceId property.

"images": [
    {
        "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest"
    }
]

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

1. Go to the desired resource in the Azure portal. To be able to use all images in a gallery, go to Azure Compute Gallery in the Azure portal. To use a specific image only, go to that image.

2. Select Access control (IAM).

3. Select Add > Add role assignment to open the Add role assignment page.

4. Assign the following role. For detailed steps, see Assign Azure roles using the Azure portal.

   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.

Configure image aliases

Azure portal

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

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

The following example shows a pool with two Azure Pipelines images and one selected marketplace image. The Azure Pipeline images have their default aliases displayed, and the selected marketplace image has a single configured alias named ubuntu-20.04-gen2.

ARM template

To configure aliases, specify them in the aliases list. The following example defines one image with a single alias named ubuntu-20.04-gen2.

"images": [
    {
        "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest",
        "aliases": [
            "ubuntu-20.04-gen2"
        ]
    }
]

Azure CLI

To configure aliases, specify them in the aliases list. The following example defines one image with a single alias named ubuntu-20.04-gen2.

"images": [
    {
        "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest",
        "aliases": [
            "ubuntu-20.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 2022	windows-2022
Azure Pipelines - Windows Server 2019	windows-2019
Azure Pipelines - Ubuntu 22.04	ubuntu-22.04
Azure Pipelines - Ubuntu 20.04	ubuntu-20.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 using that image.

To run a pipeline on the Ubuntu 20.04 image from the previous example that had an ubuntu-20.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-20.04-gen2

Important

Don't put quotes around the alias name in the ImageOverride demand, even if it has spaces in the name.

To run a pipeline 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

See also

• Configure pool settings