Merge pull request #234427 from fauhse/cmode

GA updates for creating a job definition

Author: prmerger-automator[bot]

articles/storage-mover/billing.md

@@ -10,7 +10,6 @@ ms.date: 03/22/2023
 
 <!-- 
 !########################################################
-STATUS: IN REVIEW
 
 CONTENT: final (85/100)
 

articles/storage-mover/job-definition-create.md

@@ -25,7 +25,7 @@ Initial doc score: 100 (1532 words and 0 issues)
 
 # How to define and start a migration job
 
-When you migrate a share to Azure, you'll need to describe the source share, the Azure target, and any migration settings you want to apply. These attributes are defined in a job definition within your storage mover resource. This article describes how to create and run such a job definition.
+When you migrate a share to Azure, you need to describe the source share, the Azure target, and any migration settings you want to apply. These attributes are defined in a job definition within your storage mover resource. This article describes how to create and run such a job definition.
 
 ## Prerequisites
 
@@ -37,8 +37,8 @@ There are three prerequisites to the definition the migration of your source sha
    Follow the steps in the *[Create a storage mover resource](storage-mover-create.md)* article to deploy a storage mover resource to the desired region within your Azure subscription.
 1. You need to deploy and register an Azure Storage Mover agent virtual machine (VM).
    Follow the steps in the [Azure Storage Mover agent VM deployment](agent-deploy.md) and [agent registration](agent-register.md) articles to deploy at least one agent.
-1. Finally, to define a migration, you'll need to create a job definition.
-   Job definitions are organized in a migration project. You'll need at least one migration project in your storage mover resource. If you haven't already, follow the deployment steps in the [manage projects](project-manage.md) article to create a migration project.
+1. Finally, to define a migration, you need to create a job definition.
+   Job definitions are organized in a migration project. You need at least one migration project in your storage mover resource. If you haven't already, follow the deployment steps in the [manage projects](project-manage.md) article to create a migration project.
 
 ## Create and start a job definition
 
