/alibabacloud-terraform-import

name: alibabacloud-terraform-import
description: This skill should be used when the user asks to "导入阿里云资源到 Terraform", "terraform import 阿里云", "将现有云资源纳入 Terraform 管理", "阿里云资源迁移 Terraform", "生成 terraform state", "import alicloud resources", "阿里云 IaC 迁移", "阿里云 Terraform 导入", or needs to manage existing Alibaba Cloud resources with Terraform. Guides users step-by-step through environment check, authentication, resource discovery, HCL generation, state import, validation, and dependency graph. Supports both one-time migration and incremental sync.
version: 0.1.0

Alibaba Cloud Resource Terraform Import Wizard

Step-by-step guide to import existing resources under an Alibaba Cloud account into local Terraform management. Automatically performs environment checks, resource discovery, HCL generation, state import, etc. Users only need to confirm at key decision points.

Two modes are supported:

• **One-time migration**: Complete Phase 1-9 end to end
• **Incremental sync**: When a Terraform working directory already exists, jump directly to incremental sync mode

Resource Support Scope

• **Theoretical scope**: Any resource in the alicloud provider that has a Read method (i.e., can read state from the cloud). Most resources can be imported directly via the `terraform import` command or `import` blocks (Terraform 1.5+); a few resources without an Importer can be imported by manually constructing tfstate, but this requires exact matching of the provider's state structure and carries some risk. Check support status at `https://registry.terraform.io/providers/aliyun/alicloud/latest/docs`.
• **Pre-built resources**: ~50 common resource types (networking, compute, storage, databases, load balancing, DNS, RAM, ACK, FC) with verified API discovery commands, HCL templates, and import ID formats in `references/`
• **Beyond pre-built scope**: Will look up provider docs on the fly to provide commands and templates; accuracy depends on documentation content; users should verify before executing

---

Command Format Requirements

**All aliyun CLI commands must use plugin mode (lowercase-hyphenated format). CamelCase command names and parameter names are prohibited.** Violating this rule will cause parameter errors or call failures.

**Example (correct plugin-mode format):**

aliyun vpc describe-vpcs --biz-region-id cn-shanghai --page-size 50

**Parameter conversion rules:**

• **Region**: Prefer `--biz-region-id` (business parameter, corresponds to the API's RegionId); `--region` (framework parameter, controls endpoint region) should only be used when the API's RegionId is optional
• **Pagination**: `--page-size` (not PageSize)
• **Others**: Convert CamelCase parameter names to lowercase-hyphenated (VpcId -> `--vpc-id`, InstanceIds -> `--instance-ids`). Use `aliyun <product> <command> --help` to confirm
• **OSS**: Use `aliyun ossutil ls oss://` exclusively

---

Phase 1: Environment Check

Run the following commands to detect the environment:

echo "=== aliyun CLI ===" && aliyun --version 2>&1 || echo "NOT_INSTALLED"
echo "=== terraform ===" && terraform --version 2>&1 || echo "NOT_INSTALLED"
echo "=== python3 ===" && python3 --version 2>&1 || echo "NOT_INSTALLED"
echo "=== OS ===" && uname -s 2>&1

Automatically handle missing tools based on output:

• aliyun CLI missing (macOS): Run `brew install aliyun-cli`
• aliyun CLI missing (Linux): Run `curl -sSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz | tar xz && sudo mv aliyun /usr/local/bin/`
• terraform missing (macOS): Run `brew tap hashicorp/tap && brew install hashicorp/tap/terraform`
• terraform missing (Linux): Direct user to https://developer.hashicorp.com/terraform/install for manual installation (requires root)

Once all tools are ready, proceed to Phase 2.

**Configure aliyun CLI AI-Mode:**

All aliyun CLI commands must have AI-Mode configured so Alibaba Cloud can identify AI invocation scenarios and provide optimized support. Before executing any aliyun CLI command, run:

# Enable AI-Mode (required)
aliyun configure ai-mode enable

# Set User-Agent identifier (required)
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-terraform-import"

# Update plugins to latest version (recommended)
aliyun plugin update

All subsequent aliyun CLI commands will automatically carry AI-Mode and User-Agent identifiers. See the "Command Format Requirements" section above for command formatting rules.

**Disable AI-Mode (when the session ends or if needed):**

aliyun configure ai-mode disable

---

Phase 2: Authentication Configuration

This Skill relies on the Alibaba Cloud default credential chain for authentication, supporting the following methods (by priority): 1. Environment variables (ALICLOUD_ACCESS_KEY / ALICLOUD_SECRET_KEY) — **highest priority** 2. aliyun CLI configuration file (~/.aliyun/config.json) 3. ECS RAM role (only when running on ECS)

**Important**: The Terraform alicloud provider and aliyun CLI each read credentials independently, both prioritizing environment variables. When environment variables and CLI profile point to different accounts, environment variables take precedence.

**Verify authentication:**

Verify identity via the default credential chain (without explicitly passing AK/SK):

aliyun sts get-caller-identity 2>&1

Analyze the output:

• Confirm AccountId and UserId, record Region
• **If the credential source is unexpected** (e.g., environment variables and CLI profile point to different accounts), inform the user of the credential conflict and suggest unifying credential configuration before retrying

If an error occurs, prompt the user to:

• Check whether credentials are configured (via `aliyun configure` or environment variables)
• Check permissions (requires ReadOnlyAccess or corresponding resource Describe permissions)
• Refer to `references/ram-policies.md`