Run an ACR task on a dedicated agent pool

Set up an Azure-managed VM pool (agent pool) to enable running your Azure Container Registry tasks in a dedicated compute environment. After you've configured one or more pools in your registry, you can choose a pool to run a task in place of the service's default compute environment.

An agent pool provides:

• Virtual network support - Assign an agent pool to an Azure VNet, providing access to resources in the VNet such as a container registry, key vault, or storage.
• Scale as needed - Increase the number of instances in an agent pool for compute-intensive tasks, or scale to zero. Billing is based on pool allocation. For details, see Pricing.
• Flexible options - Choose from different pool tiers and scale options to meet your task workload needs.
• Azure management - Task pools are patched and maintained by Azure, providing reserved allocation without the need to maintain the individual VMs.

This feature is available in the Premium container registry service tier. For information about registry service tiers and limits, see Azure Container Registry SKUs.

Important

This feature is currently in preview, and some limitations apply. Previews are made available to you on the condition that you agree to the supplemental terms of use. Some aspects of this feature may change prior to general availability (GA).

Preview limitations

• Task agent pools currently support Linux nodes. Windows nodes aren't currently supported.
• Task agent pools are available in preview in the following regions: West US 2, South Central US, East US 2, East US, Central US, West Europe, North Europe, Canada Central, East Asia, USGov Arizona, USGov Texas, and USGov Virginia.
• For each registry, the default total vCPU (core) quota is 16 for all standard agent pools and is 0 for isolated agent pools. Open a support request for additional allocation.
• You can't currently cancel a task run on an agent pool.

Prerequisites

• To use the Azure CLI steps in this article, Azure CLI version 2.3.1 or later is required. If you need to install or upgrade, see Install Azure CLI. Or run in Azure Cloud Shell.
• If you don't already have a container registry, create one (Premium tier required) in a preview region.

Pool tiers

Agent pool tiers provide the following resources per instance in the pool.

Tier	Type	CPU	Memory (GB)
S1	standard	2	3
S2	standard	4	8
S3	standard	8	16
I6	isolated	64	216

Create and manage a task agent pool

Set default registry (optional)

To simplify Azure CLI commands that follow, set the default registry by running the az config command:

az config set defaults.acr=<registryName>

The following examples assume that you've set the default registry. If not, pass a --registry <registryName> parameter in each az acr command.

Create agent pool

Create an agent pool by using the az acr agentpool create command. The following example creates a tier S2 pool (4 CPU/instance). By default, the pool contains 1 instance.

az acr agentpool create \
    --registry MyRegistry \
    --name myagentpool \
    --tier S2

Note

Creating an agent pool and other pool management operations take several minutes to complete.

Scale pool

Scale the pool size up or down with the az acr agentpool update command. The following example scales the pool to 2 instances. You can scale to 0 instances.

az acr agentpool update \
    --registry MyRegistry \
    --name myagentpool \
    --count 2

Create pool in a virtual network

Add firewall rules

Task agent pools require access to the following Azure services. The following firewall rules must be added to any existing network security groups or user-defined routes.

Direction	Protocol	Source	Source Port	Destination	Dest Port	Used
Outbound	TCP	VirtualNetwork	Any	AzureKeyVault	443	Default
Outbound	TCP	VirtualNetwork	Any	Storage	443	Default
Outbound	TCP	VirtualNetwork	Any	EventHub	443	Default
Outbound	TCP	VirtualNetwork	Any	AzureActiveDirectory	443	Default
Outbound	TCP	VirtualNetwork	Any	AzureMonitor	443	Default

Note

If your tasks require additional resources from the public internet, add the corresponding rules. For example, additional rules are needed to run a docker build task that pulls the base images from Docker Hub, or restores a NuGet package.

Customers basing their deployments with MCR can refer to MCR/MAR firewall rules.

Create pool in VNet

The following example creates an agent pool in the mysubnet subnet of network myvnet:

# Get the subnet ID
subnetId=$(az network vnet subnet show \
        --resource-group myresourcegroup \
        --vnet-name myvnet \
        --name mysubnetname \
        --query id --output tsv)

az acr agentpool create \
    --registry MyRegistry \
    --name myagentpool \
    --tier S2 \
    --subnet-id $subnetId

Run task on agent pool

The following examples show how to specify an agent pool when queuing a task.

Note

To use an agent pool in an ACR task, ensure that the pool contains at least 1 instance.

Quick task

Queue a quick task on the agent pool by using the az acr build command and pass the --agent-pool parameter:

az acr build \
    --registry MyRegistry \
    --agent-pool myagentpool \
    --image myimage:mytag \
    --file Dockerfile \
    https://github.com/Azure-Samples/acr-build-helloworld-node.git#main

Automatically triggered task

For example, create a scheduled task on the agent pool with az acr task create, passing the --agent-pool parameter.

az acr task create \
    --registry MyRegistry \
    --name mytask \
    --agent-pool myagentpool \
    --image myimage:mytag \
    --schedule "0 21 * * *" \
    --file Dockerfile \
    --context https://github.com/Azure-Samples/acr-build-helloworld-node.git#main \
    --commit-trigger-enabled false

To verify task setup, run az acr task run:

az acr task run \
    --registry MyRegistry \
    --name mytask

Query pool status

To find the number of runs currently scheduled on the agent pool, run az acr agentpool show.

az acr agentpool show \
    --registry MyRegistry \
    --name myagentpool \
    --queue-count

Next steps

For more examples of container image builds and maintenance in the cloud, check out the ACR Tasks tutorial series.