alibabacloud-terraform-code-generation

name

alibabacloud-terraform-code-generation

description

Use when the user wants Terraform HCL for Alibaba Cloud (Alicloud) infrastructure — new project or extending an existing one. Covers VPC, ECS, ApsaraDB RDS, OSS, SLB / ALB, Function Compute v3, ACK, and any other `alicloud_*` resource via the provider documentation and IaCService metadata. IaCService API calls should use the CallCLI-compatible tool exposed by the alibabacloud-core MCP server. For AWS → Alicloud migration, importing existing resources into state, or remote plan/apply execution, use a different skill. Triggers: "write terraform for alicloud", "generate alibaba cloud terraform", "alicloud HCL", "create alibaba cloud vpc/ecs/rds", "生成阿里云 Terraform", "阿里云 HCL", "用 Terraform 部署阿里云", "alicloud provider", "aliyun/alicloud", "terraform-provider-alicloud".

Alibaba Cloud Terraform Code Generation

Turn natural-language Alibaba Cloud infrastructure requirements into validated Terraform for the current aliyun/alicloud provider. Resource schema and validation are resolved through IaCService via MCP; Terraform provider docs and local reference files are used for HCL argument shape, examples, deprecations, and product-specific guardrails.

Hard rules (never violate)

1. Credentials — never leak, never require

NEVER read, print, ask for, or write AK/SK values anywhere — HCL, comments, env declarations, shell output, logs. The provider reads credentials itself from env, shared config, RAM role, OIDC/RRSA, sidecar, or static HCL. Do NOT recommend deprecated ALICLOUD_* or ALIBABACLOUD_* env names; current names are ALIBABA_CLOUD_ACCESS_KEY_ID, _ACCESS_KEY_SECRET, and _SECURITY_TOKEN.

2. Honest reporting — never claim a step you didn't run

Never report fmt: ok / validate: ok / plan: ok unless the corresponding command actually executed AND returned that status. When a step is skipped (tool missing, user opt-out), state "SKIPPED" (or "FAILED") with a reason. Paraphrasing real output is fine; fabricating it is not.

3. Validation and execution boundary

Never run terraform apply. Run terraform plan only when the user asks. Validation uses IaCService MCP when available, otherwise local terraform fmt/init/validate when the binary exists. Never claim validation passed unless that exact path ran successfully.

Environment (soft recommendations)

• MCP — prefer the CallCLI-compatible tool exposed by the alibabacloud-core MCP server for IaCService API calls. Tool names may be namespace-prefixed by the host client; select the tool whose name ends with AlibabaCloud___CallCLI or is documented by the installed plugin as CallCLI. Do NOT call local aliyun or helper scripts for IaCService when that MCP tool is available.
• IaCService endpoint — use --endpoint iac.cn-zhangjiakou.aliyuncs.com for all IaCService commands. Do NOT derive endpoints from region.
• Terraform fallback — local Terraform is optional and used only when IaCService validation is unavailable.

Workflow

Step 1. Parse requirement

Extract:

• region — default cn-hangzhou.
• resources[] — { alicloud_type, quantity, attributes }.
• Non-functional: multi-AZ, encryption, backup, HA, IOPS.

If ambiguous (e.g. "搭个数据库"), ask at most one clarifying question.

Step 2. Resolve target directory

Extract <target-dir> from the user's request (explicit path like myshop-infra/ or current working directory if unspecified). All subsequent file writes and static HCL checks operate in this directory. Remote validation submits the files from this directory through MCP/IaCService.

Before writing any .tf file, MUST create the directory:

mkdir -p <target-dir>

All file writes MUST prefix paths with <target-dir>/ — never write to the current working directory directly, never write to a generic outputs/ parent. After generation completes, verify the structure:

ls -R <target-dir>

Step 3. Sketch architecture

Before any HCL, sketch a dependency table — one row per resource:

resource	depends on	AZ / placement

• Expand resources[] with implied infra (VPC → VSwitch → SecurityGroup → workload); user parse often skips these.
• The expanded list is the input to Step 4's gate.

Step 4. Pre-HCL gate (MANDATORY)

For every distinct alicloud_* type from Step 3 (resources and data sources), execute 4.1 → 4.2 → 4.3. Before running any lookup, build a task-local lookup cache:

