huawei-cloud-sms-host-migrator

Imported from huaweicloud/huaweicloud-skills (skills/solution/migration/huawei-cloud-sms-host-migrator/SKILL.md). Install upstream with npx skills add huaweicloud/huaweicloud-skills --skill huawei-cloud-sms-host-migrator. Copyright stays with the author.

Huawei Cloud SMS Host Migrator

The Huawei Cloud SMS Host Migrator skill automates and guides the full lifecycle of host migration from on-premise IDCs or third-party clouds (Alibaba Cloud, Tencent Cloud, AWS) to Huawei Cloud ECS or Flexus X instances using the Huawei Cloud Server Migration Service (SMS).

Overview

The migration process supports file-level replication (MIGRATE_FILE) for Linux source hosts and block-level replication (MIGRATE_BLOCK) for Windows Server source hosts.

Key capabilities provided:

• Guided Agent Deployment: Generate installation instructions for Linux and Windows Server source machines.
• Pre-migration Compatibility Diagnostics: Automatic checks for OS version, firmware (BIOS/UEFI), disk partition table (MBR/GPT), file system, and required network ports.
• Target Specification Modeling: Provision migration templates targeting Huawei Cloud standard ECS or cost-effective Flexus X instances.
• Replication Orchestration: Track replication tasks, remaining time (remain_seconds), throttling limits, progress percentages, and subtask states.
• Cutover and Validation: Execute incremental sync windows, detach migration drivers, and verify target host boot status.

Prerequisites

1. KooCLI (hcloud): Installed and authenticated with a valid profile (cn-north-4, ap-southeast-3, etc.).
   • Follow instructions in references/cli-installation-guide.md.
2. Target Security Group Inbound Rules: The destination ECS security group must allow specific inbound ports strictly from the source server IP:
   • Linux: Inbound TCP port 22 (secure rsync over SSH).
   • Windows Server: Inbound TCP ports 22 (initialization), 8899 (control channel), and 8900 (block data streaming).
   • Default Creation Behavior: By default, create a dedicated new security group populated strictly with these rules rather than reusing an existing group.
   • Target Outbound Rules: Outbound TCP port 443 allowed to SMS API and Huawei Cloud services.
   • Target Subnet Network ACL: Ensure associated subnet ACLs allow matching inbound ports and return ephemeral ports.
   • Security Guardrail: Do not set source address to 0.0.0.0/0; restrict strictly to source server IP.
3. Source Server Network & Environment:
   • Outbound TCP port 443 open to SMS control plane: sms.cn-north-4.myhuaweicloud.com (China Site) or sms.ap-southeast-3.myhuaweicloud.com (International Site - Singapore).
   • Outbound TCP ports 22, 8899, 8900 open to target ECS (public EIP or private IP via VPN/Direct Connect).
   • NTP Time Synchronization: Source system clock drift must be within 15 minutes of standard time.
   • Dependencies: Linux requires rsync, tar, nohup, python; Windows requires PowerShell 3.0+ and VSS service.
   • Disk Space: Linux root partition (/) ≥ 200 MB free space; Windows partitions ≥ 600 MB require ≥ 320 MB free space.
4. IAM Permissions: Sufficient permissions for SMS FullAccess, ECS CommonOperations, VPC Administrator, and EVS CommonOperations.
   • See least-privilege definitions in references/iam-policies.md.
   • See complete pre-migration checklist in references/pre-migration-checklist.md.

Workflow

1. Phase 1 - Assessment & Scenario Selection:
   • Scenario A (Source Host Already Registered): Locate the host using hcloud SMS ListServers --cli-region={region}, retrieve source_server_id, verify 14 pre-checks via ShowServer, and proceed to Phase 3 (skip Phase 2).
   • Scenario B (Fresh Host / Agent Not Installed): Perform preliminary prerequisites (OS support, NTP drift ≤ 15 min, network connectivity) and proceed to Phase 2 for agent deployment (verify registration via ListServers post-installation). (Note: If registration state is unknown, run hcloud SMS ListServers --cli-region={region} first).
2. Phase 2 - Agent Deployment & Registration (Scenario B Only): Deploy OS-specific agent and authenticate out-of-band with AK/SK, SMS domain (sms.cn-north-4.myhuaweicloud.com for China Site; sms.ap-southeast-3.myhuaweicloud.com for International Site Singapore), and Enterprise Project ID.
3. Phase 3 - Target Security Group & Destination Provisioning:
   • Create a dedicated target security group with minimal inbound rules (Linux: port 22; Windows: ports 22, 8899, 8900) restricted to the source IP (public egress IP for internet; private IP for VPN/Direct Connect).
   • Target Provisioning Branching (BIOS/Linux vs UEFI Windows):
     • Standard Mode (BIOS Hosts & Linux): Create a target template (CreateTemplate) with VPC, subnet, flavor, image ID (from IMS), and network binding (300M pay-per-traffic EIP for public mode; {} for private mode).
     • Existing Server Mode (Mandatory for UEFI Windows): SMS does not support auto-provisioning via templates for UEFI Windows. Do not create a migration template. Pre-create the target ECS on Huawei Cloud with UEFI boot mode (hw_firmware_type: "uefi"), matching disk layout, and proceed directly to Phase 4.
