Merge pull request #109947 from dlepow/acrcmk

[ACR] CMK GA

Author: denrea

articles/container-registry/TOC.yml

@@ -87,10 +87,12 @@
         href: container-registry-webhook.md
     - name: Security and authentication
       items:
-      - name: Limit access with virtual network (preview)
-        href: container-registry-vnet.md
       - name: Integrate with Azure Private Link (preview)
         href: container-registry-private-link.md
+      - name: Limit access with virtual network (preview)
+        href: container-registry-vnet.md
+      - name: Encrypt with customer-managed key
+        href: container-registry-customer-managed-keys.md
       - name: Access behind a firewall
         href: container-registry-firewall-access-rules.md
       - name: Authentication
@@ -115,8 +117,6 @@
         href: container-registry-content-trust.md
       - name: Image scanning with Security Center
         href: ../security-center/azure-container-registry-integration.md?toc=/azure/container-registry/toc.json&bc=/azure/container-registry/breadcrumb/toc.json
-      - name: Encrypt registry data (preview)
-        href: container-registry-customer-managed-keys.md
     - name: Registries and other Azure services
       expanded: false
       items:

articles/container-registry/container-registry-customer-managed-keys.md

@@ -1,26 +1,23 @@
 ---
-title: Encryption-at-rest with customer-managed keys
+title: Encryption-at-rest with a customer-managed key
 description: Learn about encryption-at-rest of your Azure container registry, and how to encrypt your registry with a customer-managed key stored in Azure Key Vault
 ms.topic: article
-ms.date: 03/10/2020
+ms.date: 05/01/2020
 ms.custom: 
 ---
 
