rough draft

dlepow · dlepow · commit fb663e187dc2 · 2020-04-06T18:43:13.000-07:00
diff --git a/articles/container-registry/container-registry-transfer-images.md b/articles/container-registry/container-registry-transfer-images.md
@@ -2,7 +2,7 @@
 title: Transfer images
 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: 04/03/2020
+ms.date: 04/06/2020
 ms.custom: 
 ---
 
@@ -25,19 +25,16 @@ This feature is available in the **Premium** container registry service tier. Fo
 
 ## Prerequisites
 
-* **Container registries** - For this scenario you need an existing source registry with images to transfer, and a target registry. The source and target registries can be in the same or a different Azure subscription. The steps in this article assume that the registries are 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 subscription or 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. In each account, create a blob container for image transfer. For example, create a container named *transfer*
+* **Container registries** - For this scenario you need an existing source registry with images you want to transfer, and a target registry. The source and target registries can be in the same or a different Azure subscription, Active Directory tenant, or cloud. 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 a subscription and location of your choice. If needed, create the storage accounts with the [Azure CLI](../storage/common/storage-account-create.md?tabs=azure-cli) or other tools. In each account, create a blob container for image transfer. For example, create a container named *transfer*
 * **Key vaults** Create key vaults to store secrets in the same Azure subscription or 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
 
-You create the following three resources for ACR Transfer. All are created using PUT operations. These resources operate on two storage accounts:
+You create the following three resources for ACR Transfer. All are created using PUT operations. These resources operate on your *source* and *target* registries and storage accounts.
 
-* A *source* storage account, where images from the source registry get exported
-* A *target* storage account, from which images are imported to the target registry
-
-* **ExportPipeline** - Long-lasting resource that contains high-level information about the the *source* storage account. This information includes the storage blob container URI and the key vault secret URI of the storage SAS token. 
-* **ImportPipeline** - Long-lasting resource that contains high-level information about the *target* storage account. This information includes the storage blob container URI and the key vault secret URI of the storage SAS token. An import trigger is enabled by default, so the pipeline runs automatically when artifacts land in the target storage container. 
+* **ExportPipeline** - Long-lasting resource that contains high-level information about the *source* registry and storage account. This information includes the storage blob container URI and the key vault secret URI of the storage SAS token. 
+* **ImportPipeline** - Long-lasting resource that contains high-level information about the *target* registry and storage account. This information includes the storage blob container URI and the key vault secret URI of the storage SAS token. An import trigger is enabled by default, so the pipeline runs automatically when artifacts land in the target storage container. 
 * **PipelineRun** Resource used to invoke either an ExportPipeline or ImportPipeline resource.  
 
 You run the ExportPipeline manually by creating a PipelineRun resource. When you run the ExportPipeline, you specify the artifacts to be exported.  
@@ -80,6 +77,12 @@ az keyvault secret set \
   --vault-name sourcekeyvault 
 ```
 
+In the command output, take note of the secret's URI (`id`). You use the URIs in the export pipelines. Example:
+
+```azurecli
+https://sourcekeyvault.vault-int.azure-int.net/secrets/acrexportsas/xxxxxxxxxxxxxxx
+```
+
 ### SAS token for import
 
 Generate a SAS token for import from the target storage account.
@@ -97,6 +100,7 @@ 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 target Azure key vault using [az keyvault secret set][az-keyvault-secret-set] command:
 
@@ -106,12 +110,16 @@ az keyvault secret set \
   --value $IMPORT_SAS \
   --vault-name targetkeyvault 
 ```
+In the command output, take note of the secret's URI (`id`). You use the URI in the import pipeline. Example:
+
+```azurecli
+https://targetkeyvault.vault-int.azure-int.net/secrets/acrimportsas/xxxxxxxxxxxxxxx
+```
 
 ## Create identities 
 
 Create user-assigned managed identities for source and target key vaults by running the [az identity create][az-identity-create] command. 
 
