MGC Cross-Region Migration
Run and troubleshoot Huawei MGC/SMS migrations
MGC Cross-Region Migration
Overview
This skill runs the single-source Huawei Cloud server migration flow implemented in this repository, from precheck to task startup and result validation. It keeps execution deterministic by following the exact command sequence and error-handling rules already implemented in scripts/mgc_migrate.py.
Architecture: Terraform (main.tf) reads terraform.tfvars, maps the values to runtime environment variables, and invokes scripts/run_migration.sh, which calls python3 scripts/mgc_migrate.py. That script signs and issues HTTPS requests directly against the Huawei Cloud IAM, SMS, ECS, and VPC REST APIs (no KooCLI/hcloud involved) to create a migration project, register a migration task, and poll it to completion. Default policy is SMS first; when precheck/runtime indicates an incompatible source (for example SMS.6504), the script switches to rsync phases (full_sync -> incremental_sync -> cutover_sync).
Applicable scenarios:
- Migrating a single on-prem VMware VM or another-cloud ECS instance into Huawei Cloud via Terraform + SMS/rsync (
scripts/mgc_migrate.py). - Migrating an AWS EC2 instance directly into Huawei Cloud via the standalone rsync path (
scripts/run_aws_migration.sh+aws_to_huawei_direct.py/aws_to_huawei_rsync.py), when the source is AWS-specific (EC2 PEM-key auth, AWS CLI/API source discovery) rather than going through SMS. - Source hosts that SMS cannot handle natively, requiring rsync-based staged migration instead.
- Post-migration troubleshooting: SSH/TCP-22 unreachable, cloud-init failures, stale SMS tasks/quota errors.
- Postmortem/experience-capture requests after a migration run.
Example user requests:
- "Migrate this VMware VM in la-north-2 to la-south-2."
- "帮我把这台 AWS EC2 实例迁移到华为云。"
- "terraform apply 报错 SMS.8115,怎么处理?"
- "SMS 显示迁移成功但是 SSH 连不上目标机器,帮我排查。"
- "帮我把这次迁移过程的踩坑记录总结一下。"
Prerequisites
- Terraform
>= 1.5.0onPATH. Verify withterraform version. - Python 3.8+ on
PATH(verify withpython3 --version).scripts/mgc_migrate.pyonly uses the standard library; the optional VPN-bridge fallback path additionally importspexpect, install it only if that path is used (pip install pexpect). - This skill does not use Huawei Cloud KooCLI (
hcloud). All Huawei Cloud API calls are issued as signed HTTPS requests fromscripts/mgc_migrate.py; no separate CLI installation is required. - Credentials: set
access_key/secret_key(anddomain_nameif needed) interraform.tfvars. Terraform passes them to the migration script only as local-exec environment variables (HC_AK/HC_SK); never print them, log them, or paste them into chat. See references/iam-policies.md for the required IAM permissions. - Permission failure handling (MUST): if any API call fails with a permission/
403error, open references/iam-policies.md, show the user the exact missing permission and the minimal policy JSON, have them grant it in the IAM console, then pause until the user confirms the grant before retrying.
Workflow
- Confirm prerequisites before running any write operation.
- Prepare Terraform inputs in
terraform.tfvars. - Before migration, precheck and cleanup old source-bound SMS tasks if they can occupy the same source VM.
- Execute Terraform so it calls
scripts/run_migration.shandpython scripts/mgc_migrate.py. - Verify
out/migration_result.json; if method is rsync, also verifyout/rsync_execution.json. - Run postcheck for
vpc-migration, EIP binding, source/target security-group connectivity, and SSH/TCP-22 reachability. - If SSH/TCP-22 fails after SMS or rsync reports success, inspect ECS console output before making more network changes.
- Troubleshoot by matching error codes and postcheck symptoms to the runbook.
- Summarize recurring issues with the lessons reference when the user asks for postmortem/experience capture.
Core Commands
Validate preconditions, then inspect the key files before execution:
main.tf,variables.tf,terraform.tfvars
Run the migration:
terraform init
terraform apply -auto-approve
If apply returns No changes for terraform_data.mgc_region_migration (same run fingerprint), force one execution:
terraform apply -replace=terraform_data.mgc_region_migration -auto-approve
Terraform's local-exec maps tfvars into runtime env vars and calls:
scripts/run_migration.shpython scripts/mgc_migrate.py
Core API chain executed by the script:
POST /v3/privacy-agreementsPOST /v3/migprojectsGET /v3/sourcesPOST /v1.1/{project_id}/cloudserversPOST /v3/tasksPOST /v3/tasks/{task_id}/action(start)
Parameter Confirmation
Confirm these terraform.tfvars values with the user before applying (defaults shown are used unless the user requests changes):
| Parameter | Required | Default | Notes |
|---|---|---|---|
access_key / secret_key | Yes | — | Never echo or hardcode; see Prerequisites |
source_server_id | Yes | — | Must already be registered/connected in SMS |
target_image_id | Yes | — | Must exist in target_region |
source_region | No | la-north-2 | |
target_region | No | la-south-2 | |
target_vpc_name | No | vpc-migration | Confirm target-region VPC quota before creation |
sms_endpoint | No | https://sms.ap-southeast-3.myhuaweicloud.com | |
preferred_migration_method | No | sms | Falls back to rsync automatically on SMS.6504 |
rsync_source_host/port/user/password | Conditional | — | Required only for rsync fallback |
target_rsync_ssh_key | Conditional | — | Path on the source host to an operator-provisioned private key already trusted by the target; required for rsync fallback |
Confirm with the user before running: source server ID, target image ID, and that overwriting existing data on the target ECS is accepted (SMS migration side effect).
Output Format
Check the result artifact:
cat out/migration_result.json
Ensure the JSON includes at least:
migproject_idtask_idsource_sms_server_idtarget_server_idtask_state
If task_state is not terminal or the user asks for deeper diagnosis, use the troubleshooting guidance in references/runbook.md. Treat existing out/migration_result.json as historical unless it was just generated in the current run.
For a complete run package, also keep:
out/precheck_task_cleanup.jsonout/postcheck_network.jsonout/task_poll_latest.jsonout/precheck_source_checks.jsonout/rsync_execution.json(when fallback path is used)out/target_console_output*.txt(when SSH/TCP-22 postcheck fails)
Verification Method
Run the three verification tiers in references/verification-method.md before treating a migration as done: installation verification (Terraform/Python present), configuration verification (credentials resolve without printing secrets), and functional verification (out/migration_result.json reaches a terminal task_state and SSH/TCP-22 postcheck passes).
Best Practices
Apply existing built-in fallbacks before manual changes:
- If task creation returns
SMS.6617, allow fallback fromMIGRATE_BLOCKtoMIGRATE_FILE. - If source check returns
SMS.6504, skip SMS task creation and switch to rsync staged migration. - If task creation returns
SMS.6602, allow retry withuse_public_ip=false. - If task creation returns
SMS.7605, allow cleanup of failed task and retry. - If
SMS.7605persists even after retry/new target ECS, check and delete historical tasks bound to the same source (including oldMIGRATE_SUCCESStasks), then retry. - If
SMS.6603appears, stop and require SMS-Agent installation/start on source host. - If migration project creation returns
SMS.8115, clean old migration projects (prefer auto-generatedmgc*projects) to bring total count below 50, then rerunterraform apply. - If VPC creation fails with
VPC.0114(quota exceeded), stop and free quota first (delete unused VPC or increase quota), then rerunterraform apply. - If task query returns
SMS.7703(Task doesn't exist), do not trust staletask_id; query live task list by source and continue with the current task. - If task is
RUNNINGbutprogressis null, keep polling taskstateand verify target ECS status in parallel. - If task is
MIGRATE_SUCCESSand target ECS isACTIVEbut SSH/TCP-22 isclosed_or_timeout, inspectout/postcheck_network.jsonand ECS console output before adding more SG rules. - If console output contains cloud-init
Failed loading yaml blobor another YAML parse error, treat target user-data bootstrap as invalid; recreate the target, then rerun postcheck. user-data carries only SSH-config-independent bootstrap (network reachability and the optional VPN client). - If console output shows only
Starting OpenSSH server daemon...without a clear started service andci-info: no authorized ssh keys fingerprints found, verify network reachability and the operator-provisioned key trust on the target from VNC/serial console; this skill never writesauthorized_keys, editssshd_config, or restartssshd.
Do not invent alternative API sequences unless the user explicitly asks to modify migration logic. Prefer read-only/Describe/List/Show calls when only diagnosing, and require explicit user confirmation before any operation that overwrites or restarts the target ECS.
Migration Problem and Experience Summary
When the user asks for "迁移过程的问题总结", "经验复盘", "踩坑记录", or "postmortem", load references/lessons-learned.md and report in this order:
- Symptom and code (
VPC.0114,SMS.7703,SMS.6603,SSH closed_or_timeout, etc.). - Root cause validated from logs/output.
- Corrective action already proven in this repo.
- Preventive rule to apply before next run.
- Concrete timestamps from latest result JSON (for example
task_started_at_cn,task_finished_at_cn) to avoid stale-history confusion.
References
- references/iam-policies.md — required IAM permissions and minimal policy JSON.
- references/verification-method.md — installation/configuration/functional verification steps.
- references/acceptance-criteria.md — pass/fail criteria for a migration run.
- references/runbook.md — command-level execution checklist, tfvars-to-env mapping, error-code-oriented diagnosis steps, post-run verification checklist.
- references/lessons-learned.md — structured migration issue summary (
symptom -> root cause -> action -> prevention) and reusable troubleshooting experience. - references/reuse-bundle.md — packaged migration assets/manifest and reusable command sequence for future similar migrations.
- references/migration-skill-summary.md — concise end-to-end summary of this skill and the latest validated run facts.
Notes
- Never echo, log, or hardcode
access_key/secret_key; they must only flow throughterraform.tfvars-> Terraform local-exec env vars. - SMS migration overwrites data on the target ECS; always get explicit user confirmation before
terraform apply. - This skill is currently exercised on Windows paths/PowerShell in some environments and bash/git-bash in others; confirm the user's shell before pasting commands verbatim.
- Known limitation:
SMS.7703can surface from stale historicalout/migration_result.json; always re-query the live task list by source rather than trusting a cachedtask_id. target_admin_password(->TARGET_ADMIN_PASSWORD) has no built-in default; it must be set explicitly to a strong password before runningmgc_migrate.pyor the AWS-source scripts. Inmgc_migrate.pyand the AWS-source scripts it is used only as the create-instance APIadminPass; user-data never enables password SSH login, editssshd_config, or restartssshdon the target.- The rsync fallback authenticates to the target only with an operator-provisioned SSH key: set
TARGET_RSYNC_SSH_KEYto the private key path on the source host, and have operations trust its public half on the target (or pre-establish source-to-target passwordless SSH). The AWS-source scripts (aws_to_huawei_direct.py/aws_to_huawei_rsync.py) use the same model:rsyncruns on the source host and pushes to the target overssh -i, so each transfer has exactly one remote side and the key must exist on the source host. If the key is missing or denied, the script stops with manual guidance instead of modifying the target. The rsync fallback never writesauthorized_keys, changessshd_config, or restartssshd. ENABLE_VPN_BRIDGE=truerequireslocal_vpc_id/LOCAL_VPC_IDto be set explicitly (the bridge host's own VPC ID is no longer auto-detected via the cloud metadata endpoint).
Relationship to huawei-cloud-sms-host-migrator: that skill is a general, interactive SMS-console/API assistant for ad-hoc host migrations from any source (IDC, Alibaba Cloud, Tencent Cloud, AWS) to Huawei Cloud. This skill is narrower and automation-first: it drives the same underlying APIs (SMS for most sources, direct rsync for AWS EC2) through a fixed Terraform + Python pipeline (main.tf -> scripts/run_migration.sh -> mgc_migrate.py, or scripts/run_aws_migration.sh -> aws_to_huawei_direct.py/aws_to_huawei_rsync.py) for deterministic, single-source runs with built-in rsync/VPN-bridge fallback that huawei-cloud-sms-host-migrator does not provide. Prefer this skill when the user already has (or wants) a Terraform-driven, scriptable migration pipeline for a single source; prefer huawei-cloud-sms-host-migrator for one-off, console-guided migrations.
- Downloads
- 158All time
- Security audit
- Review
- Last updated
- 2w ago
- Current version
- v1.0.1
- License
- MIT-0
