Skip to content

Commit 4188fd4

Browse files
ShannonLeavittShannonLeavitt
authored
Merge pull request #109167 from dlepow/taskarm
[ACR] Task from template
2 parents cae8462 + 1f92b2e commit 4188fd4

File tree

3 files changed

+266
-5
lines changed

3 files changed

+266
-5
lines changed

‎articles/container-registry/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,8 @@
187187
href: container-registry-tasks-cross-registry-authentication.md
188188
- name: External authentication using key vault
189189
href: container-registry-tasks-authentication-key-vault.md
190+
- name: Quick task run with Resource Manager template
191+
href: container-registry-task-run-template.md
190192
- name: Build image with Buildpacks (preview)
191193
href: container-registry-tasks-pack-build.md
192194
- name: View task logs

‎articles/container-registry/container-registry-task-run-template.md

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
---
2+
title: Quick task run with template
3+
description: Queue an ACR task run to build an image using an Azure Resource Manager template
4+
ms.topic: article
5+
ms.date: 04/22/2020
6+
---
7+
8+
# Run ACR Tasks using Resource Manager templates
9+
10+
[ACR Tasks](container-registry-tasks-overview.md) is a suite of features within Azure Container Registry to help you manage and modify container images across the container lifecycle.
11+
12+
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][az-acr-build] command.
13+
14+
A Resource Manager template to queue a task run is useful in automation scenarios and extends the functionality of `az acr build`. For example:
15+
16+
* Use a template to create a container registry and immediately queue a task run to build and push a container image
17+
* Create or enable additional resources you can use in a quick task run, such as a managed identity for Azure resources
18+
19+
## Limitations
20+
21+
* You must specify a remote context such as a GitHub repo as the [source location](container-registry-tasks-overview.md#context-locations) for your task run. You can't use a local source context.
22+
* For task runs using a managed identity, only a *user-assigned* managed identity is permitted.
23+
24+
## Prerequisites
25+
26+
* **GitHub account** - Create an account on https://github.com if you don't already have one.
27+
* **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.
28+
29+
## Example: Create registry and queue task run
30+
31+
This example uses a [sample template](https://github.com/Azure/acr/tree/master/docs/tasks/run-as-deployment/quickdockerbuild) to create a container registry and queue a task run that builds and pushes an image.
32+
33+
### Template parameters
34+
35+
For this example, provide values for the following template parameters:
36+
37+
|Parameter |Value |
38+
|---------|---------|
39+
|registryName |Unique name of registry that's created |
40+
|repository |Target repository for build task |
41+
|taskRunName |Name of task run, which specifies image tag |
42+
|sourceLocation |Remote context for the build task, for example, https://github.com/Azure-Samples/acr-build-helloworld-node. The Dockerfile in the repo root builds a container image for a small Node.js web app. If desired, use your fork of the repo as the build context. |
43+
44+
### Deploy the template
45+
46+
Deploy the template with the [az deployment group create][az-deployment-group-create] command. This example builds and pushes the *helloworld-node:testrun* image to a registry named *mycontainerregistry*.
47+
48+
```azurecli
49+
az deployment group create \
50+
--resource-group myResourceGroup \
51+
--template-uri https://raw.githubusercontent.com/Azure/acr/master/docs/tasks/run-as-deployment/quickdockerbuild/azuredeploy.json \
52+
--parameters \
53+
registryName=mycontainerregistry \
54+
repository=helloworld-node \
55+
taskRunName=testrun \
56+
sourceLocation=https://github.com/Azure-Samples/acr-build-helloworld-node.git
57+
```
58+
59+
The previous command passes the parameters on the command line. If desired, pass them in a [parameters file](../azure-resource-manager/templates/parameter-files.md).
60+
61+
### Verify deployment
62+
63+
After the deployment completes successfully, verify the image is built by running [az acr repository show-tags][az-acr-repository-show-tags]:
64+
65+
```azurecli
66+
az acr repository show-tags \
67+
--name mycontainerregistry \
68+
--repository helloworld-node --output table
69+
```
70+
71+
Output:
72+
73+
```console
74+
Result
75+
--------
76+
testrun
77+
```
78+
79+
### View run log
80+
81+
To view details about the task run, view the run log.
82+
83+
First, get the run ID with [az acr task list-runs][az-acr-task-list-runs]
84+
```azurecli
85+
az acr task list-runs \
86+
--registry mycontainerregistry --output table
87+
```
88+
89+
Output is similar to:
90+
91+
```console
92+
RUN ID TASK PLATFORM STATUS TRIGGER STARTED DURATION
93+
-------- ------ ---------- --------- --------- -------------------- ----------
94+
ca1 linux Succeeded Manual 2020-03-23T17:54:28Z 00:00:48
95+
```
96+
97+
Run [az acr task logs][az-acr-task-logs] to view task run logs for the run ID, in this case *ca1*:
98+
99+
```azurecli
100+
az acr task logs \
101+
--registry mycontainerregistry \
102+
--run-id ca1
103+
```
104+
105+
The output shows the task run log.
106+
107+
You can also view the task run log in the Azure portal.
108+
109+
1. Navigate to your container registry
110+
2. Under **Services**, select **Tasks** > **Runs**.
111+
3. Select the run ID, in this case *ca1*.
112+
113+
The portal shows the task run log.
114+
115+
## Example: Task run with managed identity
116+
117+
Use a [sample template](https://github.com/Azure/acr/tree/master/docs/tasks/run-as-deployment/quickdockerbuildwithidentity) 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.
118+
119+
This scenario is similar to [Cross-registry authentication in an ACR task using an Azure-managed identity](container-registry-tasks-cross-registry-authentication.md). For example, an organization might maintain a centralized registry with base images accessed by multiple development teams.
120+
121+
### Prepare base registry
122+
123+
For demonstration purposes, create a separate container registry as your base registry, and push a Node.js base image pulled from Docker Hub.
124+
125+
1. Create a second container registry, for example *mybaseregistry*, to store base images.
126+
1. Pull the `node:9-alpine` image from Docker Hub, tag it for your base registry, and push it to the base registry:
127+
128+
```azurecli
129+
docker pull node:9-alpine
130+
docker tag node:9-alpine mybaseregistry.azurecr.io/baseimages/node:9-alpine
131+
az acr login -n mybaseregistry
132+
docker push mybaseregistry.azurecr.io/baseimages/node:9-alpine
133+
```
134+
135+
### Create new Dockerfile
136+
137+
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*.
138+
139+
1. In the GitHub UI, select **Create new file**.
140+
1. Name your file *Dockerfile-test* and paste the following contents. Substitute your registry name for *mybaseregistry*.
141+
```
142+
FROM mybaseregistry.azurecr.io/baseimages/node:9-alpine
143+
COPY . /src
144+
RUN cd /src && npm install
145+
EXPOSE 80
146+
CMD ["node", "/src/server.js"]
147+
```
148+
1. Select **Commit new file**.
149+
150+
[!INCLUDE [container-registry-tasks-user-assigned-id](../../includes/container-registry-tasks-user-assigned-id.md)]
151+
152+
### Give identity pull permissions to the base registry
153+
154+
Give the managed identity permissions to pull from the base registry, *mybaseregistry*.
155+
156+
Use the [az acr show][az-acr-show] command to get the resource ID of the base registry and store it in a variable:
157+
158+
```azurecli
159+
baseregID=$(az acr show \
160+
--name mybaseregistry \
161+
--query id --output tsv)
162+
```
163+
164+
Use the [az role assignment create][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.
165+
166+
```azurecli
167+
az role assignment create \
168+
--assignee $principalID \
169+
--scope $baseregID \
170+
--role acrpull
171+
```
172+
173+
### Template parameters
174+
175+
For this example, provide values for the following template parameters:
176+
177+
|Parameter |Value |
178+
|---------|---------|
179+
|registryName |Name of registry where image is built |
180+
|repository |Target repository for build task |
181+
|taskRunName |Name of task run, which specifies image tag |
182+
|userAssignedIdentity |Resource ID of user-assigned identity enabled in the task|
183+
|customRegistryIdentity | Client ID of user-assigned identity enabled in the task, used to authenticate with custom registry |
184+
|customRegistry |Login server name of the custom registry accessed in the task, for example, *mybaseregistry.azurecr.io*|
185+
|sourceLocation |Remote context for the build task, for example, *https://github.com/\<your-GitHub-ID\>/acr-build-helloworld-node.* |
186+
|dockerFilePath | Path to the Dockerfile at the remote context, used to build the image. |
187+
188+
### Deploy the template
189+
190+
Deploy the template with the [az deployment group create][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.io*.
191+
192+
```azurecli
193+
az deployment group create \
194+
--resource-group myResourceGroup \
195+
--template-uri https://raw.githubusercontent.com/Azure/acr/master/docs/tasks/run-as-deployment/quickdockerbuildwithidentity/azuredeploy.json \
196+
--parameters \
197+
registryName=mycontainerregistry \
198+
repository=helloworld-node \
199+
taskRunName=basetask \
200+
userAssignedIdentity=$resourceID \
201+
customRegistryIdentity=$clientID \
202+
sourceLocation=https://github.com/<your-GitHub-ID>/acr-build-helloworld-node.git \
203+
dockerFilePath=Dockerfile-test \
204+
customRegistry=mybaseregistry.azurecr.io
205+
```
206+
207+
The previous command passes the parameters on the command line. If desired, pass them in a [parameters file](../azure-resource-manager/templates/parameter-files.md).
208+
209+
### Verify deployment
210+
211+
After the deployment completes successfully, verify the image is built by running [az acr repository show-tags][az-acr-repository-show-tags]:
212+
213+
```azurecli
214+
az acr repository show-tags \
215+
--name mycontainerregistry \
216+
--repository helloworld-node --output table
217+
```
218+
219+
Output:
220+
221+
```console
222+
Result
223+
--------
224+
basetask
225+
```
226+
227+
### View run log
228+
229+
To view the run log, see steps in the [preceding section](#view-run-log).
230+
231+
## Next steps
232+
233+
* See more template examples in the [ACR GitHub repo](https://github.com/Azure/acr/tree/master/docs/tasks/run-as-deployment).
234+
* For details about template properties, see the template reference for [Task runs](/azure/templates/microsoft.containerregistry/2019-06-01-preview/registries/taskruns) and [Tasks](/azure/templates/microsoft.containerregistry/2019-06-01-preview/registries/tasks).
235+
236+
237+
<!-- LINKS - Internal -->
238+
[azure-cli]: /cli/azure/install-azure-cli
239+
[az-acr-build]: /cli/azure/acr#az-acr-build
240+
[az-acr-show]: /cli/azure/acr#az-acr-show
241+
[az-acr-task-run]: /cli/azure/acr/task#az-acr-task-run
242+
[az-acr-task-logs]: /cli/azure/acr/task#az-acr-task-logs
243+
[az-acr-repository-show-tags]: /cli/azure/acr/repository#az-acr-repository-show-tags
244+
[az-acr-task-list-runs]: /cli/azure/acr/task#az-acr-task-list-runs
245+
[az-deployment-group-create]: /cli/azure/deployment/group#az-deployment-group-create
246+
[az-identity-create]: /cli/azure/identity#az-identity-create
247+
[az-identity-show]: /cli/azure/identity#az-identity-show
248+
[az-role-assignment-create]: /cli/azure/role/assignment#az-role-assignment-create

‎includes/container-registry-tasks-user-assigned-id.md

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,21 +14,32 @@ ms.custom: include file
1414

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

17-
```azurecli-interactive
18-
az identity create --resource-group myResourceGroup --name myACRTasksId
17+
```azurecli
18+
az identity create \
19+
--resource-group myResourceGroup \
20+
--name myACRTasksId
1921
```
2022

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

2325
```azurecli
2426
# Get resource ID of the user-assigned identity
25-
resourceID=$(az identity show --resource-group myResourceGroup --name myACRTasksId --query id --output tsv)
27+
resourceID=$(az identity show \
28+
--resource-group myResourceGroup \
29+
--name myACRTasksId \
30+
--query id --output tsv)
2631
2732
# Get principal ID of the task's user-assigned identity
28-
principalID=$(az identity show --resource-group myResourceGroup --name myACRTasksId --query principalId --output tsv)
33+
principalID=$(az identity show \
34+
--resource-group myResourceGroup \
35+
--name myACRTasksId \
36+
--query principalId --output tsv)
2937
3038
# Get client ID of the user-assigned identity
31-
clientID=$(az identity show --resource-group myResourceGroup --name myACRTasksId --query clientId --output tsv)
39+
clientID=$(az identity show \
40+
--resource-group myResourceGroup \
41+
--name myACRTasksId \
42+
--query clientId --output tsv)
3243
```
3344

3445
<!-- LINKS - Internal -->

0 commit comments

Comments
 (0)