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
- KooCLI (
hcloud): Installed and authenticated with a valid profile (cn-north-4,ap-southeast-3, etc.).- Follow instructions in
references/cli-installation-guide.md.
- Follow instructions in
- 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), and8900(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
443allowed 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.
- Linux: Inbound TCP port
- Source Server Network & Environment:
- Outbound TCP port
443open to SMS control plane:sms.cn-north-4.myhuaweicloud.com(China Site) orsms.ap-southeast-3.myhuaweicloud.com(International Site - Singapore). - Outbound TCP ports
22,8899,8900open 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.
- Outbound TCP port
- IAM Permissions: Sufficient permissions for
SMS FullAccess,ECS CommonOperations,VPC Administrator, andEVS CommonOperations.- See least-privilege definitions in
references/iam-policies.md. - See complete pre-migration checklist in
references/pre-migration-checklist.md.
- See least-privilege definitions in
Workflow
- Phase 1 - Assessment & Scenario Selection:
- Scenario A (Source Host Already Registered): Locate the host using
hcloud SMS ListServers --cli-region={region}, retrievesource_server_id, verify 14 pre-checks viaShowServer, 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
ListServerspost-installation). (Note: If registration state is unknown, runhcloud SMS ListServers --cli-region={region}first).
- Scenario A (Source Host Already Registered): Locate the host using
- 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.comfor China Site;sms.ap-southeast-3.myhuaweicloud.comfor International Site Singapore), and Enterprise Project ID. - 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.
- Standard Mode (BIOS Hosts & Linux): Create a target template (
- Phase 4 - Replication Task Execution: Create migration task (name: 4–20 chars) with disk layout mapped from
ShowServer. For BIOS/Linux, linkvm_template_id(exist_server: false); for UEFI Windows, specifytarget_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. - Phase 5 - Incremental Sync & Cutover: Run delta synchronization passes during maintenance window, finalize cutover via
UpdateTaskStatus --operation="clear", verify source server transitions toclearedstate (task remainsMIGRATE_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=10Optionally 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.shon Linux or restartSMS-AgentWindows service).
- When all 14 pre-checks report
-
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-4to confirm registration and obtainsource_server_id.
- The source host is not yet registered in SMS. Perform preliminary offline checks (see
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_prefixto 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.
- 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).- Skip
CreateTemplate.- Proceed directly to Phase 4 and create the task using
templates/create-task-existing-server.jsonwith"exist_server": trueand"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_servervsvm_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
disksdirectly fromhcloud 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-jsonInputfiles (use 4 backslashes, e.g.,"name": "C:\\\\"). Usetemplates/create-task-windows.json(BIOS) ortemplates/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--dryrunwhen updating KooCLI. Seereferences/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 remainsMIGRATE_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. IfDeleteTemplatesubsequently returnsSMS.7101(Template not found), it has already been cleaned up and can be safely ignored.
- Delete migration task first:
hcloud SMS DeleteTask --cli-region=cn-north-4 --task_id={task_id}
- 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:
| Parameter | Required | Description | Example Value |
|---|---|---|---|
--cli-region |
Yes | Target Huawei Cloud region: cn-north-4 (China Site) or ap-southeast-3 (International Site - Singapore) |
cn-north-4 / ap-southeast-3 |
source_server_id |
Yes | Source server UUID registered with SMS (retrieved from ListServers in Scenario A, or post-registration in Scenario B) |
d8c8c498-2e90-499e-a022-4c0463ab1c98 |
os_type |
Yes | Operating system family (LINUX or WINDOWS) |
LINUX / WINDOWS |
migration_type |
Yes | Replication data copy type (MIGRATE_FILE for Linux; MIGRATE_BLOCK for Windows) |
MIGRATE_FILE (Linux) / MIGRATE_BLOCK (Windows) |
flavor |
Yes | Target Huawei Cloud ECS instance specification | c7.large.2 / x1.2u.4g (Flexus X) |
image_id |
Conditional | Target OS image UUID queried via IMS using --__platform (Linux: --__imagetype="gold" --__platform=...; Windows: --__imagetype="market" --__platform="Windows"; used for template or pre-creating target ECS) |
c3d4e5f6-a7b8-9c0d-1e2f-3a4b5c6d7e8f |
firmware |
Yes | Source host boot firmware from ShowServer (BIOS or UEFI). UEFI Windows requires existing server mode. |
BIOS / UEFI |
exist_server |
Yes | Target server mode: false for template auto-provisioning (BIOS/Linux); true for pre-created existing server (mandatory for UEFI Windows) |
false / true |
vm_id |
Conditional | Target ECS UUID (required when exist_server=true, e.g., UEFI Windows; empty string for template auto-provisioning) |
e7b8c9d0-1a2b-3c4d-5e6f-7a8b9c0d1e2f |
vm_template_id |
Conditional | Target template UUID from CreateTemplate (used when exist_server=false; empty string when exist_server=true) |
e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b |
vpc_id |
Yes | Target Virtual Private Cloud UUID | a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d |
subnet_id |
Yes | Target VPC Subnet UUID | b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e |
sg_id |
Yes | Target Security Group UUID (by default, created newly with minimal rules; or specify existing SG) | c3d4e5f6-a7b8-9c0d-1e2f-3a4b5c6d7e8f |
source_ip |
Yes | Source server IP for target SG ingress: public egress IP ({source_public_ip}) for internet; private IP ({source_private_ip}) for VPN/Direct Connect |
198.51.100.25 (Public) / 10.0.1.50 (Private) |
project_id |
Yes | Target Huawei Cloud Project UUID queried via hcloud IAM KeystoneListProjects --name="{region}" --cli-query="projects[0].id" |
a64c6153e3c646e681cc664726d8a24d |
project_name |
Yes | Target Huawei Cloud Project Name | cn-north-4 |
target_server_name |
Yes | Target ECS instance name | ecs-target-server-01 |
task_name |
Yes | Migration task name (4–20 characters; avoid overly long names) | MigrationTask |
target_disks |
Yes | Target disk and partition mapping retrieved from hcloud SMS ShowServer --cli-region={region} --source_id={source_server_id} |
Sourced from ShowServer output |
network_mode |
Yes | Network replication mode (PUBLIC internet by default; PRIVATE for VPN / Direct Connect / VPC Peering) |
PUBLIC / PRIVATE |
publicip |
Yes | Template EIP: pay-per-traffic 300M (bandwidth_size: 300) in PUBLIC mode; {} in PRIVATE mode |
Configured per network_mode |
use_public_ip |
Yes | Task public IP flag (true in PUBLIC mode; false in PRIVATE mode) |
true (PUBLIC) / false (PRIVATE) |
migration_ip |
No | Task migration IP ("" in PUBLIC mode; target private IP in PRIVATE mode) |
"" (PUBLIC) / 172.16.10.100 (PRIVATE) |
speed_limit |
No | Bandwidth throttle limit in MB/s (0 = unlimited) | 50 |
start_target_server |
No | Auto-start target ECS upon replication finish (true/false) |
false |
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