[Migrate] Start migration command, preview channel versioning & new commands for replication (#9493)

* Adding "Migrate" folder to the project

* Added migrate command

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

* Addressing style issues

* addressing the styles and removing the duplicate key

* addressing style issues

* addesssing more style issues

* addressing  inline disable at the specific line

* Added R1702 to the pylint disable comment on the function definition.

* Addressing to disable too many nested blocks R1702

* Fixing test cases and updating version changes

* Add cli fixes (#1)

* Create extension

* Update src/migrate/azext_migrate/__init__.py

Co-authored-by: Copilot <[email protected]>

* Fix import issues

* Update src/migrate/setup.py

Co-authored-by: Copilot <[email protected]>

* Small

* Small lint

* Small

* disable lint for this check

* Add json

* Fix licesnse issue

* fix small

* Small

* Get rid of unused variables

* Add service name and code owner

* New version

* Style

* Small

* Update

* Follow standard

* Add suggestions

* Small

* Not preview

* Add flag to become experimental

* Update history

* Fix

* small

* Create get job and remove replication commands

* Add better error handling for jobs command

* Add better messages to remove protected item

* Return job id in remove command

* Move helpers

* Rename get discovered server helper

* Refactor _initialize_replication_infrastructure_helpers

* Refactor new replication

* Refactor jobs

* Refactor delete protected item

* Fix lint issues

* Change release version

* Fix lint issues

* Add fix

* Updae correct version

* Put beta version before

* Fix

* Update

* Fix bifurcation tool issue

* Update amh correctly if not proper

* Use current subscription id if not passed in

* Fix correct location and target resource group creation

* Create list protected items command

* Update versions

* Add __init__.py to all folders

* Create unit tests for get replication

* Update readme with accurate description of commands

* Update readme

* Create tests for jobs and remove commands

* Add more tests to increase coverage to 74%

* Add start migration command

* Address fixes

* Remove doc strings from custom.py

* Add init

* Remove old file locations

* fix failing tests

* Fix secret test

* Fix test

* Fix secret detection

* Fix duplicates

---------

Co-authored-by: Saif Al-Din Ali <[email protected]>
Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Saif Al-Din Ali <[email protected]>
Co-authored-by: Saif Al-Din Ali <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 4 people

azure-cli-extensions.pyproj

@@ -2704,6 +2704,20 @@
     <Compile Include="src\mesh\azext_mesh\_params.py" />
     <Compile Include="src\mesh\azext_mesh\__init__.py" />
     <Compile Include="src\mesh\setup.py" />
+    <Compile Include="src\migrate\azext_migrate\aaz\__init__.py" />
+    <Compile Include="src\migrate\azext_migrate\commands.py" />
+    <Compile Include="src\migrate\azext_migrate\custom.py" />
+    <Compile Include="src\migrate\azext_migrate\tests\latest\test_migrate_commands.py" />
+    <Compile Include="src\migrate\azext_migrate\tests\latest\__init__.py" />
+    <Compile Include="src\migrate\azext_migrate\tests\__init__.py" />
+    <Compile Include="src\migrate\azext_migrate\_get_discovered_server_helpers.py" />
+    <Compile Include="src\migrate\azext_migrate\_help.py" />
+    <Compile Include="src\migrate\azext_migrate\_helpers.py" />
+    <Compile Include="src\migrate\azext_migrate\_initialize_replication_infrastructure_helpers.py" />
+    <Compile Include="src\migrate\azext_migrate\_new_local_server_replication_helpers.py" />
+    <Compile Include="src\migrate\azext_migrate\_params.py" />
+    <Compile Include="src\migrate\azext_migrate\__init__.py" />
+    <Compile Include="src\migrate\setup.py" />
     <Compile Include="src\privatedns\azext_privatedns\commands.py" />
     <Compile Include="src\privatedns\azext_privatedns\custom.py" />
     <Compile Include="src\privatedns\azext_privatedns\vendored_sdks\models\aaaa_record.py" />
@@ -4699,6 +4713,11 @@
     <Content Include="src\mesh\azext_mesh\azext_metadata.json" />
     <Content Include="src\mesh\HISTORY.rst" />
     <Content Include="src\mesh\README.rst" />
+    <Content Include="src\migrate\azext_migrate\azext_metadata.json" />
+    <Content Include="src\migrate\HISTORY.rst" />
+    <Content Include="src\migrate\linter_exclusions.yml" />
+    <Content Include="src\migrate\README.md" />
+    <Content Include="src\migrate\setup.cfg" />
     <Content Include="src\resource-graph\azext_resourcegraph\azext_metadata.json" />
     <Content Include="src\resource-graph\HISTORY.rst" />
     <Content Include="src\resource-graph\README.rst" />
@@ -4877,6 +4896,11 @@
     <Folder Include="src\mesh\azext_mesh\servicefabricmesh\mgmt\servicefabricmesh\operations" />
     <Folder Include="src\mesh\azext_mesh\tests\" />
     <Folder Include="src\mesh\azext_mesh\tests\latest" />
+    <Folder Include="src\migrate\" />
+    <Folder Include="src\migrate\azext_migrate\" />
+    <Folder Include="src\migrate\azext_migrate\aaz\" />
+    <Folder Include="src\migrate\azext_migrate\tests\" />
+    <Folder Include="src\migrate\azext_migrate\tests\latest\" />
     <Folder Include="src\privatedns\" />
     <Folder Include="src\privatedns\azext_privatedns\" />
     <Folder Include="src\privatedns\azext_privatedns\vendored_sdks\" />

src/migrate/HISTORY.rst

@@ -3,18 +3,22 @@
 Release History
 ===============
 
-3.0.0b1
+3.0.0b2
 +++++++++++++++
-* Refactor codebase for improved readability and maintainability.
+* Added replication list, get and start migration commands.
 
-2.0.1b1
+3.0.0b1
 +++++++++++++++
-* Switch to experimental version.
+* Refactor codebase for improved readability and maintainability.
 
 2.0.0
 +++++++++++++++
 * New version.
 
+2.0.1b1
++++++++++++++++
+* Switch to experimental version.
+
 1.0.0
 +++++++++++++++
 * Initial release.

src/migrate/azext_migrate/_help.py

@@ -304,6 +304,130 @@
                 --os-disk-id "disk-0"
 """
 
+helps['migrate local replication list'] = """
+    type: command
+    short-summary: List all protected items (replicating servers) in a project.
+    long-summary: |
+        Lists all servers that have replication enabled
+        in an Azure Migrate project.
+        This command shows the replication status, health,
+        and configuration details for each protected server.
+
+        The command returns information including:
+        - Protection state (e.g., Protected, ProtectedReplicating, EnablingFailed)
+        - Replication health (Normal, Warning, Critical)
+        - Source machine name and target VM name
+        - Replication policy name
+        - Resource IDs (used for remove command)
+        - Health errors if any
+
+        Note: This command uses a preview API version
+        and may experience breaking changes in future releases.
+    parameters:
+        - name: --resource-group -g
+          short-summary: Resource group containing the Azure Migrate project.
+          long-summary: >
+            The name of the resource group where
+            the Azure Migrate project is located.
+        - name: --project-name
+          short-summary: Name of the Azure Migrate project.
+          long-summary: >
+            The Azure Migrate project that contains
+            the replicating servers.
+        - name: --subscription-id
+          short-summary: Azure subscription ID.
+          long-summary: >
+            The subscription containing the Azure Migrate project.
+            Uses the default subscription if not specified.
+    examples:
+        - name: List all replicating servers in a project
+          text: |
+            az migrate local replication list \\
+                --resource-group myRG \\
+                --project-name myMigrateProject
+        - name: List replicating servers with a specific subscription
+          text: |
+            az migrate local replication list \\
+                --resource-group myRG \\
+                --project-name myMigrateProject \\
+                --subscription-id 00000000-0000-0000-0000-000000000000
+"""
+
+helps['migrate local replication get'] = """
+    type: command
+    short-summary: Get detailed information about a specific replicating server.
+    long-summary: |
+        Retrieves comprehensive details about a specific protected item (replicating server)
+        including its protection state, replication health, configuration settings,
+        and historical information about failover operations.
+
+        You can retrieve the protected item either by:
+        - Full ARM resource ID (--protected-item-id or --id)
+        - Name with project context (--protected-item-name with --resource-group and --project-name)
+
+        The command returns detailed information including:
+        - Basic information (name, resource ID, correlation ID)
+        - Protection status (state, health, resync requirements)
+        - Configuration (policy, replication extension)
+        - Failover history (test, planned, unplanned)
+        - Allowed operations
+        - Machine details (source and target information)
+        - Health errors with recommended actions (if any)
+
+        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.
+          long-summary: >
+            The complete ARM resource ID of the protected item.
+            If provided, --resource-group and --project-name are not required.
+            This ID can be obtained from the 'list' or 'new' commands.
+        - name: --protected-item-name --name
+          short-summary: Name of the protected item (replicating server).
+          long-summary: >
+            The name of the protected item to retrieve.
+            When using this option, both --resource-group and --project-name
+            are required to locate the item.
+        - name: --resource-group -g
+          short-summary: Resource group containing the Azure Migrate project.
+          long-summary: >
+            The name of the resource group where the Azure Migrate project is located.
+            Required when using --protected-item-name.
+        - name: --project-name
+          short-summary: Name of the Azure Migrate project.
+          long-summary: >
+            The Azure Migrate project that contains the replicating server.
+            Required when using --protected-item-name.
+        - name: --subscription-id
+          short-summary: Azure subscription ID.
+          long-summary: >
+            The subscription containing the Azure Migrate project.
+            Uses the default subscription if not specified.
+    examples:
+        - name: Get a protected item by its full ARM resource ID
+          text: |
+            az migrate local replication get \\
+                --protected-item-id "/subscriptions/xxxx/resourceGroups/myRG/providers/Microsoft.DataReplication/replicationVaults/myVault/protectedItems/myItem"
+        - name: Get a protected item by name using project context
+          text: |
+            az migrate local replication get \\
+                --protected-item-name myProtectedItem \\
+                --resource-group myRG \\
+                --project-name myMigrateProject
+        - name: Get a protected item with specific subscription
+          text: |
+            az migrate local replication get \\
+                --name myProtectedItem \\
+                --resource-group myRG \\
+                --project-name myMigrateProject \\
+                --subscription-id 00000000-0000-0000-0000-000000000000
+        - name: Get a protected item using short parameter names
+          text: |
+            az migrate local replication get \\
+                --id "/subscriptions/xxxx/resourceGroups/myRG/providers/Microsoft.DataReplication/replicationVaults/myVault/protectedItems/myItem"
+"""
+
 helps['migrate local replication remove'] = """
     type: command
     short-summary: Stop replication for a migrated server.
@@ -416,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

@@ -184,6 +184,42 @@ def load_arguments(self, _):
             required=True)
         c.argument('subscription_id', subscription_id_type)
 
+    with self.argument_context('migrate local replication list') as c:
+        c.argument(
+            'resource_group',
+            options_list=['--resource-group', '-g'],
+            help='The name of the resource group where the migrate '
+                 'project is present.',
+            required=True)
+        c.argument(
+            'project_name',
+            project_name_type,
+            help='The name of the migrate project.',
+            required=True)
+        c.argument('subscription_id', subscription_id_type)
+
+    with self.argument_context('migrate local replication get') as c:
+        c.argument(
+            'protected_item_name',
+            options_list=['--protected-item-name', '--name'],
+            help='The name of the protected item (replicating server).')
+        c.argument(
+            'protected_item_id',
+            options_list=['--protected-item-id', '--id'],
+            help='The full ARM resource ID of the protected item. '
+                 'If provided, --resource-group and --project-name are not required.')
+        c.argument(
+            'resource_group',
+            options_list=['--resource-group', '-g'],
+            help='The name of the resource group where the migrate '
+                 'project is present. Required when using --protected-item-name.')
+        c.argument(
+            'project_name',
+            project_name_type,
+            help='The name of the migrate project. Required when using '
+                 '--protected-item-name.')
+        c.argument('subscription_id', subscription_id_type)
+
     with self.argument_context('migrate local replication remove') as c:
         c.argument(
             'target_object_id',
@@ -219,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,11 +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', is_preview=True) as g:
+        g.custom_command('start-migration', 'start_local_server_migration')