Alibabacloud Terraform Code Generation

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 ` 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 

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

ls -R 

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.

1. Call list-resource-types only when product/resource type cannot be inferred.
2. 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_ --endpoint iac.cn-zhangjiakou.aliyuncs.com

# Conditional only:
aliyun iacservice list-resource-types --product  --endpoint iac.cn-zhangjiakou.aliyuncs.com
aliyun iacservice list-resource-type-examples --resource-type alicloud_ --endpoint iac.cn-zhangjiakou.aliyuncs.com
aliyun iacservice get-resource-type-example --example-id  --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_` \|' references/alicloud-providers.md

Three outcomes:

• Row found, status column empty → this is a common data source row; note

the [doc]() from the row and proceed to 4.2.

• Row found, status DEPRECATED -> → switch the plan to

` and re-lookup. NEVER emit the deprecated name. Common catch: alicloudfcfunction → alicloudfcv3function`.

• 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_.

(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 "|" 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

() / metadata constraints: FAILED ()`

• 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_`' 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.

1. CallCLI-compatible MCP metadata responses that include provider

version information.

1. 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. or ~> 1.. 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/"
}

• 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 `` 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 . All lines must return OK_*. If any fails, fix the offending content and re-run. Do NOT proceed to

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aliyun
• Source: aliyun/alibabacloud-agent-toolkit
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.