• types[] — de-duplicated final resource/data-source names from Step 3.
• catalog[type] — local catalog row and provider doc URL.
• product[type] — IaCService product when it can be determined from IaCService metadata or resource naming.
• resource_type[type] — IaCService schema response or failure.
• example[type] — selected IaCService example code, only when useful.
• provider_doc[type] — GetProviderDocument result or fallback doc, only when needed.

Never repeat the same IaCService call, catalog grep, pattern lookup, or provider doc fetch for the same key. Run independent lookups in parallel: list-products, catalog grep, pattern grep; then parallelize per-type get-resource-type.

4.1 Pre-doc lookup (MCP metadata + catalog + patterns, in parallel)

Run the live MCP metadata lookup and local targeted lookups before writing HCL. Optimize for one pass over each unique key:

(a) IaCService metadata via MCP — when a CallCLI-compatible MCP tool is exposed in the session, you MUST attempt live metadata lookup. In most clients the tool name ends with AlibabaCloud___CallCLI, but it may include a plugin or server namespace prefix. Do NOT silently skip this step. Do NOT run these commands in a local shell.

Use this de-duplicated call plan:

1. Call list-products once per generation task.
2. Determine each type's product from metadata, resource naming, or task cache.
3. Call get-resource-type once per final distinct alicloud_* type after deprecation routing; this is mandatory when CallCLI is available.
4. Call list-resource-types only when product/resource type cannot be inferred.
5. Call example APIs only for complex/nested resources, incomplete metadata, or Step 6 diagnostics that cannot be fixed from metadata plus local references.

aliyun iacservice list-products --endpoint iac.cn-zhangjiakou.aliyuncs.com
aliyun iacservice get-resource-type --resource-type alicloud_<name> --endpoint iac.cn-zhangjiakou.aliyuncs.com

# Conditional only:
aliyun iacservice list-resource-types --product <Product> --endpoint iac.cn-zhangjiakou.aliyuncs.com
aliyun iacservice list-resource-type-examples --resource-type alicloud_<name> --endpoint iac.cn-zhangjiakou.aliyuncs.com
aliyun iacservice get-resource-type-example --example-id <exampleId> --endpoint iac.cn-zhangjiakou.aliyuncs.com

Use metadata for product/resource availability, required attributes, enum values, defaults, sensitivity, ForceNew, and Computed constraints when present. For every distinct type, record one of these metadata statuses for Step 4.3 and Step 7:

• ok — include the product/resource type and the schema source returned by IaCService.
• failed — include the attempted command/API and the concise failure reason; continue with provider docs plus the local catalog.
• skipped — only allowed when no CallCLI-compatible MCP tool is exposed in the current session; include that exact reason.

Never report metadata constraints: SKIPPED if a CallCLI-compatible MCP tool was available but you did not try the IaCService command. That is a workflow failure; go back and run the metadata lookup. If a CallCLI invocation fails, record the failure as evidence and continue with provider docs plus the local catalog; do not simulate API results.

Two local lookups; run them concurrently with the live metadata lookup:

(b) Catalog lookup — use the local generated catalog as a stale-tolerant cache for common data source names plus deprecated resource/data-source routing and doc URL fallback. Normal supported resources and non-common data sources are intentionally omitted; IaCService metadata is authoritative for resource availability. The catalog (references/alicloud-providers.md) is a compact index; do NOT Read it whole. Use exact table-row grep per requested type; avoid substring patterns such as alicloud_(vpc|instance) because they overmatch:

for type in alicloud_vpc alicloud_vswitch alicloud_instance; do
  grep -E '^\| (resource|data source) \| `'"$type"'` \|' references/alicloud-providers.md
done

If a single type or routed replacement needs a follow-up:

grep -E '^\| (resource|data source) \| `alicloud_<name>` \|' references/alicloud-providers.md

Three outcomes:

• Row found, status column empty → this is a common data source row; note the [doc](<url>) from the row and proceed to 4.2.
• Row found, status DEPRECATED -> <new_name> → switch the plan to <new_name> and re-lookup. NEVER emit the deprecated name. Common catch: alicloud_fc_function → alicloud_fcv3_function.
• Row found, status DEPRECATED without replacement → stop and ask for a supported alternative; do not emit the deprecated resource/data source.
• Row not found, but IaCService get-resource-type succeeded → continue; record normal resource omitted from catalog; IaCService metadata used.
• Row not found for a non-common data source → use provider documentation lookup when available; otherwise ask before inventing a data source name.
• Row not found and IaCService also failed, skipped, or missed for a resource → stop. Ask whether the name was a typo; don't invent an alicloud_<guess>.