-
 ```azurecli
 # Managed identity for source vault
 az identity create \
@@ -133,15 +141,15 @@ sourcePrincipalID=$(az identity show \
 
 sourceResourceID=$(az identity show \
   --resource-group myResourceGroup \
-  --name myPipelineId --query id --output tsv) 
+  --name sourceId --query id --output tsv) 
 
 targetPrincipalID=$(az identity show \
   --resource-group myResourceGroup \
-  --name sourceId --query principalId --output tsv) 
+  --name targetId --query principalId --output tsv) 
 
 targetResourceID=$(az identity show \
   --resource-group myResourceGroup \
-  --name myPipelineId --query id --output tsv) 
+  --name targetId --query id --output tsv) 
 ```
 
 ## Grant each identity access to key vault 
@@ -152,13 +160,13 @@ Run the [az keyvault set-policy][az-keyvault-set-policy] command to grant the so
 # Source key vault
 az keyvault set-policy --name sourcekeyvault \
   --resource-group myResourceGroup \
-  --object-id $principalID \
+  --object-id $sourcePrincipalID \
   --secret-permissions get
 
 # Target key vault
 az keyvault set-policy --name targetkeyvault \
   --resource-group myResourceGroup \
-  --object-id $principalID \
+  --object-id $targetPrincipalID \
   --secret-permissions get
 ```
 
@@ -170,6 +178,15 @@ Create an ExportPipeline resource for your source container registry using Azure
 
 Copy ExportPipeline Resource Manager template files from [here](add link - TBD).
 
+Enter the following parameter values in the file `azuredeploy.parameters.json`:
+
+|Parameter  |Value  |
+|---------|---------|
+|registryName     | Name of your source container registry      |
+|exportPipelineName     |  Name you choose for the export pipeline       |
+|targetUri     |  URI of the container in your source storage account. Example: `https://sourcestorage.blob.core.windows.net/transfer`       |
+|keyVaultUri     |  URI of the SAS token secret in the source key vault. Example: `https://sourcevault.vault-int.azure-int.net/secrets/acrexportsas`       |
+
 Run [az deployment group create][az-deployment-group-create] to create the resource.
 
 ```azurecli
@@ -179,34 +196,52 @@ az deployment group create \
   --parameters azuredeploy.parameters.json \
   --parameters userAssignedIdentity=$sourceResourceID
 ```
- 
+
+Take note of the resource ID (`id`) of the pipeline, which is used in later steps. Example:
+
+```
+"/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<sourceRegistryName>/exportPipelines/myExportPipeline"
+```
+
 ### Run the ExportPipeline resource 
 
+Create a PipelineRun resource for your source container registry using Azure Resource Manager template deployment. This resource runs the ExportPipeline resource you created in the previous step, and exports specified images from your container registry to your source storage account. As shown in a later step, you can also use a PipelineRun resource to trigger an ImportPipeline for image import to your target container registry.
+
 Copy ExportPipeline Resource Manager template files from [here](add link - TBD).
 
-[Create a list of images to transfer - what is format?]
+Enter the following parameter values in the file `azuredeploy.parameters.json`:
+
+|Parameter  |Value  |
+|---------|---------|
+|registryName     | Name of your source container registry      |
+|pipelineRunName     |  Name you choose for the run       |
+|pipelineResourceId     |  Resource ID of the export pipeline. Example: `/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<sourceRegistryName>/exportPipelines/myExportPipeline`       |
+|targetName     |  Name you choose for the blob for exported artifacts in your source storage account, such a *myblob*
+|artifacts | Array of source images to transfer. Example: `[samples/hello-world:v1", "samples/nginx:v1"]`
 
 Run [az deployment group create][az-deployment-group-create] to run the resource.
 
 ```azurecli
-az group deployment create \ 
+az deployment group create \
   --resource-group myResourceGroup \
   --template-file azuredeploy.json \
   --parameters azuredeploy.parameters.json
 ```
 
