Build a docker image in a self-hosted agent running on Azure Container Instances

How can a self-hosted agent running on Azure Container Instances create a docker image? Even while the question may seem simple, it is difficult.

Suppose you’ve already set up a self-hosted agent on an Azure Container Instance (ACR); if you’re unsure how to do so, check out my blog right here! You run a pipeline with a simple docker image and … you get the below error:

Unable to locate executable file: ‘docker’. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable. Also check the file mode to verify the file is executable.

Using ACR you cannot build a docker image. This operation requires access to Docker API running on the container’s host and executing privileged containers. Within ACR you cannot access the host, so your build fails.


Like always in the Azure Cloud, there are a few solutions to the issue:

  • create a self-hosted agent on a Virtual Machine – this will work, but you need to maintain VM and set it up.
  • create a VM scale set – Azure DevOps is deploying new agents in that approach.
  • use Azure Container Registry dedicated agent pool – this enables us to build our docker images in the agents handled by ACR. So you don’t need to setup them up, this is pure Microsoft-owned services. It is also possible to have an agent pool integrated with your vnet, so it matches with Network Series concepts.

The complete pipeline you can find here!

Build a Docker image using Azure Container Registry dedicated agent pool

Firstly you must create a dedicated agent pool. You have two options, create a pool within vnet or not.

#simple agent pool
az acr agentpool create \
    --registry MyRegistry \
    --name myagentpool \
    --tier S2

#agnet pool with vnet integration
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

You have four tiers for the agent pool to choose from:

  • S1 – 2 CPU, 3 GB RAM
  • S2 – 4 CPU, 8 GB RAM
  • S3 – 8 CPU, 16 GB RAM
  • I6 – 64 CPU, 216 GB RAM

To build a Docker image using ACR dedicated agent pool you need to run the below command:

az acr build --registry $CONTAINERREGISTRY --agent-pool $AGENTPOOLNAME --image $IMAGEREPOSITORY:$TAG .


  • CONTAINERREGISTRY – is the name of your ACR, for example,
  • AGENTPOOLNAME – is the dedicated agent pool name
  • IMAGEREPOSITORY – the name of your image
  • TAG – tag for your image

From my experience, this build is slower than I run at Microsft hosted agent, but this is not a significant difference.

What next?

In this article, I explained how to build a docker image when you have a self-hosted agent in Azure Container Instances (ACI).

However, this is only part of the solution of Network Series, the whole solution contains the:

If you have any suggestions please leave a comment or use the contact form

Leave a Reply

Your email address will not be published. Required fields are marked *