Run ACR Tasks using Resource Manager templates

ACR Tasks is a suite of features within Azure Container Registry to help you manage and modify container images across the container lifecycle.

This article shows Azure Resource Manager template examples to queue a quick task run, similar to one you can create manually using the az acr build command.

A Resource Manager template to queue a task run is useful in automation scenarios and extends the functionality of az acr build. For example:

• Use a template to create a container registry and immediately queue a task run to build and push a container image
• Create or enable additional resources you can use in a quick task run, such as a managed identity for Azure resources

• You must specify a remote context such as a GitHub repo as the source location for your task run. You can't use a local source context.
• For task runs using a managed identity, only a user-assigned managed identity is permitted.

• GitHub account - Create an account on https://github.com if you don't already have one.
• Fork sample repository - For the task examples shown here, use the GitHub UI to fork the following sample repository into your GitHub account: https://github.com/Azure-Samples/acr-build-helloworld-node. This repo contains sample Dockerfiles and source code to build small container images.

This example uses a sample template to create a container registry and queue a task run that builds and pushes an image.

For this example, provide values for the following template parameters:

Deploy the template with the az deployment group create command. This example builds and pushes the helloworld-node:testrun image to a registry named mycontainerregistry.

az deployment group create \
  --resource-group myResourceGroup \
  --template-uri https://raw.githubusercontent.com/Azure/acr/master/docs/tasks/run-as-deployment/quickdockerbuild/azuredeploy.json \
  --parameters \
    registryName=mycontainerregistry \
    repository=helloworld-node \
    taskRunName=testrun \
    sourceLocation=https://github.com/Azure-Samples/acr-build-helloworld-node.git#main

The previous command passes the parameters on the command line. If desired, pass them in a parameters file.

After the deployment completes successfully, verify the image is built by running az acr repository show-tags:

az acr repository show-tags \
  --name mycontainerregistry \
  --repository helloworld-node --output table

Output:

Result
--------
testrun

To view details about the task run, view the run log.

First, get the run ID with az acr task list-runs

az acr task list-runs \
  --registry mycontainerregistry --output table

Output is similar to:

RUN ID    TASK    PLATFORM    STATUS     TRIGGER    STARTED               DURATION
--------  ------  ----------  ---------  ---------  --------------------  ----------
ca1               linux       Succeeded  Manual     2020-03-23T17:54:28Z  00:00:48

Run az acr task logs to view task run logs for the run ID, in this case ca1:

az acr task logs \
  --registry mycontainerregistry \
  --run-id ca1

The output shows the task run log.

You can also view the task run log in the Azure portal.

1. Navigate to your container registry
2. Under Services, select Tasks > Runs.
3. Select the run ID, in this case ca1.

The portal shows the task run log.

Use a sample template to queue a task run that enables a user-assigned managed identity. During the task run, the identity authenticates to pull an image from another Azure container registry.

This scenario is similar to Cross-registry authentication in an ACR task using an Microsoft-managed identity. For example, an organization might maintain a centralized registry with base images accessed by multiple development teams.

For demonstration purposes, create a separate container registry as your base registry, and push a Node.js base image pulled from Docker Hub.

1. Create a second container registry, for example mybaseregistry, to store base images.

2. Pull the node:9-alpine image from Docker Hub, tag it for your base registry, and push it to the base registry:

   docker pull node:9-alpine
   docker tag node:9-alpine mybaseregistry.azurecr.cn/baseimages/node:9-alpine
   az acr login -n mybaseregistry
   docker push mybaseregistry.azurecr.cn/baseimages/node:9-alpine
   

Create a Dockerfile that pulls the base image from your base registry. Perform the following steps in your local fork of the GitHub repo, for example, https://github.com/myGitHubID/acr-build-helloworld-node.git.

1. In the GitHub UI, select Create new file.
2. Name your file Dockerfile-test and paste the following contents. Substitute your registry name for mybaseregistry.

   FROM mybaseregistry.azurecr.cn/baseimages/node:9-alpine
   COPY . /src
   RUN cd /src && npm install
   EXPOSE 80
   CMD ["node", "/src/server.js"]
   

3. Select Commit new file.

Create an identity named myACRTasksId in your subscription using the az identity create command. You can use the same resource group you used previously to create a container registry, or a different one.

az identity create \
  --resource-group myResourceGroup \
  --name myACRTasksId

To configure the user-assigned identity in the following steps, use the az identity show command to store the identity's resource ID, principal ID, and client ID in variables.

# Get resource ID of the user-assigned identity
resourceID=$(az identity show \
  --resource-group myResourceGroup \
  --name myACRTasksId \
  --query id --output tsv)

# Get principal ID of the task's user-assigned identity
principalID=$(az identity show \
  --resource-group myResourceGroup \
  --name myACRTasksId \
  --query principalId --output tsv)

# Get client ID of the user-assigned identity
clientID=$(az identity show \
  --resource-group myResourceGroup \
  --name myACRTasksId \
  --query clientId --output tsv)

Give the managed identity permissions to pull from the base registry, mybaseregistry.

Use the az acr show command to get the resource ID of the base registry and store it in a variable:

baseregID=$(az acr show \
  --name mybaseregistry \
  --query id --output tsv)

Use the az role assignment create command to assign the identity the Acrpull role to the base registry. This role has permissions only to pull images from the registry.

az role assignment create \
  --assignee $principalID \
  --scope $baseregID \
  --role acrpull

For this example, provide values for the following template parameters:

Deploy the template with the az deployment group create command. This example builds and pushes the helloworld-node:testrun image to a registry named mycontainerregistry. The base image is pulled from mybaseregistry.azurecr.cn.

az deployment group create \
  --resource-group myResourceGroup \
  --template-uri https://raw.githubusercontent.com/Azure/acr/master/docs/tasks/run-as-deployment/quickdockerbuildwithidentity/azuredeploy.json \
  --parameters \
    registryName=mycontainerregistry \
    repository=helloworld-node \
    taskRunName=basetask \
    userAssignedIdentity=$resourceID \
    customRegistryIdentity=$clientID \
    sourceLocation=https://github.com/<your-GitHub-ID>/acr-build-helloworld-node.git#main \
    dockerFilePath=Dockerfile-test \
    customRegistry=mybaseregistry.azurecr.cn

The previous command passes the parameters on the command line. If desired, pass them in a parameters file.

After the deployment completes successfully, verify the image is built by running az acr repository show-tags:

az acr repository show-tags \
  --name mycontainerregistry \
  --repository helloworld-node --output table

Output:

Result
--------
basetask

To view the run log, see steps in the preceding section.

• See more template examples in the ACR GitHub repo.
• For details about template properties, see the template reference for Task runs and Tasks.