4. Phase 4 - Replication Task Execution: Create migration task (name: 4–20 chars) with disk layout mapped from ShowServer. For BIOS/Linux, link vm_template_id (exist_server: false); for UEFI Windows, specify target_server.vm_id (exist_server: true, type: MIGRATE_BLOCK). Route replication traffic via public EIP (use_public_ip: true) or private IP (use_public_ip: false). Monitor progress and adjust speed if needed.
5. Phase 5 - Incremental Sync & Cutover: Run delta synchronization passes during maintenance window, finalize cutover via UpdateTaskStatus --operation="clear", verify source server transitions to cleared state (task remains MIGRATE_SUCCESS), and clean up resources in Task → Template sequence.

[!IMPORTANT] Mutating operations (such as creating migration tasks, pausing/restarting tasks, modifying templates, and triggering cutover) alter cloud resources. Always confirm parameters with the user before executing mutating commands.

Core Commands

1. Assessment & Server Discovery (Read-Only)

View current migration overview statistics across all lifecycle states:

hcloud SMS ShowOverview --cli-region=cn-north-4

Decision Branching:

• Scenario A (Source Server Registered in SMS): Query registered servers to locate the target host and retrieve its ID:

  hcloud SMS ListServers --cli-region=cn-north-4 --limit=10

  Optionally filter by hostname:

  hcloud SMS ListServers --cli-region=cn-north-4 --name="source-host-01"

  Inspect detailed source server configuration, disk layout, and automated pre-check results:

  hcloud SMS ShowServer --cli-region=cn-north-4 --source_id={source_server_id}

  • When all 14 pre-checks report result: "OK", skip Phase 2 (Agent Deployment) and jump directly to Phase 3 (Target Template Management).
  • If state: "unavailable", the agent is disconnected; guide the user to restart the agent on the source host (sudo ./startup.sh on Linux or restart SMS-Agent Windows service).

• Scenario B (Fresh Host / Agent Not Installed):

  • The source host is not yet registered in SMS. Perform preliminary offline checks (see references/pre-migration-checklist.md).
  • Proceed directly to Phase 2 (Agent Deployment & Registration) (see references/agent-deployment-guide.md).
  • Once the agent runs and registers, query hcloud SMS ListServers --cli-region=cn-north-4 to confirm registration and obtain source_server_id.

List existing migration projects:

hcloud SMS ListMigprojects --cli-region=cn-north-4

2. Target Security Group & Template Management

Step 2.1: Create Dedicated Target Security Group

By default, create a new dedicated security group rather than reusing an existing group:

hcloud VPC CreateSecurityGroup --cli-region=cn-north-4 --security_group.name=sg-sms-target-migration --security_group.description="Dedicated security group for SMS target ECS"

Add ingress rules restricted to source server IP:

[!IMPORTANT] Source IP Selection:

• Public IP (Default): For internet migrations, set remote_ip_prefix to the source host's public egress IP ({source_public_ip}/32).
• Private IP: Use source private IP ({source_private_ip}/32) only when private network connectivity (VPN/Direct Connect) is established.

• For Linux (Port 22):

hcloud VPC CreateSecurityGroupRule --cli-region=cn-north-4 --security_group_rule.security_group_id="{sg_id}" --security_group_rule.direction="ingress" --security_group_rule.protocol="tcp" --security_group_rule.multiport="22" --security_group_rule.remote_ip_prefix="{source_public_ip}/32"

• For Windows Server (Ports 22, 8899, 8900):

hcloud VPC CreateSecurityGroupRule --cli-region=cn-north-4 --security_group_rule.security_group_id="{sg_id}" --security_group_rule.direction="ingress" --security_group_rule.protocol="tcp" --security_group_rule.multiport="22,8899,8900" --security_group_rule.remote_ip_prefix="{source_public_ip}/32"

Step 2.2: Target Provisioning & Destination Setup

Before configuring the target, determine the provisioning path based on the source host firmware:

[!IMPORTANT]

