work in progress

dlepow · dlepow · commit 4bc4b1c3dd41 · 2020-04-03T11:00:52.000-07:00
diff --git a/articles/container-registry/container-registry-transfer-images.md b/articles/container-registry/container-registry-transfer-images.md
@@ -1,39 +1,49 @@
 ---
 title: Transfer images
-description: You learn how to ...
+description: Transfer images in bulk from one container registry to another registry by creating a transfer pipeline using Azure storage accounts
 ms.topic: article
 ms.date: 03/31/2020
 ms.custom: 
 ---
 
 # Transfer images to another registry
 
-[Intro]
+This article shows how to transfer images or other registry artifacts in bulk from one Azure container registry to another registry. The source and target registries can be in the same or different subscriptions, or potentially in different Active Directory tenants or Azure clouds. 
 
-If you'd like to use the Azure CLI locally, you must have Azure CLI version **XXX** or later installed  and logged in with [az login][az-login]. Run `az --version` to find the version. If you need to install or upgrade the CLI, see [Install Azure CLI][azure-cli].
+To transfer images, you create a transfer *pipeline*:
+
+* Create source and target storage resources, and store storage access secrets in Azure key vaults 
+* Create and run a registry resource to export images to the source storage account 
+* Copy images from the source storage account to the target storage account
+* Create a registry resource to import images to the target registry. You can set up the import pipeline to trigger whenever images are in the source storage account
+
+Transferring registry images offers a more general, scalable alternative to [importing images](container-registry-import-images.md) from one container registry to another.
+
+In this article, you use the Azure CLI and Azure Resource Manager templates to create the resources and transfer pipeline. If you'd like to use the Azure CLI locally, you must have Azure CLI version **XXX** or later installed and logged in with [az login][az-login]. Run `az --version` to find the version. If you need to install or upgrade the CLI, see [Install Azure CLI][azure-cli].
+
+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).
 
 
 ## Prerequisites
 
-* **Storage accounts** - Create source and target storage accounts. If needed, create the storage accounts with the [Azure CLI](../storage/common/storage-account-create.md?tabs=azure-cli) or other tools. The source and target storage accounts can be in the same or a different Azure subscription. For the steps in article, the accounts must be in the same Active Directory tenant.
-* **Key vault** for storing secrets - If needed, create a key vault with the [Azure CLI](../key-vault/quick-create-cli.md) or other tools
 * **Container registries** - For this scenario you need an existing source registry with images to transfer, and a target registry. The source and target registry can be in the same or a different Azure subscription. For the steps in article, the registries must be in the same Active Directory tenant. If you need to create a registry, see [Quickstart: Create a private container registry using the Azure CLI](container-registry-get-started-cli.md). 
+* **Storage accounts** - Create source and target storage accounts in the same Azure subscriptions as your source and target registries. If needed, create the storage accounts with the [Azure CLI](../storage/common/storage-account-create.md?tabs=azure-cli) or other tools.
+
+  [TODO: Needed to create source and target blob containers??]
+
+* **Key vaults** Create key vaults to store secrets in the same Azure subscriptions as your source and target registries. If needed, create source and target key vaults with the [Azure CLI](../key-vault/quick-create-cli.md) or other tools.
 
 ## Scenario overview
 
-The following three resources are used for ACR Transfer. All are created using PUT operations. 
+You create the following three resources for ACR Transfer. All are created using PUT operations. 
 
-* **ExportPipeline** - Long lasting resource that contains high level target info, such as storage blob container URI and the KV secret URI of the target storage SAS token. 
+* **ExportPipeline** - Long-lasting resource that contains high level target information, such as storage blob container URI and the key vault secret URI of the target storage SAS token. 
 * **ImportPipeline** - Long lasting resource that contains high level source info, such as storage blob container URI and the KV secret URI of the source storage SAS token. Source trigger is enabled by default so the pipeline will run automatically when artifacts land in the source storage container. 
 * **PipelineRun** Resource used to invoke either an ExportPipeline or ImportPipeline resource.  
 
-An ExportPipeline must be run manualIly by creating a PipelineRun resource. When you run the ExportPipeline, you specify the artifacts to be exported.  
+An ExportPipeline must be run manually by creating a PipelineRun resource. When you run the ExportPipeline, you specify the artifacts to be exported.  
 
-An ImportPipeline configured with source trigger enabled is run automatically. It can also be run manually using a PipelineRun. 
-
-### Assumptions for this article
-* The export and import SAS tokens are located in the same key vault, and a user-assigned identity is shared between export and import. 
-* The source and target registries and storage accounts are in the same tenant.
+If a source trigger is enabled, an ImportPipeline runs automatically. It can also be run manually using a PipelineRun. 
 
 ### Alternate scenarios
 * The ImportPipeline and ExportPipeline may be located in different tenants. In this case, you need separate managed identities and key vaults for the export and import resources.