+For image export, when prompted, leave the `sourceName` blank. You can also leave `catalogDigest` and `forceUpdateTag` values blank.
+
+When deployment completes successfully, verify image export by viewing the exported blob in the *transfer* container of the source storage account.
+
 ## Transfer blob (optional) 
 
 Use the AzCopy command to copy the blob from the source storage account to the target storage account. See [Copy blobs between storage accounts](/storage/common/storage-use-azcopy-blobs.md#copy-blobs-between-storage-accounts). 
 
-[TODO: What does the AzCopy command look like? Is it the `azcopy sync` shown below?]
-
-The following `azcopy sync` command ynchronizes the transfer containers in the source and target storage accounts:
+For example, the following [`azcopy sync`](/azure/storage/common/storage-ref-azcopy-sync) command synchronizes the *transfer* container from the source storage account with the *transfer* container in the target account. Authentication uses the export and import SAS tokens previously saved in environment variables:
 
 ```console
 azcopy sync \
-  'https://<source-storage-account-name>.blob.core.windows.net/transfer' \
-  'https://<destination-storage-account-name>.blob.core.windows.net/transfer' \
+  'https://<source-storage-account-name>.blob.core.windows.net/transfer/'$EXPORT_SAS \
+  'https://<destination-storage-account-name>.blob.core.windows.net/transfer/'$IMPORT_SAS \
   --recursive 
 ```
 
@@ -218,6 +253,15 @@ Create an ImportPipeline resource in your target container registry using Azure
 
 Copy ImportPipeline Resource Manager template files from [here](add link - TBD).
 
+Enter the following parameter values in the file `azuredeploy.parameters.json`:
+
+Parameter  |Value  |
+|---------|---------|
+|registryName     | Name of your target container registry      |
+|importPipelineName     |  Name you choose for the import pipeline       |
+|sourceUri     |  URI of the container in your target storage account, used as a source for the import pipeline. Example: `https://targetstorage.blob.core.windows.net/transfer`       |
+|keyVaultUri     |  URI of the SAS token secret in the target key vault. Example: `https://targetvault.vault-int.azure-int.net/secrets/acrimportsas`       |
+
 Run [az deployment group create][az-deployment-group-create] to create the resource.
 
 ```azurecli
@@ -228,22 +272,40 @@ az group deployment create \
   --parameters userAssignedIdentity=$targetResourceID 
 ```
 
+When deployment completes successfully, verify image import by listing the repositories in the target container registry.
+
 ### Run the ImportPipeline resource manually (optional) 
  
-Copy ImportPipeline Resource Manager template files from [here](add link - TBD).
+You can also use a PipelineRun resource to trigger an ImportPipeline for image import to your target container registry.
+
+Copy ExportPipeline Resource Manager template files from [here](add link - TBD).
+
+Enter the following parameter values in the file `azuredeploy.parameters.json`:
+
+|Parameter  |Value  |
+|---------|---------|
+|registryName     | Name of your source container registry      |
+|pipelineRunName     |  Name you choose for the run       |
+|pipelineResourceId     |  Resource ID of the import pipeline. Example: `/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<sourceRegistryName>/exportPipelines/myExportPipeline`       |
+|sourceName     |  Name of the blob for exported artifacts in your storage account, such a *myblob*
 
 Run [az deployment group create][az-deployment-group-create] to run the resource.
- 
+
 ```azurecli
-az group deployment create \ 
-  --resource-group myResourceGroup \ 
-  --template-file azuredeploy.json \ 
-  --parameters azuredeploy.parameters.json 
+az deployment group create \
+  --resource-group myResourceGroup \
+  --template-file azuredeploy.json \
+  --parameters azuredeploy.parameters.json
 ```
 
-## Verify image transfer
+For image export, when prompted, leave the `targetName` blank. You can also leave `catalogDigest` and `forceUpdateTag` values blank.
+
+When deployment completes successfully, verify image import by listing the repositories in the target container registry.
+
+## Manage pipeline resources
+
+[TODO: How to delete, etc.]
 
-[TODO]
 
 <!-- LINKS - External -->
 