• BIOS-boot Hosts & Linux: Auto-provisioning via a dedicated target template (CreateTemplate) is supported. Proceed with the template workflow below.
• UEFI Windows Hosts (Existing Server Mode Mandatory): SMS does NOT support auto-provisioning via migration templates for UEFI Windows hosts. You must NOT create a migration template.
  1. Pre-create a new target ECS on Huawei Cloud first (ensure UEFI boot mode hw_firmware_type: "uefi", matching vCPU/RAM, and disk size >= source disk).
  2. Skip CreateTemplate.
  3. Proceed directly to Phase 4 and create the task using templates/create-task-existing-server.json with "exist_server": true and "target_server.vm_id": "{target_ecs_vm_id}".

Query target VPC and Subnet configurations:

# Query VPC with pinned API version v3 to avoid multi-version preamble text breaking JSON parsing:
hcloud VPC ListVpcs/v3 --cli-region=cn-north-4 --limit=10

# Query subnets in the target VPC:
hcloud VPC ListSubnets --cli-region=cn-north-4 --vpc_id="{vpc_id}" --limit=10

Query target Project ID for the region:

# Query project ID for the specified target region (e.g., cn-north-4):
hcloud IAM KeystoneListProjects --cli-region=cn-north-4 --name="cn-north-4" --cli-query="projects[0].id"

# Or list all projects authorized for the account:
hcloud IAM KeystoneListAuthProjects

Query Image Management Service (IMS) to obtain the target OS image_id:

[!NOTE]

• Linux Images: Query public/gold images using --__imagetype="gold" with --__platform.
• Windows Server Images: Windows images on Huawei Cloud are provided under Marketplace Images. Query using --__imagetype="market" with --__platform="Windows".

# Query active public Linux images by platform (e.g., Ubuntu, CentOS, Debian, EulerOS):
hcloud IMS ListImages --cli-region=cn-north-4 --status=active --__imagetype="gold" --__platform="Ubuntu" --limit=10

# Query active Windows Server images under Marketplace Images (__imagetype="market") using platform filtering:
hcloud IMS ListImages --cli-region=cn-north-4 --status=active --__imagetype="market" --__platform="Windows" --limit=10

Extract the image UUID (id) and populate the "image_id" field in templates/create-template.json (or use it when pre-creating the target ECS).

Create a target template using a JSON specification file:

[!IMPORTANT]

• JSON Encapsulation: KooCLI requires the template definition inside a top-level "body" object to pass all REST API fields directly.
• Public vs. Private Network (publicip):
  • Public Internet (Default): Target ECS requires an EIP. Configure pay-per-traffic 300M bandwidth: "publicip": { "type": "5_bgp", "bandwidth_size": 300, "bandwidth_share_type": "PER" }
  • Private Intranet (VPN/Direct Connect): Omit public IP by configuring "publicip": {}.

hcloud SMS CreateTemplate --cli-region=cn-north-4 --cli-jsonInput="templates/create-template.json"

Customize target ECS parameters (flavor, VPC, subnet, security group, disk size, and bandwidth) in templates/create-template.json.

3. Migration Task Orchestration

List ongoing or past migration tasks:

hcloud SMS ListTasks --cli-region=cn-north-4 --limit=10

Inspect migration task status, progress percentage, subtasks, and remaining time (remain_seconds, estimate_complete_time):

# Query full task details:
hcloud SMS ShowTask --cli-region=cn-north-4 --task_id={task_id}

# Or extract remaining time and replication speed directly:
hcloud SMS ShowTask --cli-region=cn-north-4 --task_id={task_id} --cli-query="{RemainingSeconds:remain_seconds,SpeedMBs:migrate_speed,EstimateComplete:estimate_complete_time}"

Create a migration task using a JSON specification file:

[!IMPORTANT]

• JSON Encapsulation: KooCLI requires task parameters wrapped inside a top-level "body" object to pass all fields directly.
• Task Name Length: Length must be between 4 and 20 characters (4 <= length <= 20). Avoid overly long names.
• Replication Type (type): Use "MIGRATE_FILE" for Linux and "MIGRATE_BLOCK" for Windows.
• Target Mode (exist_server vs vm_template_id):
  • Template mode (BIOS/Linux): Set "exist_server": false, "vm_template_id": "{template_id}", and "vm_id": "".
  • Existing server mode (UEFI Windows): Set "exist_server": true, "target_server.vm_id": "{target_ecs_vm_id}", and "vm_template_id": "".
• Target Disks Sourcing: Map disks directly from hcloud SMS ShowServer --cli-region={region} --source_id={source_server_id}.
• Windows Disk Path Double-Escaping (KooCLI Workaround): Due to a KooCLI JSON serialization defect (tested on v7.2.12), backslashes in Windows partition paths and UUIDs must be double-escaped in --cli-jsonInput files (use 4 backslashes, e.g., "name": "C:\\\\"). Use templates/create-task-windows.json (BIOS) or templates/create-task-existing-server.json (UEFI). Note: If a future KooCLI update fixes this serialization defect, revert to standard JSON escaping ("name": "C:\\"). Verify outbound payload using --dryrun when updating KooCLI. See references/troubleshooting-guide.md.