@@ -43,6 +53,8 @@ An ImportPipeline configured with source trigger enabled is run automatically. I
 
 Transfer uses shared access signature (SAS) tokens to export to and import from storage accounts. The properties required to create SAS tokens are detailed below.  
 
+[TODO: Create containers, generate tokens at container level?]
+
 ### SAS token for export
 
 Generate a SAS token for export in the source storage account.
@@ -62,13 +74,13 @@ Copy the generated SAS token and use it to set the EXPORT_SAS environment variab
 EXPORT_SAS='?sv=2019-02-02&...'
 ```
 
-Store the SAS token in your Azure key vault using [az keyvault secret set][az-keyvault-secret-set]:
+Store the SAS token in your source Azure key vault using [az keyvault secret set][az-keyvault-secret-set]:
 
 ```azurecli
 az keyvault secret set \
   --name acrexportsas \
   --value $EXPORT_SAS \
-  --vault-name mykeyvault 
+  --vault-name sourcekeyvault 
 ```
 
 ### SAS token for import
@@ -89,44 +101,65 @@ Copy the generated SAS token and use it to set the IMPORT_SAS environment variab
 ```console
 IMPORT_SAS='?sv=2019-02-02&...'
 
-Store the SAS token in your Azure key vault using [az keyvault secret set][az-keyvault-secret-set]:
+Store the SAS token in your target Azure key vault using [az keyvault secret set][az-keyvault-secret-set]:
 
 ```azurecli
 az keyvault secret set \
   --name acrimportsas \
   --value $IMPORT_SAS \
-  --vault-name mykeyvault 
+  --vault-name targetkeyvault 
 ```
 
-## Create identity 
+## Create identities 
+
+Create user-assigned managed identities for source and target key vaults by running the [az identity create][az-identity-create] command. 
 
-Create the user-assigned managed identity by running the [az identity create][az-identity-create] command. 
 
- 
 ```azurecli
+# Managed identity for source vault
 az identity create \
   --resource-group myResourceGroup \
-  --name myPipelineId  
+  --name sourceId  
+
+# Managed identity for target vault
+az identity create \
+  --resource-group myResourceGroup \
+  --name targetId 
 ```
 
 Set the following variables using the [az identity show][az-identity-show] command:
 
 ```azurecli
-principalID=$(az identity show \
+sourcePrincipalID=$(az identity show \
   --resource-group myResourceGroup \
-  --name myPipelineId --query principalId --output tsv) 
+  --name sourceId --query principalId --output tsv) 
 
-resourceID=$(az identity show \
+sourceResourceID=$(az identity show \
+  --resource-group myResourceGroup \
+  --name myPipelineId --query id --output tsv) 
+
+targetPrincipalID=$(az identity show \
+  --resource-group myResourceGroup \
+  --name sourceId --query principalId --output tsv) 
+
+targetResourceID=$(az identity show \
   --resource-group myResourceGroup \
   --name myPipelineId --query id --output tsv) 
 ```
 
-## Grant the identity access to key vault 
+## Grant each identity access to key vault 
 
-Run the [az keyvault set-policy][az-keyvault-set-policy] command to grant the identity access to your key vault:
+Run the [az keyvault set-policy][az-keyvault-set-policy] command to grant each identity access to the respective key vault:
 
 ```azurecli
-az keyvault set-policy --name mykeyvault \
+# Source key vault
+az keyvault set-policy --name sourcekeyvault \
+  --resource-group myResourceGroup \
+  --object-id $principalID \
+  --secret-permissions get
+
+# Target key vault
+az keyvault set-policy --name targetkeyvault \
   --resource-group myResourceGroup \
   --object-id $principalID \
   --secret-permissions get
@@ -154,6 +187,8 @@ az deployment group create \
 
 Copy ExportPipeline Resource Manager template files from [here](add link - TBD).
 
+[Create a list of images to transfer - what is format?]
+
 Run [az deployment group create][az-deployment-group-create] to run the resource.
 
 ```azurecli
@@ -163,13 +198,20 @@ az group deployment create \
   --parameters azuredeploy.parameters.json
 ```
 
-[How to specify the artifacts?]
-
 ## Transfer blob (optional) 
 
 Copy the blob to the target storage account using the AzCopy command. See [Copy blobs between storage accounts](/storage/common/storage-use-azcopy-blobs.md#copy-blobs-between-storage-accounts). 
 
-[What does the AzCopy command look like?]
+[TODO: What does the AzCopy command look like? Is it the `azcopy sync` shown below?]
+
+Synchronize the source and target storage containers:
+
+```console
+azcopy sync \
+  'https://<source-storage-account-name>.blob.core.windows.net/<container-name>' \
+  'https://<destination-storage-account-name>.blob.core.windows.net/<container-name>' \
+  --recursive 
+```
 
 ## Import 
 
@@ -202,6 +244,9 @@ az group deployment create \
   --parameters azuredeploy.parameters.json 
 ```
 
+## Verify image transfer
+
+[TODO]
 
 <!-- LINKS - External -->
 