(c) Pattern lookup (conditional) — if the user's requirement matches a product-specific idiom listed in references/resource-patterns.md (e.g. RDS cross-AZ HA, OSS lifecycle noncurrent, VPC peering), read the relevant section. These idioms are NOT in the provider doc's Required list but are what the user actually wants (e.g. zone_id_slave_a for RDS HA is optional per the doc but required for real cross-AZ placement). Missing them produces "validates but silently wrong" output.

When a matching pattern section is found, ALL attributes listed in that section's "Required attributes" table MUST appear in the generated HCL — treat them as mandatory even if the provider doc marks them Optional.

# Quick check whether a relevant pattern exists, then Read only the section:
grep -inE "<keyword1>|<keyword2>" references/resource-patterns.md

Run one pattern grep for the user's product keywords, not one grep per resource, then cache any matching sections.

4.2 Provider doc fallback (metadata-first)

Do NOT fetch provider docs when IaCService metadata and selected official examples from 4.1 contain enough schema and usage shape for HCL generation. Provider doc fetch is not a default phase; running external documentation fetch on the fast path is a workflow failure.

Fetch provider docs only when metadata is unavailable/incomplete for the user's requirement, examples are absent/insufficient, Step 6 diagnostics cannot be fixed from metadata plus local references, or the user explicitly asks for docs.

When docs are needed, call IaCService get-provider-document through MCP first. Use --endpoint iac.cn-zhangjiakou.aliyuncs.com, call once per distinct type, and cache provider_doc[type].

If get-provider-document fails, fall back to the catalog GitHub URL/raw URL. If all documentation channels fail, use the local catalog plus IaCService metadata from 4.1 and prefix recitation with doc unreachable: used metadata/local catalog.

4.3 Recite (proof-of-read)

Before writing HCL, emit a compact per-resource brief:

• Required param names only from IaCService metadata/doc/local fallback
• 2–5 key Optional/nested params relevant to the user's requirement
• Non-obvious pattern attrs from resource-patterns.md, if any
• Metadata constraints from IaCService, or metadata constraints: SKIPPED (<reason>) / metadata constraints: FAILED (<reason>)
• Metadata evidence — attempted IaCService command/API for this type and its status (ok, failed, or skipped). If this line is missing, Step 4 is incomplete and HCL generation must not start.
• Doc evidence — not fetched (metadata sufficient) on the fast path, or the provider doc/raw URL when 4.2 fetched documentation.

If Required or Optional params are missing, return to 4.2. Skipping or using a partial recitation is a hard failure; metadata/doc failure uses local catalog fallback, not memory.

Step 5. Generate

5.1 Write HCL from the recitations, not memory

Use ONLY the params established in 4.3. If you need a param that wasn't in the recited brief, re-fetch 4.2 with a deeper read; do not guess. Use the fastest batch write method allowed by the host client (single batch edit, script, or heredoc); avoid serial per-file writes unless required.

Before writing a field, look up the resource in references/deprecated-fields.md for local fix actions (see §5.5):

grep '`alicloud_<resource>`' references/deprecated-fields.md

If the user's requirement touches a product with a specific usage pattern (e.g. RDS cross-AZ HA, VPC peering, OSS lifecycle), also consult references/resource-patterns.md for the non-obvious attributes.

5.2 Data-source enforcement (MANDATORY — no hardcoded IDs)

Resolve via data blocks, never literals. These also pass Step 4's gate:

• zone_id → data "alicloud_zones" (filter by available_resource_creation).
• image_id → data "alicloud_images" (filter by name_regex, owners = "system", most_recent = true).
• instance_type → data "alicloud_instance_types" (filter by cpu_core_count, memory_size, AZ).
• Never put literal defaults for zone_id, image_id, or ECS instance_type variables. Resource arguments must reference the data source result, not a hardcoded ID or a variable default.

Generate variables.tf for all variable blocks; every generated var.* MUST have type and description. Generate outputs.tf for useful non-sensitive resource IDs, endpoints, and names. Terraform merges all *.tf equivalently.

5.3 Provider block (content contract)

