Skip to content

Commit b95eb31

Browse files
ShannonLeavittShannonLeavitt
authored
Merge pull request #83979 from dlepow/acrpurge
[ACR] Auto-purge
2 parents 7c266aa + 5f2c017 commit b95eb31

File tree

3 files changed

+201
-7
lines changed

3 files changed

+201
-7
lines changed

‎articles/container-registry/TOC.yml

+5-1
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,11 @@
6666
- name: Lock container images
6767
href: container-registry-image-lock.md
6868
- name: Delete container images
69-
href: container-registry-delete.md
69+
items:
70+
- name: Delete image data - CLI
71+
href: container-registry-delete.md
72+
- name: Automatically purge tags and manifests (preview)
73+
href: container-registry-auto-purge.md
7074
- name: Upgrade a Classic registry
7175
href: container-registry-upgrade.md
7276
- name: Use ACR webhooks

‎articles/container-registry/container-registry-auto-purge.md

+187
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: Automatically remove image resources in Azure Container Registry
3+
description: Use a purge command to delete multiple tags and manifests from an Azure container registry based on age and a tag filter, and optionally schedule purge operations.
4+
services: container-registry
5+
author: dlepow
6+
manager: gwallace
7+
8+
ms.service: container-registry
9+
ms.topic: article
10+
ms.date: 08/14/2019
11+
ms.author: danlep
12+
---
13+
14+
# Automatically purge images from an Azure container registry
15+
16+
When you use an Azure container registry as part of a development workflow, the registry can quickly fill up with images or other artifacts that aren't needed after a short period. You might want to delete all tags that are older than a certain duration or match a specified name filter. To delete multiple artifacts quickly, this article introduces the `acr purge` command you can run as an on-demand or [scheduled](container-registry-tasks-scheduled.md) ACR Task.
17+
18+
The `acr purge` command is currently distributed in a public container image available from Microsoft Container Registry.
19+
20+
You can use the Azure Cloud Shell or a local installation of the Azure CLI to run the ACR task examples in this article. If you'd like to use it locally, version 2.0.69 or later is required. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][azure-cli-install].
21+
22+
> [!IMPORTANT]
23+
> This feature is currently in preview. Previews are made available to you on the condition that you agree to the [supplemental terms of use][terms-of-use]. Some aspects of this feature may change prior to general availability (GA).
24+
25+
> [!WARNING]
26+
> Use the `acr purge` command with caution--deleted image data is UNRECOVERABLE. If you have systems that pull images by manifest digest (as opposed to image name), you should not purge untagged images. Deleting untagged images will prevent those systems from pulling the images from your registry. Instead of pulling by manifest, consider adopting a *unique tagging* scheme, a [recommended best practice](container-registry-image-tag-version.md).
27+
28+
If you want to delete single image tags or manifests using Azure CLI commands, see [Delete container images in Azure Container Registry](container-registry-delete.md).
29+
30+
## Use the purge command
31+
32+
The `acr purge` container command deletes images by tag in a repository that match a name filter and that are older than a specified duration. By default, only tag references are deleted, not the underlying [manifests](container-registry-concepts.md#manifest) and layer data. The command has an option to also delete manifests.
33+
34+
> [!NOTE]
35+
> `acr purge` does not delete an image tag or repository where the `write-enabled` attribute is set to `false`. For information, see [Lock a container image in an Azure container registry](container-registry-image-lock.md).
36+
37+
`acr purge` is designed to run as a container command in an [ACR Task](container-registry-tasks-overview.md), so that it authenticates automatically with the registry where the task runs.
38+
39+
At a minimum, specify the following when you run `acr purge`:
40+
41+
* `--registry` - The Azure container registry where you run the command.
42+
* `--filter` - A repository and a *regular expression* to filter tags in the repository. Examples: `--filter "hello-world:.*"` matches all tags in the `hello-world` repository, and `--filter "hello-world:^1.*"` matches tags beginning with `1`. Pass multiple `--filter` parameters to purge multiple repositories.
43+
* `--ago` - A Go-style [duration string](https://golang.org/pkg/time/) to indicate a duration beyond which images are deleted. The duration consists of a sequence of one or more decimal numbers, each with a unit suffix. Valid time units include "d" for days, "h" for hours, and "m" for minutes. For example, `--ago 2d3h6m` selects all filtered images last modified more than 2 days, 3 hours, and 6 minutes ago, and `--ago 1.5h` selects images last modified more than 1.5 hours ago.
44+
45+
`acr purge` supports several optional parameters. The following two are used in examples in this article:
46+
47+
* `--untagged` - Specifies that manifests that don't have associated tags (*untagged manifests*) are deleted.
48+
* `--dry-run` - Specifies that no data is deleted, but the output is the same as if the command is run without this flag. This parameter is useful for testing a purge command to make sure it does not inadvertently delete data you intend to preserve.
49+
50+
For additional parameters, run `acr purge --help`.
51+
52+
`acr purge` supports other features of ACR Tasks commands including [run variables](container-registry-tasks-reference-yaml.md#run-variables) and [task run logs](container-registry-tasks-overview.md#view-task-logs) that are streamed and also saved for later retrieval.
53+
54+
### Run in an on-demand task
55+
56+
The following example uses the [az acr run][az-acr-run] command to run the `purge` command on-demand. This example deletes all image tags and manifests in the `hello-world` repository in *myregistry* that were modified more than 1 day ago. The container command is passed using an environment variable. The task runs without a source context.
57+
58+
```azurecli
59+
# Environment variable for container command line
60+
PURGE_CMD="mcr.microsoft.com/acr/acr-cli:0.1 purge \
61+
--registry {{.Run.Registry}} --filter 'hello-world:.*' --untagged --ago 1d"
62+
63+
az acr run \
64+
--cmd "$PURGE_CMD" \
65+
--registry myregistry \
66+
/dev/null
67+
```
68+
69+
### Run in a scheduled task
70+
71+
The following example uses the [az acr task create][az-acr-task-create] command to create a daily [scheduled ACR task](container-registry-tasks-scheduled.md). The task purges tags modified more than 7 days ago in the `hello-world` repository. The container command is passed using an environment variable. The task runs without a source context.
72+
73+
```azurecli
74+
# Environment variable for container command line
75+
PURGE_CMD="mcr.microsoft.com/acr/acr-cli:0.1 purge \
76+
--registry {{.Run.Registry}} --filter 'hello-world:.*' --ago 7d"
77+
78+
az acr task create --name purgeTask \
79+
--cmd "$PURGE_CMD" \
80+
--schedule "0 0 * * *" \
81+
--registry myregistry \
82+
--context /dev/null
83+
```
84+
85+
Run the [az acr task show][az-acr-task-show] command to see that the timer trigger is configured.
86+
87+
### Purge large numbers of tags and manifests
88+
89+
Purging a large number of tags and manifests could take several minutes or longer. To purge thousands of tags and manifests, the command might need to run longer than the default timeout time of 600 seconds for an on-demand task, or 3600 seconds for a scheduled task. If the timeout time is exceeded, only a subset of tags and manifests are deleted. To ensure that a large-scale purge is complete, pass the `--timeout` parameter to increase the value.
90+
91+
For example, the following on-demand task sets a timeout time of 3600 seconds (1 hour):
92+
93+
```azurecli
94+
# Environment variable for container command line
95+
PURGE_CMD="mcr.microsoft.com/acr/acr-cli:0.1 purge \
96+
--registry {{.Run.Registry}} --filter 'hello-world:.*' --ago 1d --untagged"
97+
98+
az acr run \
99+
--cmd "$PURGE_CMD" \
100+
--registry myregistry \
101+
--timeout 3600 \
102+
/dev/null
103+
```
104+
105+
## Example: Scheduled purge of multiple repositories in a registry
106+
107+
This example walks through using `acr purge` to periodically clean up multiple repositories in a registry. For example, you might have a development pipeline that pushes images to the `samples/devimage1` and `samples/devimage2` repositories. You periodically import development images into a production repository for your deployments, so you no longer need the development images. On a weekly basis, you purge the `samples/devimage1` and `samples/devimage2` repositories, in preparation for the coming week's work.
108+
109+
### Preview the purge
110+
111+
Before deleting data, we recommend running an on-demand purge task using the `--dry-run` parameter. This option allows you to see the tags and manifests that the command will purge, without removing any data.
112+
113+
In the following example, the filter in each repository selects all tags. The `--ago 0d` parameter matches images of all ages in the repositories that match the filters. Modify the selection criteria as needed for your scenario. The `--untagged` parameter indicates to delete manifests in addition to tags. The container command is passed to the [az acr run][az-acr-run] command using an environment variable.
114+
115+
```azurecli
116+
# Environment variable for container command line
117+
PURGE_CMD="mcr.microsoft.com/acr/acr-cli:0.1 purge \
118+
--registry {{.Run.Registry}} \
119+
--filter 'samples/devimage1:.*' --filter 'samples/devimage2:.*' \
120+
--ago 0d --untagged --dry-run"
121+
122+
az acr run \
123+
--cmd "$PURGE_CMD" \
124+
--registry myregistry \
125+
/dev/null
126+
```
127+
128+
Review the command output to see the tags and manifests that match the selection parameters. Because the command is run with `--dry-run`, no data is deleted.
129+
130+
Sample output:
131+
132+
```console
133+
[...]
134+
Deleting tags for repository: samples/devimage1
135+
myregistry.azurecr.io/samples/devimage1:232889b
136+
myregistry.azurecr.io/samples/devimage1:a21776a
137+
Deleting manifests for repository: samples/devimage1
138+
myregistry.azurecr.io/samples/devimage1@sha256:81b6f9c92844bbbb5d0a101b22f7c2a7949e40f8ea90c8b3bc396879d95e788b
139+
myregistry.azurecr.io/samples/devimage1@sha256:3ded859790e68bd02791a972ab0bae727231dc8746f233a7949e40f8ea90c8b3
140+
Deleting tags for repository: samples/devimage2
141+
myregistry.azurecr.io/samples/devimage2:5e788ba
142+
myregistry.azurecr.io/samples/devimage2:f336b7c
143+
Deleting manifests for repository: samples/devimage2
144+
myregistry.azurecr.io/samples/devimage2@sha256:8d2527cde610e1715ad095cb12bc7ed169b60c495e5428eefdf336b7cb7c0371
145+
myregistry.azurecr.io/samples/devimage2@sha256:ca86b078f89607bc03ded859790e68bd02791a972ab0bae727231dc8746f233a
146+
147+
Number of deleted tags: 4
148+
Number of deleted manifests: 4
149+
[...]
150+
```
151+
152+
### Schedule the purge
153+
154+
After you've verified the dry run, create a scheduled task to automate the purge. The following example schedules a weekly task on Sunday at 1:00 UTC to run the previous purge command:
155+
156+
```azurecli
157+
# Environment variable for container command line
158+
PURGE_CMD="mcr.microsoft.com/acr/acr-cli:0.1 purge \
159+
--registry {{.Run.Registry}} \
160+
--filter 'samples/devimage1:.*' --filter 'samples/devimage2:.*' \
161+
--ago 0d --untagged --dry-run"
162+
163+
az acr task create --name weeklyPurgeTask \
164+
--cmd "$PURGE_CMD" \
165+
--schedule "0 1 * * Sun" \
166+
--registry myregistry \
167+
--context /dev/null
168+
```
169+
170+
Run the [az acr task show][az-acr-task-show] command to see that the timer trigger is configured.
171+
172+
## Next steps
173+
174+
Learn about other options to [delete image data](container-registry-delete.md) in Azure Container Registry.
175+
176+
For more information about image storage, see [Container image storage in Azure Container Registry](container-registry-storage.md).
177+
178+
<!-- LINKS - External -->
179+
180+
[terms-of-use]: https://azure.microsoft.com/support/legal/preview-supplemental-terms/
181+
182+
<!-- LINKS - Internal -->
183+
[azure-cli-install]: /cli/azure/install-azure-cli
184+
[az-acr-run]: /cli/azure/acr#az-acr-run
185+
[az-acr-task-create]: /cli/azure/acr/task#az-acr-task-create
186+
[az-acr-task-show]: /cli/azure/acr/task#az-acr-task-show
187+

‎articles/container-registry/container-registry-delete.md

+9-6
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
---
22
title: Delete image resources in Azure Container Registry
3-
description: Details on how to effectively manage registry size by deleting container image data.
3+
description: Details on how to effectively manage registry size by deleting container image data using Azure CLI commands.
44
services: container-registry
55
author: dlepow
66
manager: gwallace
77

88
ms.service: container-registry
99
ms.topic: article
10-
ms.date: 06/17/2019
10+
ms.date: 07/31/2019
1111
ms.author: danlep
1212
---
1313

14-
# Delete container images in Azure Container Registry
14+
# Delete container images in Azure Container Registry using the Azure CLI
1515

1616
To maintain the size of your Azure container registry, you should periodically delete stale image data. While some container images deployed into production may require longer-term storage, others can typically be deleted more quickly. For example, in an automated build and test scenario, your registry can quickly fill with images that might never be deployed, and can be purged shortly after completing the build and test pass.
1717

@@ -109,7 +109,7 @@ az acr repository show-manifests --name <acrName> --repository <repositoryName>
109109
After identifying stale manifest digests, you can run the following Bash script to delete manifest digests older than a specified timestamp. It requires the Azure CLI and **xargs**. By default, the script performs no deletion. Change the `ENABLE_DELETE` value to `true` to enable image deletion.
110110

111111
> [!WARNING]
112-
> Use the following sample script with caution--deleted image data is UNRECOVERABLE. If you have systems that pull images by manifest digest (as opposed to image name), you should not run these scripts. Deleting the manifest digests will prevent those systems from pulling the images from your registry. Instead of pulling by manifest, consider adopting a *unique tagging* scheme, a [recommended best practice][tagging-best-practices].
112+
> Use the following sample script with caution--deleted image data is UNRECOVERABLE. If you have systems that pull images by manifest digest (as opposed to image name), you should not run these scripts. Deleting the manifest digests will prevent those systems from pulling the images from your registry. Instead of pulling by manifest, consider adopting a *unique tagging* scheme, a [recommended best practice](container-registry-image-tag-version.md).
113113
114114
```bash
115115
#!/bin/bash
@@ -197,7 +197,7 @@ az acr repository show-manifests --name <acrName> --repository <repositoryName>
197197
Using this command in a script, you can delete all untagged images in a repository.
198198

199199
> [!WARNING]
200-
> Use the following sample scripts with caution--deleted image data is UNRECOVERABLE. If you have systems that pull images by manifest digest (as opposed to image name), you should not run these scripts. Deleting untagged images will prevent those systems from pulling the images from your registry. Instead of pulling by manifest, consider adopting a *unique tagging* scheme, a [recommended best practice][tagging-best-practices].
200+
> Use the following sample scripts with caution--deleted image data is UNRECOVERABLE. If you have systems that pull images by manifest digest (as opposed to image name), you should not run these scripts. Deleting untagged images will prevent those systems from pulling the images from your registry. Instead of pulling by manifest, consider adopting a *unique tagging* scheme, a [recommended best practice](container-registry-image-tag-version.md).
201201
202202
**Azure CLI in Bash**
203203

@@ -256,6 +256,10 @@ if ($enableDelete) {
256256
}
257257
```
258258

259+
## Automatically purge tags and manifests (preview)
260+
261+
As an alternative to scripting Azure CLI commands, run an on-demand or scheduled ACR task to delete all tags that are older than a certain duration or match a specified name filter. For more information, see [Automatically purge images from an Azure container registry](container-registry-auto-purge.md).
262+
259263
## Next steps
260264

261265
For more information about image storage in Azure Container Registry see [Container image storage in Azure Container Registry](container-registry-storage.md).
@@ -266,7 +270,6 @@ For more information about image storage in Azure Container Registry see [Contai
266270
<!-- LINKS - External -->
267271
[docker-manifest-inspect]: https://docs.docker.com/edge/engine/reference/commandline/manifest/#manifest-inspect
268272
[portal]: https://portal.azure.com
269-
[tagging-best-practices]: https://stevelasker.blog/2018/03/01/docker-tagging-best-practices-for-tagging-and-versioning-docker-images/
270273

271274
<!-- LINKS - Internal -->
272275
[az-acr-repository-delete]: /cli/azure/acr/repository#az-acr-repository-delete

0 commit comments

Comments
 (0)