@@ -74,9 +74,10 @@ Refer to the [resource naming convention](../azure-resource-manager/management/r
 
    :::image type="content" source="media/job-definition-create/endpoint-source-new-sml.png" alt-text="Screen capture of the Source tab illustrating the location of the New Source Endpoint fields." lightbox="media/job-definition-create/endpoint-source-new-lrg.png":::
 
-   By default, migration jobs will start from the root of your share. However, if your use case involves copying data from a specific path within your source share, you can provide the path in the **Sub-path** field. Supplying this value will start the data migration from the location you've specified. If the sub path you've specified isn't found, no data will be copied.
+   <a name="sub-path"></a>
+   By default, migration jobs start from the root of your share. However, if your use case involves copying data from a specific path within your source share, you can provide the path in the **Sub-path** field. Supplying this value will start the data migration from the location you've specified. If the sub path you've specified isn't found, no data will be copied.
 
-   Prior to creating an endpoint and a job resource, it's important to verify that the path you've provided is correct and that the data is accessible. You're unable to modify endpoints or job resources after they're created. If the specified path is wrong, you'll need to delete the resources and re-create them.
+   Prior to creating an endpoint and a job resource, it's important to verify that the path you've provided is correct and that the data is accessible. You're unable to modify endpoints or job resources after they're created. If the specified path is wrong, your only option is to delete the resources and re-create them.
 
    Values for host, share name, and subpath are concatenated to form the full migration source path. The path is displayed in the **Full path** field within the **Verify full path** section. Copy the path provided and verify that you're able to access it before committing your changes.
 
@@ -92,19 +93,26 @@ Refer to the [resource naming convention](../azure-resource-manager/management/r
 
    :::image type="content" source="media/job-definition-create/endpoint-target-new-sml.png" alt-text="Screen capture of the Target tab illustrating the location of the New Target Endpoint fields." lightbox="media/job-definition-create/endpoint-target-new-lrg.png":::
 
-   A target subpath value can be used to specify a location within the target container where your migrated data will be copied. The subpath value is relative to the container's root. Omitting the subpath value will result in the data being copied to the root, while providing a unique value will generate a new subfolder.
+   A target subpath value can be used to specify a location within the target container where your migrated data will be copied. The subpath value is relative to the container's root. Omitting the subpath value results in the data being copied to the root, while providing a unique value will generate a new subfolder.
 
    After ensuring the accuracy of your settings, select **Next** to continue.
 
-1. Within the **Settings** tab, take note of the settings associated with the **Copy mode** and **Migration outcomes**. The service's **copy mode** will affect the behavior of the migration engine when files or folders change between copy iterations.
+1. Within the **Settings** tab, take note of the settings associated with the **Copy mode** and **Migration outcomes**. The service's **copy mode** affects the behavior of the migration engine when files or folders change between copy iterations.
 
-   The current release of Azure Storage Mover only supports **merge** mode.
+   <a name="copy-modes"></a>
+   **Merge source into target:**
 
    - Files will be kept in the target, even if they don’t exist in the source.
    - Files with matching names and paths will be updated to match the source.
-   - Folder renames between copies may lead to duplicate content in the target.
+   - File or folder renames between copies lead to duplicate content in the target.
+   
+   **Mirror source to target:**
 
-   **Migration outcomes** are based upon the specific storage types of the source and target endpoints. For example, because blob storage only supports "virtual" folders, source files in folders will have their paths prepended to their names and placed in a flat list within a blob container. Empty folders will be represented as an empty blob in the target. Source folder metadata will be persisted in the custom metadata field of a blob, as they are with files.
+   - Files in the target will be deleted if they don’t exist in the source.
+   - Files and folders in the target will be updated to match the source.   
+   - File or folder renames between copies won't lead to duplicate content. A renamed item on the source side leads to the deletion of the item with the original name in the target. Additionally, the renamed item is also uploaded to the target. If the renamed item is a folder, the described behavior of delete and reupload applies to all files and folders contained in it. Avoid renaming folders during a migration, especially near the root level of your source data.
+
+   **Migration outcomes** are based upon the specific storage types of the source and target endpoints. For example, because blob storage only supports "virtual" folders, source files in folders will have their paths prepended to their names and placed in a flat list within a blob container. Empty folders will be represented as an empty blob in the target. Source folder metadata is persisted in the custom metadata field of a blob, as they are with files.
 
    After viewing the effects of the copy mode and migration outcomes, select **Next** to review the values from the previous tabs.
 
@@ -114,7 +122,7 @@ Refer to the [resource naming convention](../azure-resource-manager/management/r
 
 ### [PowerShell](#tab/powershell)
 
-You'll need to use several cmdlets to create a new job definition.
+You need to use several cmdlets to create a new job definition.
 
 Use the `New-AzStorageMoverJobDefinition` cmdlet to create new job definition resource in a project. The following example assumes that you aren't reusing *storage endpoints* you've previously created.
 
@@ -170,7 +178,8 @@ New-AzStorageMoverAzStorageContainerEndpoint `
 $projectName        = "Your project name"
 $jobDefName         = "Your job definition name"
 $JobDefDescription  = "Optional, up to 1024 characters"
-$jobDefCopyMode     = "Additive"
+$jobDefCopyMode     = "Additive" # Merges source into target. See description in portal tab.
+#$jobDefCopyMode    = "Mirror" # Mirrors source into target. See description in portal tab.
 $agentName          = "The name of an agent previously registered to the same storage mover resource"
 
 
@@ -191,6 +200,6 @@ New-AzStorageMoverJobDefinition `
 
 ## Next steps
 
-Now that you've created a job definition with source and target endpoints, learn how to estimate the time required to perform your migration job. Learn about Azure Storage Mover performance targets by visiting the article suggested below.
+Now that you've created a job definition with source and target endpoints, learn how to estimate the time required to perform your migration job.
 > [!div class="nextstepaction"]
 > [Azure Storage Mover scale and performance targets](performance-targets.md)