HARD GATE: must pass before Step 6. The provider contract is mandatory, not stylistic. Any missing block, open-ended provider version, hardcoded region, or missing configuration_source must be fixed before validation.

Two Terraform blocks must appear somewhere in the project's *.tf files. Terraform merges all *.tf in a directory, so file organization is a style choice, not a contract — see "File organization" below.

Block 1 — terraform { required_providers {} }:

terraform {
  required_version = ">= 1.5"
  required_providers {
    alicloud = {
      source  = "aliyun/alicloud"
      version = "~> 1.280"
    }
  }
}

• Provider version: resolve the latest published stable aliyun/alicloud 1.x version through IaCService metadata when available, then write a pessimistic minor constraint (1.278.0 -> ~> 1.278). Lookup sources, in order:
  1. CallCLI-compatible MCP tool with aliyun iacservice list-terraform-provider-versions if supported by the installed MCP/proxy version.
  2. CallCLI-compatible MCP metadata responses that include provider version information.
  3. Provider registry/GitHub release metadata only when the host client has an explicit safe documentation fetch mechanism.
• If lookup fails, fall back to ~> 1.280 (last reviewed 2026-07-02). Accepted form is ~> 1.<minor> or ~> 1.<minor>.<patch> from a confirmed or conservative stable 1.x release. Do NOT write open-ended constraints (>= 1.x, >= 1.239.0) or bare version strings.

Block 2 — provider "alicloud" {} with BOTH region = var.region and configuration_source:

provider "alicloud" {
  region               = var.region
  configuration_source = "AlibabaCloud-Agent-Skills/alibabacloud-terraform-code-generation/<32hex>"
}

• configuration_source is required. Resolve one session id per task: use SKILL_SESSION_ID only if it is exactly 32 hex characters; otherwise generate one 32-character lowercase hex value once. Replace <32hex> with the real id.
• region MUST reference var.region, not a hardcoded literal.

File organization (recommended, not required): conventional split is terraform.tf (Block 1) + providers.tf (Block 2). Also acceptable: a single versions.tf containing both blocks, or either block at the top of main.tf. Pick what fits the project — Terraform merges all *.tf equivalently. Do NOT add a filename check; run the content check below instead.

Post-generation verification: run scripts/static_checks.sh provider <target-dir>. All lines must return OK_*. If any fails, fix the offending content and re-run. Do NOT proceed to Step 6 with BAD_OR_MISSING_VERSION, MISSING_CFG_SOURCE, or HARDCODED_REGION. Do NOT claim provider verification unless the script emitted OK_VERSION, OK_CFG_SOURCE, and OK_REGION_VAR.

5.4 Style baseline

• 2-space indent; = aligned within a block; snake_case semantic resource labels (alicloud_vswitch.app_a, not vsw1).
• Every tag-supporting resource should carry a non-empty tags block for ops hygiene — pick reasonable keys for the scenario (common choices: ManagedBy, Project, Environment, CreatedBy). Skill does not prescribe specific tag keys or values.

5.5 Deprecated-field audit — static grep pass (MANDATORY)

Run before terraform is needed — this is a pure-grep pass on the HCL you just wrote. IaCService/provider diagnostics decide whether a field is currently deprecated; references/deprecated-fields.md is a compact fix-action map for high-risk fields whose replacement is not always returned by IaCService. For every generated resource, grep the project against it and handle each row-kind:

• rename row → if the old field name appears in HCL you just wrote, replace it with the new field name. Examples that show up most often:
  • alicloud_ram_role: name → role_name, document → assume_role_policy_document
  • alicloud_security_group: name → security_group_name
  • alicloud_db_database: name → data_base_name
• split / soft-split row → do NOT write the inline field on the parent. Declare the replacement sub-resource only when the user's requirement needs that capability, or when references/resource-patterns.md says the sub-resource has an explicit safe default. Example: for OSS buckets, alicloud_oss_bucket_acl defaults to private, but logging/CORS/website sub-resources are omitted unless the user asks for those features.
• deprecated-no-replacement row → stop using the field, no substitute.

Applies only to files written in this generation — do NOT refactor pre-existing user files you weren't asked to touch.

HARD GATE: must pass before Step 6 — run scripts/static_checks.sh deprecated <target-dir>. If it produces any DEPRECATED: line, fix using the Action column in references/deprecated-fields.md, then re-run until every line returns OK:. Before the audit, explicitly grep each generated resource type in references/deprecated-fields.md; any rename row means the old field name is forbidden in generated HCL. Do NOT proceed to Step 6 with any DEPRECATED: output. Do NOT claim "verified" unless the script produces all OK:.