-# Encryption using customer-managed keys
+# Encrypt registry using a customer-managed key
 
 When you store images and other artifacts in an Azure container registry, Azure automatically encrypts the registry content at rest with [service-managed keys](../security/fundamentals/encryption-atrest.md#data-encryption-models). You can supplement default encryption with an additional encryption layer using a key that you create and manage in Azure Key Vault. This article walks you through the steps using the Azure CLI and the Azure portal.
 
-Server-side encryption with customer-managed keys is supported through integration with [Azure Key Vault](../key-vault/general/overview.md). You can create your own encryption keys and store them in a key vault, or you can use Azure Key Vault's APIs to generate encryption keys. With Azure Key Vault, you can also audit key usage.
+Server-side encryption with customer-managed keys is supported through integration with [Azure Key Vault](../key-vault/general/overview.md). You can create your own encryption keys and store them in a key vault, or use Azure Key Vault's APIs to generate keys. With Azure Key Vault, you can also audit key usage.
 
 This feature is available in the **Premium** container registry service tier. For information about registry service tiers and limits, see [Azure Container Registry SKUs](container-registry-skus.md).
 
-> [!IMPORTANT]
-> This feature is currently in preview, and some [limitations](#preview-limitations) apply. 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).
->
 
-## Preview limitations 
+## Things to know
 
-* You can currently enable this feature only when you create a registry.
+* You can currently enable a customer-managed key only when you create a registry.
 * After enabling a customer-managed key on a registry, you can't disable it.
 * [Content trust](container-registry-content-trust.md) is currently not supported in a registry encrypted with a customer-managed key.
 * In a registry encrypted with a customer-managed key, run logs for [ACR Tasks](container-registry-tasks-overview.md) are currently retained for only 24 hours. If you need to retain logs for a longer period, see guidance to [export and store task run logs](container-registry-tasks-logs.md#alternative-log-storage).
@@ -135,12 +132,15 @@ In the command output, take note of the key's ID, `kid`. You use this ID in the
 For convenience, store this value in an environment variable:
 
 ```azurecli
-keyID=$(az keyvault key show --name <keyname> --vault-name <key-vault-name> --query 'key.kid' --output tsv)
+keyID=$(az keyvault key show \
+  --name <keyname> \
+  --vault-name <key-vault-name> \
+  --query 'key.kid' --output tsv)
 ```
 
 ### Create a registry with customer-managed key
 
-Run the [az acr create][az-acr-create] command to create a registry and enable the customer-managed key. Pass the managed identity principal ID and the key ID, stored previously in environment variables:
+Run the [az acr create][az-acr-create] command to create a registry in the Premium service tier and enable the customer-managed key. Pass the managed identity principal ID and the key ID, stored previously in environment variables:
 
 ```azurecli
 az acr create \
@@ -159,21 +159,34 @@ To show whether registry encryption with a customer-managed key is enabled, run
 az acr encryption show --name <registry-name> 
 ```
 
+Output is similar to:
+
+```console
+{
+  "keyVaultProperties": {
+    "identity": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "keyIdentifier": "https://myvault.vault.azure.net/keys/myresourcegroup/abcdefg123456789...",
+    "versionedKeyIdentifier": "https://myvault.vault.azure.net/keys/myresourcegroup/abcdefg123456789..."
+  },
+  "status": "enabled"
+}
+```
+
 ## Enable customer-managed key - portal
 
 ### Create a managed identity
 
 Create a user-assigned [managed identity for Azure resources](../active-directory/managed-identities-azure-resources/overview.md) in the Azure portal. For steps, see [Create a user-assigned identity](../active-directory/managed-identities-azure-resources/how-to-manage-ua-identity-portal.md#create-a-user-assigned-managed-identity).
 
-Take note of the **Resource Name** of the managed identity. You need this name in later steps.
+You use the identity's name in later steps.
 
 ![Create user-assigned managed identity in the Azure portal](./media/container-registry-customer-managed-keys/create-managed-identity.png)
 
 ### Create a key vault
 
 For steps to create a key vault, see [Quickstart: Set and retrieve a secret from Azure Key Vault using the Azure portal](../key-vault/secrets/quick-create-portal.md).
 
-When creating a key vault for a customer-managed key, in the **Basics** tab, you must enable the following protection settings: **Soft delete** and **Purge protection**. These settings help prevent data loss caused by accidental key or key vault deletions.
+When creating a key vault for a customer-managed key, in the **Basics** tab, enable the following protection settings: **Soft delete** and **Purge protection**. These settings help prevent data loss caused by accidental key or key vault deletions.
 
 ![Create key vault in the Azure portal](./media/container-registry-customer-managed-keys/create-key-vault.png)
 
@@ -203,14 +216,14 @@ Configure a policy for the key vault so that the identity can access it.
 1. In the **Basics** tab, select or create a resource group, and enter a registry name. In **SKU**, select **Premium**.
 1. In the **Encryption** tab, in **Customer-managed key**, select **Enabled**.
 1. In **Identity**, select the managed identity you created.
-1. In **Encryption key**, select **Select from Key Vault**.
+1. In **Encryption**, select **Select from Key Vault**.
 1. In the **Select key from Azure Key Vault** window, select the key vault, key, and version you created in the preceding section.
 1. In the **Encryption** tab, select **Review + create**.
 1. Select **Create** to deploy the registry instance.
 
 ![Create container registry in the Azure portal](./media/container-registry-customer-managed-keys/create-encrypted-registry.png)
 
-To see the encryption status of your registry in the portal, navigate to your registry. Under **Settings**, select  **Encryption (Preview)**.
+To see the encryption status of your registry in the portal, navigate to your registry. Under **Settings**, select  **Encryption**.
 
 ## Enable customer-managed key - template
 
@@ -342,38 +355,75 @@ az group deployment create \
 
 ### Show encryption status
 
-To show the status of registry encryption, run the [az acr encryption show-status][az-acr-encryption-show-status] command:
+To show the status of registry encryption, run the [az acr encryption show][az-acr-encryption-show] command:
 
 ```azurecli
-az acr encryption show-status --name <registry-name> 
+az acr encryption show --name <registry-name> 
 ```
 
 ## Use the registry
 
-After you enable a registry to encrypt data using a customer-managed key, you can perform the same registry operations that you perform in a registry that's not encrypted with a customer-managed key. For example, you can authenticate with the registry and push Docker images. See example commands in [Push and pull an image](container-registry-get-started-docker-cli.md).
+After enabling a customer-managed key in a registry, you can perform the same registry operations that you perform in a registry that's not encrypted with a customer-managed key. For example, you can authenticate with the registry and push Docker images. See example commands in [Push and pull an image](container-registry-get-started-docker-cli.md).
 
 ## Rotate key
 
-You can rotate a customer-managed key in Azure Key Vault according to your compliance policies. Create a new key, and then update the registry to encrypt data using the new key. You can perform these steps using the Azure CLI or in the portal.
+Rotate a customer-managed key used for registry encryption to your compliance policies. Create a new key, or update a key version, and then update the registry to encrypt data using the key. You can perform these steps using the Azure CLI or in the portal.
+
+When rotating a key, typically you specify the same identity used when creating the registry. Optionally, configure a new user-assigned identity for key access, or enable and specify the registry's system-assigned identity.
+
+> [!NOTE]
+> Ensure that the required [key vault access policy](#add-key-vault-access-policy) is set for the identity you configure for key access. 
+
+### Azure CLI
 
-For example, run the [az keyvault key create][az-keyvault-key-create] command to create a new key:
+Use [az keyvault key][az-keyvault-key] commands to create or manage your key vault keys. For example, to create a new key version or key, run the [az keyvault key create][az-keyvault-key-create] command:
 
 ```azurecli
-az keyvault key create –-name <new-key-name> --vault-name <key-vault-name> 
+# Create new version of existing key
+az keyvault key create \
+  –-name <key-name> \
+  --vault-name <key-vault-name> 
+
+# Create new key
+az keyvault key create \
+  –-name <new-key-name> \
+  --vault-name <key-vault-name> 
 ```
 
-Then run the [az acr encryption rotate-key][az-acr-encryption-rotate-key] command, passing the new key ID and the principal ID of the managed identity you previously configured:
+Then run the [az acr encryption rotate-key][az-acr-encryption-rotate-key] command, passing the new key ID and the identity you want to configure:
 
 ```azurecli
-az acr encryption rotatekey \
+# Rotate key and use user-assigned identity
+az acr encryption rotate-key \
   --name <registry-name> \
   --key-encryption-key <new-key-id> \
-  --identity $identityPrincipalID
+  --identity <principal-id-user-assigned-identity>
+
+# Rotate key and use system-assigned identity
+az acr encryption rotate-key \
+  --name <registry-name> \
+  --key-encryption-key <new-key-id> \
+  --identity [system]
 ```
 
+### Portal
+
+Use the registry's **Encryption** settings to update the key version, key, key vault, or identity settings used for the customer-managed key. 
+
+For example, to generate and configure a new key version:
+
+1. In the portal, navigate to your registry. 
+1. Under **Settings**, select  **Encryption** > **Change key**.
+1. Select **Select key**
+    
+    ![Rotate key in the Azure portal](./media/container-registry-customer-managed-keys/rotate-key.png)
+1. In the **Select key from Azure Key Vault** window, select the key vault and key you configured previously, and in **Version**, select **Create new**.
+1. In the **Create a key** window, select **Generate**, and then **Create**.
+1. Complete the key selection and select **Save**.
+
 ## Revoke key
 
-Revoke the customer-managed encryption key by changing the access policy on the key vault or by deleting the key. For example, use the [az keyvault delete-policy][az-keyvault-delete-policy] command to change the access policy of the managed identity used by your registry. For example:
+Revoke the customer-managed encryption key by changing the access policy on the key vault or by deleting the key. For example, use the [az keyvault delete-policy][az-keyvault-delete-policy] command to change the access policy of the managed identity used by your registry:
 
 ```azurecli
 az keyvault delete-policy \
@@ -384,15 +434,49 @@ az keyvault delete-policy \
 
 Revoking the key effectively blocks access to all registry data, since the registry can't access the encryption key. If access to the key is enabled or the deleted key is restored, your registry will pick the key so you can again access the encrypted registry data.
 
+## Advanced scenarios
+
+### System-assigned identity
+
+You can configure a registry's system-assigned managed identity to access the key vault for encryption keys. If you're unfamiliar with the different managed identities for Azure resources, see the [overview](../active-directory/managed-identities-azure-resources/overview.md).
+
+To enable the registry's system-assigned identity in the portal:
+
+1. In the portal, navigate to your registry. 
+1. Select **Settings** >  **Identity**.
+1. Under **System assigned**, set **Status** to **On**. Select **Save**.
+1. Copy the **Object ID** of the identity.
+
+To grant the identity access to your key vault:
+
+1. Navigate to your key vault.
+1. Select **Settings** > **Access policies > +Add Access Policy**.
+1. Select **Key permissions**, and select **Get**, **Unwrap Key**, and **Wrap Key**.
+1. Select **Select principal** and search for the object ID of your system-assigned managed identity, or the name of your registry.  
+1. Select **Add**, then select **Save**.
+
+To update the registry's encryption settings to use the identity:
+
+1. In the portal, navigate to your registry. 
+1. Under **Settings**, select  **Encryption** > **Change key**.
+1. In **Identity**, select **System assigned**, and select **Save**.
+
+### Key Vault firewall
+
+If your Azure key vault is deployed in a virtual network with a Key Vault firewall, perform the following steps:
+
+1. Configure registry encryption to use the registry's system-assigned identity. See the preceding section.
+2. Configure the key vault to allow access by any [trusted service](../key-vault/general/overview-vnet-service-endpoints.md#trusted-services). 
+
+For detailed steps, see [Configure Azure Key Vault firewalls and virtual networks](../key-vault/general/network-security.md). 
+
 ## Next steps
 
 * Learn more about [encryption at rest in Azure](../security/fundamentals/encryption-atrest.md).
 * Learn more about access policies and how to [secure access to a key vault](../key-vault/general/secure-your-key-vault.md).
-* To provide feedback on customer-managed keys for Azure Container Registry, visit the [ACR GitHub site](https://aka.ms/acr/issues).
 
 
 <!-- LINKS - external -->
-[terms-of-use]: https://azure.microsoft.com/support/legal/preview-supplemental-terms
 
 <!-- LINKS - internal -->
 
@@ -404,6 +488,7 @@ Revoking the key effectively blocks access to all registry data, since the regis
 [az-group-deployment-create]: /cli/azure/group/deployment#az-group-deployment-create
 [az-keyvault-create]: /cli/azure/keyvault#az-keyvault-create
 [az-keyvault-key-create]: /cli/azure/keyvault/key#az-keyvault-key-create
+[az-keyvault-key]: /cli/azure/keyvault/key
 [az-keyvault-set-policy]: /cli/azure/keyvault#az-keyvault-set-policy
 [az-keyvault-delete-policy]: /cli/azure/keyvault#az-keyvault-delete-policy
 [az-resource-show]: /cli/azure/resource#az-resource-show

articles/container-registry/media/container-registry-customer-managed-keys/rotate-key.png

@@ -73,6 +73,7 @@ Here's a list of trusted services that are allowed to access a key vault if the
 |Azure Event Hubs|[Allow access to a key vault for customer-managed keys scenario](https://docs.microsoft.com/azure/event-hubs/configure-customer-managed-key)|
 |Azure Service Bus|[Allow access to a key vault for customer-managed keys scenario](https://docs.microsoft.com/azure/service-bus-messaging/configure-customer-managed-key)|
 |Azure Import/Export| [Use customer-managed keys in Azure Key Vault for Import/Export service](https://docs.microsoft.com/azure/storage/common/storage-import-export-encryption-key-portal)
+|Azure Container Registry|[Registry encryption using customer-managed keys](../../container-registry/container-registry-customer-managed-keys.md)
 
 > [!NOTE]
 > You must set up the relevant Key Vault access policies to allow the corresponding services to get access to Key Vault.