Adding preview tag for commands, moving migration to a seperate folder & update help text.

Author: mettursathish

src/migrate/azext_migrate/_help.py

@@ -540,3 +540,61 @@
                 --name myJobName \\
                 --subscription-id "12345678-1234-1234-1234-123456789012"
 """
+
+helps['migrate local start-migration'] = """
+    type: command
+    short-summary: Start migration for a replicating server to Azure Local.
+    long-summary: |
+        Initiates the migration (failover) process for a server that
+        has been configured for replication to Azure Local or Azure Stack HCI.
+        This command triggers the final migration step, which creates
+        the virtual machine on the target Azure Local/Stack HCI environment.
+
+        The protected item must be in a healthy replication state
+        before migration can be initiated.
+        You can optionally specify whether to turn off the source server
+        after migration completes.
+
+        Note: This command uses a preview API version
+        and may experience breaking changes in future releases.
+    parameters:
+        - name: --protected-item-id --id
+          short-summary: Full ARM resource ID of the protected item to migrate.
+          long-summary: >
+            The complete ARM resource ID of the replicating server.
+            This ID can be obtained from the 'az migrate local replication list'
+            or 'az migrate local replication get' commands.
+            Required parameter.
+        - name: --turn-off-source-server
+          short-summary: Turn off the source server after migration.
+          long-summary: >
+            Specifies whether the source server should be powered off
+            after the migration completes successfully.
+            Default is False. Use this option to automatically shut down
+            the source server to prevent conflicts.
+        - name: --subscription-id
+          short-summary: Azure subscription ID.
+          long-summary: >
+            The subscription containing the migration resources.
+            Uses the current subscription if not specified.
+    examples:
+        - name: Start migration for a protected item
+          text: |
+            az migrate local start-migration \\
+                --protected-item-id "/subscriptions/xxxx/resourceGroups/myRG/providers/Microsoft.DataReplication/replicationVaults/myVault/protectedItems/myItem"
+        - name: Start migration and turn off source server
+          text: |
+            az migrate local start-migration \\
+                --protected-item-id "/subscriptions/xxxx/resourceGroups/myRG/providers/Microsoft.DataReplication/replicationVaults/myVault/protectedItems/myItem" \\
+                --turn-off-source-server
+        - name: Start migration using short parameter names
+          text: |
+            az migrate local start-migration \\
+                --id "/subscriptions/xxxx/resourceGroups/myRG/providers/Microsoft.DataReplication/replicationVaults/myVault/protectedItems/myItem" \\
+                --turn-off-source-server
+        - name: Start migration with specific subscription
+          text: |
+            az migrate local start-migration \\
+                --protected-item-id "/subscriptions/xxxx/resourceGroups/myRG/providers/Microsoft.DataReplication/replicationVaults/myVault/protectedItems/myItem" \\
+                --subscription-id "12345678-1234-1234-1234-123456789012"
+"""

src/migrate/azext_migrate/_params.py

@@ -255,3 +255,18 @@ def load_arguments(self, _):
             options_list=['--job-name', '--name'],
             help='Job identifier.')
         c.argument('subscription_id', subscription_id_type)
+
+    with self.argument_context('migrate local start-migration') as c:
+        c.argument(
+            'protected_item_id',
+            options_list=['--protected-item-id', '--id'],
+            help='The full ARM resource ID of the protected item to migrate. '
+                 'This can be obtained from the list or get replication commands.',
+            required=True)
+        c.argument(
+            'turn_off_source_server',
+            options_list=['--turn-off-source-server'],
+            arg_type=get_three_state_flag(),
+            help='Specifies whether the source server should be turned off '
+                 'after migration completes. Default is False.')
+        c.argument('subscription_id', subscription_id_type)

src/migrate/azext_migrate/commands.py

@@ -6,16 +6,16 @@
 
 def load_command_table(self, _):
     # Azure Local Migration Commands
-    with self.command_group('migrate') as g:
+    with self.command_group('migrate', is_preview=True) as g:
         g.custom_command('get-discovered-server', 'get_discovered_server')
 
-    with self.command_group('migrate local replication') as g:
+    with self.command_group('migrate local replication', is_preview=True) as g:
         g.custom_command('init', 'initialize_replication_infrastructure')
         g.custom_command('new', 'new_local_server_replication')
         g.custom_command('list', 'list_local_server_replications')
         g.custom_command('get', 'get_local_server_replication')
         g.custom_command('remove', 'remove_local_server_replication')
         g.custom_command('get-job', 'get_local_replication_job')
 
-    with self.command_group('migrate local') as g:
+    with self.command_group('migrate local', is_preview=True) as g:
         g.custom_command('start-migration', 'start_local_server_migration')

src/migrate/azext_migrate/custom.py

@@ -20,31 +20,6 @@ def get_discovered_server(cmd,
                           subscription_id=None,
                           name=None,
                           appliance_name=None):
-    """
-    Retrieve discovered servers from the Azure Migrate project.
-
-    Args:
-        cmd: The CLI command context
-        project_name (str): Specifies the migrate project name (required)
-        resource_group (str): Specifies the resource group name
-            (required)
-        display_name (str, optional): Specifies the source machine
-            display name
-        source_machine_type (str, optional): Specifies the source machine
-            type (VMware, HyperV)
-        subscription_id (str, optional): Specifies the subscription id
-        name (str, optional): Specifies the source machine name
-            (internal name)
-        appliance_name (str, optional): Specifies the appliance name
-            (maps to site)
-
-    Returns:
-        dict: The discovered server data from the API response
-
-    Raises:
-        CLIError: If required parameters are missing or the API request
-            fails
-    """
     from azext_migrate.helpers._utils import APIVersion
     from azext_migrate.helpers._server import (
         validate_get_discovered_server_params,
@@ -112,37 +87,6 @@ def initialize_replication_infrastructure(cmd,
                                           cache_storage_account_id=None,
                                           subscription_id=None,
                                           pass_thru=False):
-    """
-    Initialize Azure Migrate local replication infrastructure.
-
-    This function is based on a preview API version and may experience
-    breaking changes in future releases.
-
-    Args:
-        cmd: The CLI command context
-        resource_group (str): Specifies the Resource Group of the
-            Azure Migrate Project (required)
-        project_name (str): Specifies the name of the Azure Migrate
-            project to be used for server migration (required)
-        source_appliance_name (str): Specifies the source appliance name
-            for the AzLocal scenario (required)
-        target_appliance_name (str): Specifies the target appliance name
-            for the AzLocal scenario (required)
-        cache_storage_account_id (str, optional): Specifies the Storage
-            Account ARM Id to be used for private endpoint scenario
-        subscription_id (str, optional): Azure Subscription ID. Uses
-            current subscription if not provided
-        pass_thru (bool, optional): Returns True when the command
-            succeeds
-
-    Returns:
-        bool: True if the operation succeeds (when pass_thru is True),
-            otherwise None
-
-    Raises:
-        CLIError: If required parameters are missing or the API request
-            fails
-    """
     from azure.cli.core.commands.client_factory import \
         get_subscription_id
     from azext_migrate.helpers.replication.init._execute_init import (
@@ -197,63 +141,6 @@ def new_local_server_replication(cmd,
                                  nic_to_include=None,
                                  os_disk_id=None,
                                  subscription_id=None):
-    """
-    Create a new replication for an Azure Local server.
-
-    This cmdlet is based on a preview API version and may experience
-    breaking changes in future releases.
-
-    Args:
-        cmd: The CLI command context
-        target_storage_path_id (str): Specifies the storage path ARM ID
-            where the VMs will be stored (required)
-        target_resource_group_id (str): Specifies the target resource
-            group ARM ID where the migrated VM resources will reside
-            (required)
-        target_vm_name (str): Specifies the name of the VM to be created
-            (required)
-        source_appliance_name (str): Specifies the source appliance name
-            for the AzLocal scenario (required)
-        target_appliance_name (str): Specifies the target appliance name
-            for the AzLocal scenario (required)
-        machine_id (str, optional): Specifies the machine ARM ID of the
-            discovered server to be migrated (required if machine_index
-            not provided)
-        machine_index (int, optional): Specifies the index of the
-            discovered server from the list (1-based, required if
-            machine_id not provided)
-        project_name (str, optional): Specifies the migrate project name
-            (required when using machine_index)
-        resource_group (str, optional): Specifies the resource group
-            name (required when using machine_index)
-        target_vm_cpu_core (int, optional): Specifies the number of CPU
-            cores
-        target_virtual_switch_id (str, optional): Specifies the logical
-            network ARM ID that the VMs will use (required for default
-            user mode)
-        target_test_virtual_switch_id (str, optional): Specifies the test
-            logical network ARM ID that the VMs will use
-        is_dynamic_memory_enabled (str, optional): Specifies if RAM is
-            dynamic or not. Valid values: 'true', 'false'
-        target_vm_ram (int, optional): Specifies the target RAM size in
-            MB
-        disk_to_include (list, optional): Specifies the disks on the
-            source server to be included for replication (power user
-            mode)
-        nic_to_include (list, optional): Specifies the NICs on the source
-            server to be included for replication (power user mode)
-        os_disk_id (str, optional): Specifies the operating system disk
-            for the source server to be migrated (required for default
-            user mode)
-        subscription_id (str, optional): Azure Subscription ID. Uses
-            current subscription if not provided
-
-    Returns:
-        dict: The job model from the API response
-
-    Raises:
-        CLIError: If required parameters are missing or validation fails
-    """
     from azext_migrate.helpers._utils import SiteTypes
     from azext_migrate.helpers.replication.new._validate import (
         validate_server_parameters,
@@ -482,29 +369,6 @@ def get_local_replication_job(cmd,
                               project_name=None,
                               job_name=None,
                               subscription_id=None):
-    """
-    Retrieve the status of an Azure Migrate job.
-
-    This cmdlet is based on a preview API version and may experience
-    breaking changes in future releases.
-
-    Args:
-        cmd: The CLI command context
-        job_id (str, optional): Specifies the job ARM ID for which
-            the details need to be retrieved
-        resource_group (str, optional): The name of the resource
-            group where the recovery services vault is present
-        project_name (str, optional): The name of the migrate project
-        job_name (str, optional): Job identifier/name
-        subscription_id (str, optional): Azure Subscription ID. Uses
-            current subscription if not provided
-
-    Returns:
-        dict or list: Job details (single job or list of jobs)
-
-    Raises:
-        CLIError: If required parameters are missing or the job is not found
-    """
     from azure.cli.core.commands.client_factory import \
         get_subscription_id
     from azext_migrate.helpers.replication.job._parse import (
@@ -554,26 +418,6 @@ def list_local_server_replications(cmd,
                                    resource_group=None,
                                    project_name=None,
                                    subscription_id=None):
-    """
-    List all protected items (replicating servers) in an Azure Migrate project.
-
-    This cmdlet is based on a preview API version and may experience
-    breaking changes in future releases.
-
-    Args:
-        cmd: The CLI command context
-        resource_group (str, optional): The name of the resource group where
-            the migrate project is present (required)
-        project_name (str, optional): The name of the migrate project (required)
-        subscription_id (str, optional): Azure Subscription ID. Uses
-            current subscription if not provided
-
-    Returns:
-        list: List of protected items with their replication status
-
-    Raises:
-        CLIError: If required parameters are missing or the vault is not found
-    """
     from azure.cli.core.commands.client_factory import \
         get_subscription_id
     from azext_migrate.helpers.replication.list._execute_list import (
@@ -605,31 +449,6 @@ def get_local_server_replication(cmd,
                                  resource_group=None,
                                  project_name=None,
                                  subscription_id=None):
-    """
-    Get details of a specific replicating server.
-
-    This cmdlet is based on a preview API version and may experience
-    breaking changes in future releases.
-
-    Args:
-        cmd: The CLI command context
-        protected_item_name (str, optional): The name of the protected item
-        protected_item_id (str, optional): The full ARM resource ID of the
-            protected item
-        resource_group (str, optional): The name of the resource group where
-            the migrate project is present (required if using protected_item_name)
-        project_name (str, optional): The name of the migrate project
-            (required if using protected_item_name)
-        subscription_id (str, optional): Azure Subscription ID. Uses
-            current subscription if not provided
-
-    Returns:
-        dict: Detailed information about the protected item
-
-    Raises:
-        CLIError: If required parameters are missing or the protected item
-            is not found
-    """
     from azure.cli.core.commands.client_factory import \
         get_subscription_id
     from azext_migrate.helpers.replication.get._execute_get import (
@@ -664,28 +483,6 @@ def remove_local_server_replication(cmd,
                                     target_object_id,
                                     force_remove=False,
                                     subscription_id=None):
-    """
-    Stop replication for a migrated server.
-
-    This cmdlet is based on a preview API version and may experience
-    breaking changes in future releases.
-
-    Args:
-        cmd: The CLI command context
-        target_object_id (str): Specifies the replicating server ARM ID
-            for which replication needs to be disabled (required)
-        force_remove (bool, optional): Specifies whether the replication
-            needs to be force removed. Default is False
-        subscription_id (str, optional): Azure Subscription ID. Uses
-            current subscription if not provided
-
-    Returns:
-        dict: The job model from the API response
-
-    Raises:
-        CLIError: If the protected item is not found or cannot be
-            removed in its current state
-    """
     from azure.cli.core.commands.client_factory import \
         get_subscription_id
     from azext_migrate.helpers.replication.remove._parse import (
@@ -720,39 +517,12 @@ def start_local_server_migration(cmd,
                                  protected_item_id=None,
                                  turn_off_source_server=False,
                                  subscription_id=None):
-    """
-    Start migration for a local server.
-
-    This cmdlet is based on a preview API version and may experience
-    breaking changes in future releases.
-
-    Args:
-        cmd: The CLI command context
-        protected_item_name (str, optional): The name of the protected item
-        protected_item_id (str, optional): The full ARM resource ID of the
-            protected item
-        resource_group (str, optional): The name of the resource group where
-            the migrate project is present (required if using protected_item_name)
-        project_name (str, optional): The name of the migrate project
-            (required if using protected_item_name)
-        turn_off_source_server (bool, optional): Specifies whether the source
-            server should be turned off post migration. Default is False
-        subscription_id (str, optional): Azure Subscription ID. Uses
-            current subscription if not provided
-
-    Returns:
-        dict: Job model representing the migration operation
-
-    Raises:
-        CLIError: If required parameters are missing or the protected item
-            is not found or cannot be migrated
-    """
     from azure.cli.core.commands.client_factory import \
         get_subscription_id
-    from azext_migrate.helpers.replication.migrate._parse import (
+    from azext_migrate.helpers.migration.start._parse import (
         parse_protected_item_id
     )
-    from azext_migrate.helpers.replication.migrate._execute_migrate import (
+    from azext_migrate.helpers.migration.start._execute_migrate import (
         execute_migration
     )