Step 6. Validate

Prefer IaCService remote validation through the available CallCLI-compatible MCP tool, usually the tool whose name ends with AlibabaCloud___CallCLI, with aliyun iacservice validate-module; use endpoint --endpoint iac.cn-zhangjiakou.aliyuncs.com. Related commands are list-products, get-resource-type, get-provider-document, list-terraform-provider-versions, and validate-module --source Upload. For validate-module, preserve real newlines in --code and generate a fresh UUID --client-token.

Remote validation limits: IaCService validates uploaded Terraform in a remote sandbox. Do NOT introduce dependencies that require local filesystem access or unregistered providers before this step:

• No local file functions in remotely validated code: file(), filebase64(), templatefile(), fileset(), archive_file, or source = "./..." module references. Inline small generated artifacts when needed, or omit artifact packaging from remote validation and explain that boundary.
• Avoid third-party providers such as hashicorp/archive in generated modules. The validation environment is intended for the Alibaba Cloud provider path; if another provider is unavoidable, report Validation: SKIPPED or FAILED with the exact IaCService diagnostic instead of adding local-only workarounds.
• Do not use local paths (file://, relative zip/code paths, or machine-local directories) in arguments that IaCService must evaluate.

If CallCLI is unavailable or fails before validation starts, fall back to local Terraform when present:

(cd <target-dir> && terraform fmt -recursive && terraform init -backend=false && terraform validate -json)

If terraform is not on PATH, report exactly: Validation: SKIPPED (terraform binary not on PATH).

Loop up to 3 fix attempts for either validation path:

1. Fix diagnostics with severity error.
2. Fix any deprecation diagnostics or [DEPRECATED] strings.
3. Re-run the same validation path. Stop only with no errors and no deprecation diagnostics.

Step 7. Coverage check + summarize

MANDATORY — runs regardless of generation outcome. The Files written:, IaCService metadata:, Validation:, and Deprecation routing: labels are the final contract; do not skip or rename them.

Coverage check. Enumerate resource blocks in the generated HCL and compare with Step 3's sketch. If any row is missing, return to Step 5, add it, then rerun Step 5 checks and Step 6; do not skip implicit resources.

Summary template — print in the user's language, using this structure:

Files written:
<path/to/file1>
<path/to/file2>
...

IaCService metadata: <ok | SKIPPED (CallCLI-compatible MCP tool not exposed) | FAILED (<reason>)>

Validation: <iacservice validate-module: ok | terraform fmt+validate: ok | SKIPPED (...) | FAILED (...)>

Deprecation routing: <If re-routed: `<original_name>` → `<new_name>`; else: None>

<optional architecture notes, design decisions, deploy hints>

Allowed Validation: values:

• Validation: iacservice validate-module: ok
• Validation: terraform fmt+validate: ok
• Validation: SKIPPED (terraform binary not on PATH)
• Validation: SKIPPED (<reason>)
• Validation: FAILED (<diagnostic excerpt>)

IaCService metadata: summarizes Step 4.1 only. Use ok only when every generated resource/data source had successful metadata lookup; use SKIPPED (CallCLI-compatible MCP tool not exposed) only when no CallCLI-style MCP tool is available; otherwise use FAILED (<reason>).

Step 8 (internal). Where execution belongs — DO NOT narrate to user

After Step 7, stop. Do not run plan/apply. Do not expose orchestration phrases such as "returning control", "handoff", or "upstream caller". If the user asks to deploy, point to their normal Terraform workflow or alibabacloud-spec-ops:alibabacloud-executing-plans.

References

Source	When to read
references/alicloud-providers.md (local)	Step 4.1 — resource existence, deprecation mark, doc URL
OSS provider doc mirror, then catalog GitHub/raw URL	Step 4.2 — fallback docs for HCL argument shape and examples
references/deprecated-fields.md (local)	Step 5.1 + Step 5.5 — fix actions for high-risk deprecated fields
references/resource-patterns.md (local)	Step 5.1 — product-specific idioms not emphasized by the provider doc (RDS HA, …)
scripts/static_checks.sh	Step 5.3 + Step 5.5 — provider block and deprecated-field verification