Final editorial pass

Author: stevenmatthew

articles/storage-mover/agent-deploy.md

@@ -5,7 +5,7 @@ author: stevenmatthew
 ms.author: shaas
 ms.service: storage-mover
 ms.topic: how-to
-ms.date: 03/14/2023
+ms.date: 03/27/2023
 ---
 
 <!-- 
@@ -19,20 +19,20 @@ REVIEW Engineering: not reviewed
 EDIT PASS: started
 
 Initial doc score: 83
-Current doc score: 96 (1915 words and 0 issues)
+Current doc score: 96 (2026 words and 10 false-positive issues)
 
 !########################################################
 -->
 
 # Deploy an Azure Storage Mover agent
 
-The Azure Storage Mover service utilizes agents to perform the migration jobs you configure in the service. An agent is a virtual machine-based migration appliance that runs on a virtualization host. Ideally, your virtualization host will be located as near as possible to the source storage to be migrated.
+The Azure Storage Mover service utilizes agents to perform the migration jobs you configure in the service. An agent is a virtual machine-based migration appliance that runs on a virtualization host. Ideally, your virtualization host is located as near as possible to the source storage to be migrated.
 
-Because the agent is essentially a migration appliance, you'll interact with it through an agent-local administrative shell. The shell limits the operations you can perform on this machine, though network configuration and troubleshooting tasks are accessible.
+Because the agent is essentially a migration appliance, you interact with it through an agent-local administrative shell. The shell limits the operations you can perform on this machine, though network configuration and troubleshooting tasks are accessible.
 
 Use of the agent in migrations is managed through Azure. Both Azure PowerShell and CLI are supported, and graphical interaction is available within the Azure portal. The agent is made available as a disk image compatible with new Windows Hyper-V virtual machines (VM).
 
-This article will guide you through the steps necessary to successfully deploy a Storage Mover agent VM.
+This article guides you through the steps necessary to successfully deploy a Storage Mover agent VM.
 
 ## Prerequisites
 
@@ -51,11 +51,11 @@ Like every VM, the agent requires available compute, memory, network, and storag
 
 ### Network resources
 
-The agent will require unrestricted internet connectivity.
+The agent requires unrestricted internet connectivity.
 
-There's no single network configuration option that will work for every environment. However, the simplest configuration will involve the deployment of an external virtual switch. The external switch type is connected to a physical adapter and will allow your host operating system (OS) to share its connection with all your virtual machines (VMs). This switch allows communication between your physical network, the management operating system, and the virtual adapters on your virtual machines. This approach is fine for a test environment, but may not be suitable for a production server.
+There's no single network configuration option that works for every environment. However, the simplest configuration involves the deployment of an external virtual switch. The external switch type is connected to a physical adapter and allows your host operating system (OS) to share its connection with all your virtual machines (VMs). This switch allows communication between your physical network, the management operating system, and the virtual adapters on your virtual machines. This approach is fine for a test environment, but may not be suitable for a production server.
 
-After the switch is created, ensure that the management and agent VMs are both on the same switch. On the WAN link firewall, outbound TCP port 443 must be open. Keep in mind that connectivity interruptions are to be expected when changing network configurations.
+After the switch is created, ensure that both the management and agent VMs are on the same switch. On the WAN link firewall, outbound TCP port 443 must be open. Keep in mind that connectivity interruptions are to be expected when changing network configurations.
 
 You can get help with [creating a virtual switch for Hyper-V virtual machines](/windows-server/virtualization/hyper-v/get-started/create-a-virtual-switch-for-hyper-v-virtual-machines) in the [Windows Server](/windows-server/) documentation.
 
@@ -97,11 +97,11 @@ At a minimum, the agent image needs 20 GiB of local storage. The amount required
    > [!IMPORTANT]
    > Only *Generation 1* VMs are supported. This Linux image won't boot as a *Generation 2* VM.
 
