Recover deleted artifacts with soft delete policy in Azure Container Registry (Preview)

Article
10/28/2024

Azure Container Registry (ACR) allows you to enable the soft delete policy to recover any accidentally deleted artifacts for a set retention period.

Diagram of soft delete artifacts lifecycle.

Aspects of soft delete policy

The soft delete policy can be enabled/disabled at any time. Once you enable the soft-delete policy in ACR, it manages the deleted artifacts as soft deleted artifacts with a set retention period. Thereby you have ability to list, filter, and restore the soft deleted artifacts.

Retention period

The default retention period for soft deleted artifacts is seven days, but it's possible to set the retention period value between one to 90 days. You can set, update, and change the retention policy value. The soft deleted artifacts expire once the retention period is complete.

Autopurge

The autopurge runs every 24 hours and always considers the current value of retention days before permanently deleting the soft deleted artifacts. For example, after five days of soft deleting the artifact, if you change the value of retention days from seven to 14 days, the artifact will only expire after 14 days from the initial soft delete.

Availability and pricing information

This feature is available in all the service tiers (also known as SKUs). For information about registry service tiers, see Azure Container Registry service tiers.

Note

The soft deleted artifacts are billed as per active sku pricing for storage.

Preview limitations

Important

The soft delete policy is currently in PREVIEW. See the Supplemental Terms of Use for Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

ACR currently doesn't support manually purging soft deleted artifacts.
The soft delete policy doesn't support a geo-replicated registry.
ACR doesn't allow enabling both the retention policy and the soft delete policy. See retention policy for untagged manifests.

Prerequisites

The user requires following permissions (at registry level) to perform soft delete operations:

Permission	Description
Microsoft.ContainerRegistry/registries/deleted/read	List soft-deleted artifacts
Microsoft.ContainerRegistry/registries/deleted/restore/action	Restore soft-deleted artifact

You can use a local installation of the Azure CLI to run the command examples in this article. If you'd like to use it locally, version 2.0.74 or later is required. Run az --version for the version. If you need to install or upgrade, see Install Azure CLI.

Enable soft delete policy for registry - CLI

Update soft delete policy for a given MyRegistry ACR with a retention period set between 1 to 90 days.
```
az acr config soft-delete update -r MyRegistry --days 7 --status <enabled/disabled>
```
Show configured soft delete policy for a given MyRegistry ACR.
```
az acr config soft-delete show -r MyRegistry
```

List the soft deleted artifacts- CLI

The az acr repository list-deleted commands enable fetching and listing of the soft deleted repositories. For more information use --help.

List the soft deleted repositories in a given MyRegistry ACR.
```
az acr repository list-deleted -n MyRegistry
```

The az acr manifest list-deleted commands enable fetching and listing of the soft delete manifests.

List the soft deleted manifests of a hello-world repository in a given MyRegistry ACR.
```
az acr manifest list-deleted -r MyRegistry -n hello-world
```

The az acr manifest list-deleted-tags commands enable fetching and listing of the soft delete tags.

List the soft delete tags of a hello-world repository in a given MyRegistry ACR.
```
az acr manifest list-deleted-tags -r MyRegistry -n hello-world
```
Filter the soft delete tags of a hello-world repository to match tag latest in a given MyRegistry ACR.
```
az acr manifest list-deleted-tags -r MyRegistry -n hello-world:latest
```

Restore the soft deleted artifacts - CLI

The az acr manifest restore commands restore a single image by tag and digest.

Restore the image of a hello-world repository by tag latestand digest sha256:abc123 in a given MyRegistry ACR.
```
az acr manifest restore -r MyRegistry -n hello-world:latest -d sha256:abc123
```
Restore the most recently deleted manifest of a hello-world repository by tag latest in a given MyRegistry ACR.
```
az acr manifest restore -r MyRegistry -n hello-world:latest
```
Force restore overwrites the existing tag with the same name in the repository. If the soft delete policy is enabled during force restore. The overwritten tag is soft deleted. You can force restore with specific arguments --force, -f.
Force restore the image of a hello-world repository by tag latestand digest sha256:abc123 in a given MyRegistry ACR.
```
az acr manifest restore -r MyRegistry -n hello-world:latest -d sha256:abc123 -f
```

Important

Restoring a manifest list won't recursively restore any underlying soft deleted manifests. If you're restoring soft deleted ORAS artifacts, then restoring a subject doesn't recursively restore the referrer chain. Also, the subject has to be restored first, only then a referrer manifest is allowed to restore. Otherwise it throws an error.

Enable soft delete policy for registry - Portal

You can also enable a registry's soft delete policy in the Azure portal.

Navigate to your Azure Container Registry.
In the Overview tab, verify the status of the Soft Delete (Preview).
If the Status is Disabled, Select Update.
Select the checkbox to Enable Soft Delete.
Select the number of days between 0 and 90 days for retaining the soft deleted artifacts.
Select Save to save your changes.

Restore the soft deleted artifacts - Portal

Navigate to your Azure Container Registry.
In the Menu section, Select Services, and Select Repositories.
In the Repositories, Select your preferred Repository.
Select on the Manage deleted artifacts to see all the soft deleted artifacts.

Note

Once you enable the soft delete policy and perform actions such as untag a manifest or delete an artifact, You will be able to find these tags and artifacts in the Managed delete artifacts before the number of retention days expire.
Filter the deleted artifact you have to restore.
Select the artifact, and select on the Restore in the right column.
A Restore Artifact window pops up.
Select the tag to restore, here you have an option to choose, and recover any additional tags.
Select on Restore.

Restore from soft deleted repositories - Portal

Navigate to your Azure Container Registry.
In the Menu section, Select Services,
In the Services tab, Select Repositories.
In the Repositories tab, select on Manage Deleted Repositories.
Filter the deleted repository in the Soft Deleted Repositories(Preview).
Select the deleted repository, filter the deleted artifact from on the Manage deleted artifacts.
Select the artifact, and select on the Restore in the right column.
A Restore Artifact window pops up.
Select the tag to restore, here you have an option to choose, and recover any other tags.
Select on Restore.

Important

Importing a soft deleted image at both source and target resources is blocked. Pushing an image to the soft deleted repository will restore the soft deleted repository. Pushing an image that shares a same manifest digest with the soft deleted image is not allowed. Instead restore the soft deleted image.