Merge pull request #88015 from dlepow/acrretention

[ACR] Retention policy article

Author: ktoliver

articles/container-registry/TOC.yml

@@ -71,6 +71,8 @@
       items:
       - name: Delete image data - CLI
         href: container-registry-delete.md
+      - name: Retention policy for untagged manifests (preview)
+        href: container-registry-retention-policy.md
       - name: Automatically purge tags and manifests (preview)
         href: container-registry-auto-purge.md
     - name: Upgrade a Classic registry

articles/container-registry/container-registry-concepts.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: container-registry
 ms.topic: article
-ms.date: 07/01/2019
+ms.date: 09/10/2019
 ms.author: danlep
 ---
 
@@ -90,7 +90,7 @@ Each container image or artifact pushed to a container registry is associated wi
 az acr repository show-manifests --name <acrName> --repository <repositoryName>
 ```
 
-For example, list the manifest digests for the "acr-helloworld" repository:
+For example, list the manifests for the "acr-helloworld" repository:
 
 ```console
 $ az acr repository show-manifests --name myregistry --repository acr-helloworld
@@ -133,8 +133,7 @@ $ docker pull myregistry.azurecr.io/acr-helloworld@sha256:0a2e01852872580b2c2fea
 ```
 
 > [!IMPORTANT]
-> If you repeatedly push modified images with identical tags, you might create orphaned images--images that are untagged, but still consume space in your registry. Untagged images are not shown in the Azure CLI or in the Azure portal when you list or view images by tag. However, their layers still exist and consume space in your registry. For information about freeing space used by untagged images, see [Delete container images in Azure Container Registry](container-registry-delete.md).
-
+> If you repeatedly push modified images with identical tags, you might create orphaned images--images that are untagged, but still consume space in your registry. Untagged images are not shown in the Azure CLI or in the Azure portal when you list or view images by tag. However, their layers still exist and consume space in your registry. Deleting an untagged image frees registry space when the manifest is the only one, or the last one, pointing to a particular layer. For information about freeing space used by untagged images, see [Delete container images in Azure Container Registry](container-registry-delete.md).
 
 ## Next steps
 

articles/container-registry/container-registry-content-trust.md

@@ -1,6 +1,6 @@
 ---
 title: Content trust in Azure Container Registry
-description: Learn how enable content trust for your Azure container registry, and push and pull signed images.
+description: Learn how to enable content trust for your Azure container registry, and push and pull signed images.
 services: container-registry
 author: dlepow
 manager: gwallace

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

@@ -255,10 +255,13 @@ if ($enableDelete) {
 }
 ```
 
+
 ## Automatically purge tags and manifests (preview)
 
 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).
 
+Optionally set a [retention policy](container-registry-retention-policy.md) for each registry, to manage untagged manifests. When you enable a retention policy, image manifests in the registry that don't have any associated tags, and the underlying layer data, are automatically deleted after a set period.
+
 ## Next steps
 
 For more information about image storage in Azure Container Registry see [Container image storage in Azure Container Registry](container-registry-storage.md).

articles/container-registry/container-registry-retention-policy.md

@@ -0,0 +1,99 @@
+---
+title: Policy to retain untagged manifests in Azure Container Registry
+description: Learn how to enable a retention policy in your Azure container registry, for automatic deletion of untagged manifests after a defined period.
+services: container-registry
+author: dlepow
+manager: gwallace
+
+ms.service: container-registry
+ms.topic: article
+ms.date: 09/25/2019
+ms.author: danlep
+---
+
+# Set a retention policy for untagged manifests
+
+Azure Container Registry gives you the option to set a *retention policy* for stored image manifests that don't have any associated tags (*untagged manifests*). When a retention policy is enabled, untagged manifests in the registry are automatically deleted after a number of days you set. This feature prevents the registry from filling up with artifacts that aren't needed and helps you save on storage costs. If  the `delete-enabled` attribute of an untagged manifest is set to `false`, the manifest can't be deleted, and the retention policy doesn't apply.
+
+You can use the Azure Cloud Shell or 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` to find the version. If you need to install or upgrade, see [Install Azure CLI][azure-cli].
+
+> [!IMPORTANT]
+> This feature is currently in preview, and some [limitations apply](#preview-limitations). 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).
+
+> [!WARNING]
+> Set a retention policy with care--deleted image data is UNRECOVERABLE. If you have systems that pull images by manifest digest (as opposed to image name), you should not set a retention policy for untagged manifests. 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).
+
+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).
+
+## Preview limitations
+
+* Only a **Premium** container registry can be configured with a retention policy. For information about registry service tiers, see [Azure Container Registry SKUs](container-registry-skus.md).
+* You can only set a retention policy for untagged manifests.
+
+## Set a retention policy - CLI
+
+The following example shows you how to use the Azure CLI to set a retention policy for untagged manifests in a registry.
+
+### Enable a retention policy
+
+By default, no retention policy is set in a container registry. To set or update a retention policy, run the [az acr config retention update][az-acr-config-retention-update] command in the Azure CLI. You can specify a number of days between 0 and 365 to retain the untagged manifests. If you don't specify a number of days, the command sets a default of 7 days. After the retention period, all untagged manifests in the registry are automatically deleted.
+
+The following example sets a retention policy of 30 days for untagged manifests in the registry *myregistry*:
+
+```azurecli
+az acr config retention update --name myregistry --status enabled --days 30 --type UntaggedManifests
+```
+
+The following example sets a policy to delete any manifest in the registry as soon as it's untagged. Create this policy by setting a retention period of 0 days:
+
+```azurecli
+az acr config retention update --name myregistry --status enabled --days 0 --type UntaggedManifests
+```
+
+### Disable a retention policy
+
+To see the retention policy set in a registry, run the [az acr config retention show][az-acr-config-retention-show] command:
+
+```azurecli
+az acr config retention show --name myregistry
+```
+
+To disable a retention policy in a registry, run the [az acr config retention update][az-acr-config-retention-update] command and set `--status disabled`:
+
+```azurecli
+az acr config retention update --name myregistry --status disabled
+```
+
+## Set a retention policy - portal
+
+You can also set a registry's retention policy in the [Azure portal](https://portal.azure.com). The following example shows you how to use the portal to set a retention policy for untagged manifests in a registry.
+
+### Enable a retention policy
+
+1. Navigate to your Azure container registry. Under **Policies**, select **Retention** (Preview).
+1. In **Status**, select **Enabled**.
+1. Select a number of days between 0 and 365 to retain the untagged manifests. Select **Save**.
+
+![Enable a retention policy in Azure portal](media/container-registry-retention-policy/container-registry-retention-policy01.png)
+
+### Disable a retention policy
+
+1. Navigate to your Azure container registry. Under **Policies**, select **Retention** (Preview).
+1. In **Status**, select **Disabled**. Select **Save**.
+
+## Next steps
+
+* Learn more about options to [delete images and repositories](container-registry-delete.md) in Azure Container Registry
+
+* Learn how to [automatically purge](container-registry-auto-purge.md) selected images and manifests from a registry
+
+* Learn more about options to [lock images and manifests](container-registry-image-lock.md) in a registry
+
+<!-- LINKS - external -->
+[terms-of-use]: https://azure.microsoft.com/support/legal/preview-supplemental-terms/
+
+
+<!-- LINKS - internal -->
+[azure-cli]: /cli/azure/install-azure-cli
+[az-acr-config-retention-update]: /cli/azure/acr/config/retention#az-acr-config-retention-update
+[az-acr-config-retention-show]: /cli/azure/acr/config/retention#az-acr-config-retention-show