-1. If you haven't already, [determine the amount of memory you'll need for your VM](#determine-required-resources-for-the-vm). Enter this amount in the **Assign Memory** pane, noting that you need to enter the value in MiB. 1 GiB = 1024 MiB. Using the **Dynamic Memory** feature is fine.
+1. If you haven't already, [determine the amount of memory you need for your VM](#determine-required-resources-for-the-vm). Enter this amount in the **Assign Memory** pane, noting that you need to enter the value in MiB. 1 GiB = 1024 MiB. Using the **Dynamic Memory** feature is fine.
 
    :::image type="content" source="media/agent-deploy/agent-memory-allocate-sml.png" lightbox="media/agent-deploy/agent-memory-allocate-lrg.png"  alt-text="Image showing the location of the Startup Memory field within the New Virtual Machine Wizard.":::
 
-1. Within the **Configure Networking** pane, select the **Connection** drop-down. From the list, choose the virtual switch that will provide the agent with internet connectivity and select **Next**. For more information, see the [Hyper-V virtual networking documentation](/windows-server/networking/sdn/technologies/hyper-v-network-virtualization/hyperv-network-virtualization-overview-windows-server) for details.
+1. Within the **Configure Networking** pane, select the **Connection** drop-down. From the list, choose the virtual switch that provides the agent with internet connectivity and select **Next**. For more information, see the [Hyper-V virtual networking documentation](/windows-server/networking/sdn/technologies/hyper-v-network-virtualization/hyperv-network-virtualization-overview-windows-server) for details.
 
    :::image type="content" source="media/agent-deploy/agent-networking-configure-sml.png" lightbox="media/agent-deploy/agent-networking-configure-lrg.png"  alt-text="Image showing the location of the network Connection field within the New Virtual Machine Wizard.":::
 
@@ -125,7 +125,7 @@ The agent is delivered with a default user account and password. Immediately aft
 
 ## Bandwidth throttling
 
-A general consideration when deploying new machines in a network is the amount of bandwidth they'll use. Any Azure Storage Mover agent will use all available network bandwidth on the local network (source share to agent) and the WAN link (agent to Azure Storage).
+A general consideration when deploying new machines in a network is the amount of bandwidth they use. Any Azure Storage Mover agent uses all available network bandwidth on the local network (source share to agent) and the WAN link (agent to Azure Storage).
 
 > [!IMPORTANT]
 > The current Azure Storage Mover agent does not support bandwidth throttling schedules.
@@ -161,7 +161,7 @@ You can unregister an agent using the administrative shell of the agent VM. The
 xdmsh> 4
 ```
 
-Select the option **4) Unregister**. You'll be prompted for confirmation.
+Select the option **4) Unregister**. You're prompted for confirmation.
 
 > [!WARNING]
 > Unregistration stops any running migration job on the agent and permanently removes the agent from the pool of available migration agents. Re-registration of a previously registered agent VM is not supported. If you need a new agent you should register a new, previously unregistered agent VM. Do not reuse a previously unregistered agent VM.
@@ -195,20 +195,20 @@ Unregister-AzStorageMoverAgent -ResourceGroupName <YourResourceGroupName> -Stora
 
 Several things take place during the unregistration process:
 
-- The agent is removed from the storage mover resource. You'll no longer be able to see the agent in the *Registered agents* tab in the portal or select it for new migration jobs.
+- The agent is removed from the storage mover resource. You can no longer see the agent in the *Registered agents* tab in the portal or select it for new migration jobs.
 - The agent is also removed from the Azure ARC service. This removal deletes the hybrid compute resource of type *Server - Azure Arc* that represented the agent with the Azure ARC service in the same resource group as your storage mover resource.
-- Unregistration removes the managed identity of the agent from Azure Active Directory (Azure AD). The associated service principal is automatically removed, invalidating any permissions this agent may have had on other Azure resources. If you check the role-based access control (RBAC) role assignments, for instance of a target storage container the agent previously had permissions to, you'll no longer find the service principal of the agent, because it was deleted. The assignment itself is still visible as "Unknown service principal" but this assignment no longer connects to an identity and can never be reconnected. It's simply a sign that a role assignment used to be here, of a service principal that no longer exists.
+- Unregistration removes the managed identity of the agent from Azure Active Directory (Azure AD). The associated service principal is automatically removed, invalidating any permissions this agent may have had on other Azure resources. If you check the role-based access control (RBAC) role assignments, for instance of a target storage container the agent previously had permissions to, you no longer find the service principal of the agent, because it was deleted. The assignment itself is still visible as "Unknown service principal" but this assignment no longer connects to an identity and can never be reconnected. It's simply a sign that a role assignment used to be here, of a service principal that no longer exists.
 
   This behavior is standard, and not specific to Azure Storage Mover. You can observe the same behavior if you remove a different service principal from Azure AD and then check a former role assignment.
 
 > [!WARNING]
 > Unregistration of an offline agent is supported, but the agent's Azure ARC resource isn't automatically deleted. Instead, you'll need to manually delete the resource after unregistering an offline agent. The lifecycle of the agent's managed identity is tied to this resource. Removing it removes the managed identity and service principal, as previously described.
 
-You can check that the unregistration process is complete when the agent disappears from the Azure portal and either Azure PowerShell or Azure CLI. You'll also need to confirm that the hybrid compute resource of type *Server - Azure Arc* is gone from the resource group.
+You can check that the unregistration process is complete when the agent disappears from the Azure portal and either Azure PowerShell or Azure CLI. You also need to confirm that the hybrid compute resource of type *Server - Azure Arc* is gone from the resource group.
 
-You can also use the agent's administrative shell to check that the agent is unregistered. To verify unregistration, navigate to any submenu and then return to the top-level menu. If unregistration was successful, you'll see the menu option toggle from *Unregister* to *Register*. As previously mentioned, re-registering isn't supported.
+You can also use the agent's administrative shell to check that the agent is unregistered. To verify unregistration, navigate to any submenu and then return to the top-level menu. If unregistration was successful, you see the menu option toggle from *Unregister* to *Register*. As previously mentioned, re-registering isn't supported.
 
-You can stop the agent VM on your virtualization host after the unregistration is complete. It's best to delete the agent VM image since it was previously registered, retains some state, and must not be used again. If you need a new agent, deploy a new VM with a new agent image that had never been registered before.
+You can stop the agent VM on your virtualization host after the unregistration is complete. It's best to delete the agent VM image since it was previously registered, retains some state, and must not be used again. If you need a new agent, deploy a new VM with a new agent image, never before registered.
 
 ## Next steps
 

articles/storage-mover/deployment-planning.md

@@ -6,7 +6,7 @@ author: stevenmatthew
 ms.service: storage-mover
 ms.author: shaas
 ms.topic: conceptual
-ms.date: 03/14/2023
+ms.date: 03/27/2023
 ---
 
 <!-- 
@@ -34,26 +34,26 @@ Azure Storage Mover aspires to work for a wide range of migration scenarios. How
 
 A deployment of Azure Storage Mover consists out of cloud service components and one or more migration agents you run in your environment, close to the source storage.
 
-The cloud service component is represented by a storage mover resource, deployed in your choice of Azure subscription and resource group. Identify a subscription in the same Azure Active Directory (Azure AD) tenant as the Azure storage accounts you want to migrate into.
+A storage mover resource comprises the cloud service component. This resource is deployed within your choice of Azure subscription and resource group. Identify a subscription in the same Azure Active Directory (Azure AD) tenant as the Azure storage accounts you want to migrate into.
 
 > [!NOTE]
 > An Azure storage mover resource can orchestrate migrations into Azure Storage in other subscriptions, as long as they are governed by the same Azure Active Directory tenant.
 
 ## Select an Azure region for your deployment
 
-When you deploy an Azure storage mover resource, you'll also need to decide on a region. The region you select only determines where control messages are sent and metadata about your migration is stored. The data that is migrated, is sent directly from the agent to the target in Azure Storage. Your files never travel through the Storage Mover service or the resource in that region. That means the proximity between source, agent, and target storage is more important for migration performance than the location of your storage mover resource.
+When you deploy an Azure storage mover resource, you also need to choose a region. The region you select only determines where control messages are sent and metadata about your migration is stored. The data that is migrated, is sent directly from the agent to the target in Azure Storage. Your files never travel through the Storage Mover service or the resource in that region. That means the proximity between source, agent, and target storage is more important for migration performance than the location of your storage mover resource.
 
-:::image type="content" source="media/across-articles/data-vs-management-path.png" alt-text="A diagram illustrating a migration's path by showing two arrows. The first arrow for data traveling to a storage account from the source/agent and a second arrow for only the management/control info to the storage mover resource/service." lightbox="media/across-articles/data-vs-management-path-large.png":::
+:::image type="content" source="media/across-articles/data-vs-management-path.png" alt-text="A diagram illustrating a migration's path by showing two arrows. The first arrow represents data traveling to a storage account from the source and agent, and a second arrow represents the management and control info to the storage mover resource and service." lightbox="media/across-articles/data-vs-management-path-large.png":::
 
-In most cases, deploying only a single storage mover resource is the best option, even when you need to migrate files located in other countries. You'll register one or more migration agents to a storage mover resource - and an agent can only be used for migrations by the storage mover it's registered with. The agents themselves should be located close to the source storage, even if that means registering  agents deployed in other countries to a storage mover resource located across the globe.
+In most cases, deploying only a single storage mover resource is the best option, even when you need to migrate files located in other countries. One or more migration agents are registered to a storage mover resource. An agent can only be used by the storage mover to which it's registered. The agents themselves should be located close to the source storage, even if that means registering  agents deployed in other countries to a storage mover resource located across the globe.
 
 Only deploy multiple storage mover resources if you have distinct sets of migration agents. Having separate storage mover resources and agents allows you to keep permissions separate for the admins managing their part of the source or target storage.
 
 Deploying a Storage Mover agent as an Azure VM hasn't been tested and is currently not supported.
 
 ## Getting your subscription ready
 
-Your subscription must be in the same Azure Active Directory tenant as the target Azure storage accounts you want to migrate into. When you've decided on an Azure subscription and resource group for your storage mover resource, you'll need to prepare a few things depending on how you deploy and which actions you or another admin will perform.
+Your subscription must be in the same Azure Active Directory tenant as the target Azure storage accounts you want to migrate into. When you've decided on an Azure subscription and resource group for your storage mover resource, you need to prepare a few things depending on how you deploy and which actions you or another admin perform.
 
 ### Resource provider namespaces
 
@@ -71,7 +71,7 @@ Register a resource provider:
 > [!TIP]
 > When you deploy a storage mover resource as a subscription *Owner* or *Contributor* through the Azure portal, your subscription is automatically registered with both of these resource provider namespaces. You'll only have to perform the registration manually when using Azure PowerShell or CLI.
 
-Once a subscription is enabled for both of these resource provider namespaces, it will remain enabled until manually unregistered. You can even delete the last storage mover resource and your subscription still remains enabled. Subsequent storage mover resource deployments then require reduced permissions from an admin. The following section contains a breakdown of different management scenarios and their required permissions.
+Once a subscription is enabled for both of these resource provider namespaces, it remains enabled until manually unregistered. You can even delete the last storage mover resource and your subscription still remains enabled. Subsequent storage mover resource deployments then require reduced permissions from an admin. The following section contains a breakdown of different management scenarios and their required permissions.
 
 ## Permissions