# Create task for Linux source host (template auto-provisioning):
hcloud SMS CreateTask --cli-region=cn-north-4 --cli-jsonInput="templates/create-task.json"

# Create task for BIOS Windows source host (template auto-provisioning):
hcloud SMS CreateTask --cli-region=cn-north-4 --cli-jsonInput="templates/create-task-windows.json"

# Create task for UEFI Windows host (pre-created existing server mode):
hcloud SMS CreateTask --cli-region=cn-north-4 --cli-jsonInput="templates/create-task-existing-server.json"

For complete task definitions across operating systems and provisioning modes, see the pre-configured templates:

• Linux (Template Auto-Provisioning): templates/create-task.json
• Windows BIOS (Template Auto-Provisioning): templates/create-task-windows.json
• Windows UEFI (Existing Server Mode): templates/create-task-existing-server.json

Control migration task state (start, stop, clear, restart):

[!NOTE] After executing clear, the migration task status remains MIGRATE_SUCCESS, while the source server status (ShowServer -> state) transitions to "cleared".

# Start or pause replication task:
hcloud SMS UpdateTaskStatus --cli-region=cn-north-4 --task_id={task_id} --operation="start"

# Finalize cutover and clean up replication snapshots:
hcloud SMS UpdateTaskStatus --cli-region=cn-north-4 --task_id={task_id} --operation="clear"

# Confirm cutover completion on source server:
hcloud SMS ShowServer --cli-region=cn-north-4 --source_id={source_server_id}

Adjust replication speed throttling limit (0-1000 Mbit/s):

hcloud SMS UpdateSpeed --cli-region=cn-north-4 --task_id={task_id} --speed_limit.1.start="00:00" --speed_limit.1.end="24:00" --speed_limit.1.speed=50

4. Resource Cleanup Sequence (Task → Template)

Clean up migration resources in strict sequence after cutover or task completion:

[!IMPORTANT]

• Strict Deletion Order (Task → Template): A target template cannot be deleted while linked to an active task (returns SMS.7111). Always delete the task first.
• Automatic Template Removal (SMS.7101): When a task is created with auto-provisioning (exist_server: false), deleting the task may automatically delete the associated template. If DeleteTemplate subsequently returns SMS.7101 (Template not found), it has already been cleaned up and can be safely ignored.

1. Delete migration task first:

hcloud SMS DeleteTask --cli-region=cn-north-4 --task_id={task_id}

2. Delete target template:

hcloud SMS DeleteTemplate --cli-region=cn-north-4 --id={template_id}

5. Network Diagnostics & Troubleshooting

Inspect target security group rules and subnet network ACLs:

# Query inbound rules on the destination security group:
hcloud VPC ListSecurityGroupRules/v3 --cli-region=cn-north-4 --security_group_id.1="{sg_id}"

# Query subnet firewall / network ACL policies:
hcloud VPC ListFirewall --cli-region=cn-north-4

Inspect target ECS status and release target resources:

# Query target ECS status and attributes:
hcloud ECS ShowServer --cli-region=cn-north-4 --server_id="{target_ecs_vm_id}"

# Remove stalled or failed migration task to release target resources:
hcloud SMS DeleteTask --cli-region=cn-north-4 --task_id={task_id}

Parameter Confirmation

Before creating templates or executing migration tasks, confirm the following parameters:

KooCLI Command Format Standard

All KooCLI commands must adhere to the standard syntax:

hcloud <Service> <Operation> --cli-region=<region> [--param1=value1 ...]

• Service: Exact KooCLI service identifier starting with uppercase/title case (e.g., SMS, ECS, VPC).
• Operation: PascalCase operation identifier (e.g., ListServers, ShowOverview, CreateTask).
• Region: Mandatory parameter --cli-region=<region_id> specifying the target cloud region.
• Parameters: Structured parameters use dot notation (e.g., --vpc.id=xxx, --nics.1.id=yyy).

Reference Documents

• cli-installation-guide.md — KooCLI installation and profile configuration
• iam-policies.md — Least-privilege IAM policies for SMS, ECS, VPC, and EVS
• dataflow-diagram.md — Architecture and data flow diagrams for control and data planes
• agent-deployment-guide.md — Detailed agent installation procedures for Linux & Windows
• pre-migration-checklist.md — Compatibility checklist for OS, disk, and network ports
• troubleshooting-guide.md — Diagnostic commands, common SMS error codes, and recovery steps
• related-commands.md — Command reference table for SMS CLI operations