iac-code 0.1.0__py3-none-any.whl

iac_code/skills/bundled/iac_aliyun/references/cloud-products/rds.md

@@ -0,0 +1,95 @@
+# 阿里云 RDS 选型指南
+
+## 引擎选择
+
+| 引擎 | 推荐场景 | 说明 |
+|------|----------|------|
+| MySQL | Web 应用、电商、SaaS | 生态最广，开源友好 |
+| PostgreSQL | 复杂查询、GIS、分析 | 功能最全，支持 JSON、扩展 |
+| SQL Server | .NET 应用、企业系统 | Windows 生态，需授权费 |
+| MariaDB | MySQL 替代 | 兼容 MySQL，开源 |
+
+**推荐选择**：优先 MySQL 8.0 或 PostgreSQL 15，除非有特殊需求。
+
+## 版本推荐
+
+- MySQL：**8.0**（长期支持，性能优于 5.7）
+- PostgreSQL：**15** 或 **16**
+- SQL Server：2019 Enterprise/Standard
+
+## 系列（Edition）
+
+| 系列 | 可用区 | 适用 | 说明 |
+|------|--------|------|------|
+| 基础版（Basic） | 单 AZ | 开发/测试 | 无主备，成本低，不建议生产用 |
+| 高可用版（HA） | 双 AZ | 生产 | 主备架构，自动切换，推荐 |
+| 三节点企业版（Cluster） | 三 AZ | 金融/关键系统 | 一主两备，RPO=0 |
+
+## 规格推荐
+
+| 场景 | 推荐规格 | 存储 |
+|------|----------|------|
+| 开发/测试 | rds.mysql.s1.small (1c2g) | 20 GB |
+| 小型应用 | mysql.n2.medium.1 (2c4g) | 100 GB |
+| 中型应用 | mysql.n4.large.1 (4c8g) | 200 GB |
+| 高并发/大数据 | mysql.n8.xlarge.1 (8c32g) | 500+ GB |
+
+## 存储类型
+
+- **ESSD PL1**：推荐，高 IO，适合大多数生产场景
+- **SSD**：性能略低，成本低，适合测试环境
+- **ESSD PL2/PL3**：极高 IO，适合高并发写入场景
+
+## 网络配置
+
+- 生产环境：只开放内网访问，禁止公网直连
+- 开发/测试：可临时开放公网，IP 白名单严格限制
+- 使用安全组或 IP 白名单控制访问来源
+
+## 备份策略
+
+- 自动备份：开启，保留 7 天以上
+- 备份时间：业务低峰期（如凌晨 2-4 点）
+- 跨地域备份：关键数据开启，防止地域级灾难
+
+## 账户类型与权限
+
+- `MasterUserType: Super`：超级账户，自动拥有所有数据库的全部权限，**不需要**创建 `ALIYUN::RDS::AccountPrivilege` 资源
+- `MasterUserType: Normal`：普通账户，需通过 `ALIYUN::RDS::AccountPrivilege` 单独授权数据库访问权限
+
+## 最佳实践
+
+- 连接池：应用层使用连接池（如 HikariCP、pgBouncer），避免连接数暴涨
+- 慢查询：开启慢查询日志，阈值 1 秒
+- 参数调优：生产环境根据业务调整 `innodb_buffer_pool_size` 等核心参数
+- 只读实例：读多写少场景添加只读实例分担压力
+
+## 库存相关属性（模板中须参数化为 Parameters）
+
+| 属性 | 说明 |
+|------|------|
+| ZoneId | 可用区 |
+| DBInstanceClass | 数据库实例规格 |
+| DBInstanceStorageType | 存储类型 |
+
+## 可用性查询
+
+### 查询可用 RDS 规格
+
+```
+aliyun_api(product="rds", action="DescribeAvailableClasses", params={
+    "Engine": "MySQL",
+    "EngineVersion": "8.0",
+    "DBInstanceStorageType": "cloud_essd",
+    "Category": "HighAvailability",
+    "CommodityCode": "bards"
+})
+```
+
+> Engine 可选 MySQL / PostgreSQL / SQLServer / MariaDB。Category 可选 Basic / HighAvailability / cluster。CommodityCode 按量付费用 bards，包年包月用 rds。
+
+### 筛选逻辑
+
+1. 从返回结果中，找出可用的实例规格和可用区
+2. 按「规格推荐」表优先匹配
+3. 推荐规格不可用时，选同系列中最接近 vCPU/内存配置的可用规格

iac_code/skills/bundled/iac_aliyun/references/cloud-products/redis.md

@@ -0,0 +1,100 @@
+# 阿里云 Redis 选型指南
+
+## 版本选择
+
+| 版本 | 说明 | 推荐 |
+|------|------|------|
+| Redis 7.0 | 最新，Function 支持，性能提升 | 新项目首选 |
+| Redis 6.0 | 多线程 IO，稳定 | 已有项目 |
+| Redis 5.0 | 成熟稳定 | 兼容性要求高 |
+
+## 产品系列
+
+### 社区版（开源兼容）
+
+| 架构 | 说明 | 适用场景 |
+|------|------|----------|
+| 标准版-单副本 | 单节点，无主备 | 开发/测试，低成本 |
+| 标准版-双副本 | 主备架构，自动故障切换 | 生产环境基础选项 |
+| 集群版 | 数据分片，水平扩展 | 大容量（> 64 GB）、高并发 |
+| 读写分离版 | 主节点写，多只读节点 | 读多写少，扩展读能力 |
+
+### 企业版
+
+- 持久内存型：内存 + 持久化，比标准版成本低 40%
+- 存储型：海量数据，冷热数据混合
+
+## 规格推荐
+
+| 场景 | 推荐规格 | 内存 |
+|------|----------|------|
+| 开发/测试 | redis.master.micro.default | 1 GB |
+| 小型应用（Session/缓存） | redis.master.small.default | 2 GB |
+| 中型应用 | redis.master.mid.default | 8 GB |
+| 高并发应用 | redis.master.large.default | 16 GB |
+| 大容量需求 | 集群版，按分片数扩展 | 32 GB+ |
+
+## 网络配置
+
+- 生产环境：仅开放内网访问，禁止公网直连
+- 安全 IP 白名单：限制为应用服务器网段
+- SSL/TLS：敏感数据场景开启传输加密
+
+## 持久化配置
+
+- RDB（快照）：定期全量快照，恢复快，数据可能有少量丢失
+- AOF（追加日志）：近实时持久化，数据更安全，性能略低
+- 推荐：生产环境开启 RDB + AOF 双持久化
+
+## 集群版选型
+
+适用条件（满足任一即考虑集群版）：
+- 单实例内存需求 > 64 GB
+- QPS 超过 10 万
+- Key 数量超过 1 亿
+
+集群版注意事项：
+- 不支持跨 Slot 的多 Key 操作（MSET、Pipeline 需同 Slot）
+- 不支持 SELECT 切换 DB（固定 DB 0）
+- Lua 脚本需确保所有 Key 在同一 Slot
+
+## 读写分离版
+
+- 适合读 QPS 远大于写 QPS 的场景（如新闻、商品详情）
+- 只读节点数量：1-5 个，按读流量动态调整
+- 主节点和只读节点数据同步有微秒级延迟，读业务需容忍
+
+## 最佳实践
+
+- Key 命名规范：`{业务}:{模块}:{ID}`，如 `user:session:12345`
+- 设置合理 TTL，避免 Key 无限增长（内存打满）
+- 大 Value（> 10 KB）拆分或存 OSS，Redis 存引用
+- 禁止生产环境执行 `KEYS *`、`FLUSHALL` 等危险命令
+- 监控内存使用率，超过 80% 及时扩容
+- 慢查询阈值设为 10 ms，定期分析优化
+
+## 库存相关属性（模板中须参数化为 Parameters）
+
+| 属性 | 说明 |
+|------|------|
+| ZoneId | 可用区 |
+| InstanceClass | 实例规格 |
+
+## 可用性查询
+
+### 查询可用 Redis 规格
+
+```
+aliyun_api(product="r-kvstore", action="DescribeAvailableResource", params={
+    "InstanceChargeType": "PostPaid",
+    "Engine": "Redis"
+})
+```
+
+> InstanceChargeType 也可传 "PrePaid"（包年包月）。
+
+### 筛选逻辑
+
+1. 从返回结果中，找出可用的实例规格和可用区
+2. 按「规格推荐」表优先匹配
+3. 推荐规格不可用时，选同内存量级中最接近的可用规格

iac_code/skills/bundled/iac_aliyun/references/cloud-products/slb.md

@@ -0,0 +1,60 @@
+# 阿里云负载均衡选型指南
+
+## 产品对比
+
+| 产品 | 层级 | 协议 | 适用场景 |
+|------|------|------|----------|
+| CLB（传统型） | L4/L7 | TCP/UDP/HTTP/HTTPS | 通用场景，成本低 |
+| ALB（应用型） | L7 | HTTP/HTTPS/QUIC | 高级路由、微服务网关 |
+| NLB（网络型） | L4 | TCP/UDP/TCPSSL | 超高性能、极低延迟 |
+
+### 选型决策树
+
+```
+需要 L7 路由（URL/Header/Cookie 转发）？
+├── 是 → ALB（应用型负载均衡）
+│         - 基于内容的路由
+│         - 重写/重定向
+│         - WAF 集成
+│         - WebSocket/HTTP2
+└── 否 → 需要超高性能（百万 QPS / 极低延迟）？
+          ├── 是 → NLB（网络型负载均衡）
+          │         - 保持客户端源 IP
+          │         - UDP 支持
+          └── 否 → CLB（传统型负载均衡）
+                    - 成本最低
+                    - 配置简单
+                    - TCP/HTTP 均支持
+```
+
+## CLB 配置要点
+
+涉及 3 个资源类型：
+- `ALIYUN::SLB::LoadBalancer`：创建实例，关键属性 `AddressType`（internet/intranet）、`LoadBalancerSpec`
+- `ALIYUN::SLB::Listener`：配置监听，关键属性 `Protocol`、`ListenerPort`、`BackendServerPort`、`HealthCheck`
+- `ALIYUN::SLB::BackendServerAttachment`：绑定后端服务器
+
+## ALB 配置要点
+
+涉及 3 个资源类型：
+- `ALIYUN::ALB::LoadBalancer`：创建实例，需配置 `ZoneMappings`（至少 2 个可用区）
+- `ALIYUN::ALB::ServerGroup`：配置服务器组和健康检查
+- `ALIYUN::ALB::Listener`：配置监听，通过 `DefaultActions` 的 `ForwardGroup` 关联 ServerGroup
+
+## HTTPS 配置建议
+
+- 证书上传到阿里云证书管理服务（SSL Certificates Service）
+- SLB/ALB 监听器配置 HTTPS，引用证书 ID
+- HTTP → HTTPS 重定向：ALB 支持配置监听器重定向规则
+
+## 健康检查最佳实践
+
+- 配置专用健康检查接口（如 `/health`），返回 200 即视为健康
+- 阈值设置：健康阈值 3 次，不健康阈值 3 次，间隔 5 秒
+- 避免用业务接口做健康检查（防止误判）
+
+## 会话保持
+
+- CLB：支持基于 Cookie 的会话保持
+- ALB：支持基于 Cookie 和源 IP 的会话保持
+- 无状态应用：不需要会话保持，水平扩展更灵活

iac_code/skills/bundled/iac_aliyun/references/cloud-products/vpc.md

@@ -0,0 +1,54 @@
+# 阿里云 VPC 网络规划指南
+
+## CIDR 规划原则
+
+- 避免与线下网络或其他 VPC 重叠
+- 预留足够地址空间（按 3-5 年规划）
+- 推荐网段：`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`
+
+### 推荐规划
+
+| 环境 | VPC CIDR | 说明 |
+|------|----------|------|
+| 生产 | 10.0.0.0/16 | 65,534 个地址 |
+| 预发布 | 10.1.0.0/16 | 独立隔离 |
+| 开发/测试 | 10.2.0.0/16 | |
+| 个人/小项目 | 192.168.0.0/24 | 254 个地址，够用即可 |
+
+## VSwitch 规划
+
+每个可用区建议创建独立 VSwitch，按用途分层：
+
+```
+VPC: 10.0.0.0/16
+├── 可用区 A
+│   ├── 公网层 VSwitch:  10.0.1.0/24  (SLB、NAT、跳板机)
+│   ├── 应用层 VSwitch:  10.0.2.0/24  (ECS、容器)
+│   └── 数据层 VSwitch:  10.0.3.0/24  (RDS、Redis、OSS VPC Endpoint)
+└── 可用区 B
+    ├── 公网层 VSwitch:  10.0.11.0/24
+    ├── 应用层 VSwitch:  10.0.12.0/24
+    └── 数据层 VSwitch:  10.0.13.0/24
+```
+
+## 安全组设计
+
+### 分层安全组策略
+
+生产环境推荐按层级划分安全组：公网层、应用层、数据层。通过 `SourceGroupId` 实现层间引用，仅允许上层流量流入下层：
+
+- **公网层 SG**：仅允许 80/443，`SourceCidrIp: 0.0.0.0/0`
+- **应用层 SG**：仅允许来自公网层 SG 的流量，`SourceGroupId: !Ref PublicSG`
+- **数据层 SG**：仅允许来自应用层 SG 的流量，`SourceGroupId: !Ref AppSG`
+
+## NAT 网关
+
+- 公网访问：ECS 无公网 IP 时，通过 NAT 网关（`ALIYUN::VPC::NatGateway`）SNAT 访问公网
+- 公网入站：通过 DNAT 规则映射端口到内网（不推荐，优先用 SLB）
+
+## 网络访问控制建议
+
+- **最小权限原则**：安全组只开放必要端口和来源
+- **禁止 0.0.0.0/0 用于管理端口**：SSH(22)、RDP(3389) 严格限制来源
+- **数据层不出公网**：RDS、Redis 等仅内网访问
+- **VPC 对等连接**：跨 VPC 访问使用 VPC Peering，不通过公网

iac_code/skills/bundled/iac_aliyun/references/ros-template.md

@@ -0,0 +1,155 @@
+# ROS 模板最佳实践
+
+## 常用资源
+
+- ALIYUN::ECS::VPC: 创建专有网络
+- ALIYUN::ECS::VSwitch: 创建交换机
+- ALIYUN::ECS::SecurityGroup: 创建安全组（同时支持安全组规则）
+- ALIYUN::ECS::InstanceGroup: 创建N个ECS实例（通过 `MaxAmount` 指定数量）
+
+## 在实例中执行命令
+
+**不要使用 UserData + WaitCondition**。根据场景选择：
+
+- **自定义命令** → `ALIYUN::ECS::RunCommand` + `CommandContent`
+- **公共命令** → `ALIYUN::ECS::Invocation` + `CommandName`
+
+```yaml
+# 自定义命令
+RunSetup:
+  Type: ALIYUN::ECS::RunCommand
+  Properties:
+    InstanceIds:
+      - !Ref WebServer
+    Type: RunShellScript
+    Sync: true
+    Timeout: 600
+    ContentEncoding: PlainText
+    CommandContent: |
+      #!/bin/bash
+      yum install -y nginx
+      systemctl enable nginx
+      systemctl start nginx
+
+# 公共命令
+InstallOpenClaw:
+  Type: ALIYUN::ECS::Invocation
+  Properties:
+    InstanceIds:
+      - !Ref WebServer
+    CommandName: ACS-ECS-InstallOpenClaw-for-linux.sh
+    Sync: true
+    Timeout: 600
+```
+
+### 嵌套栈
+
+```yaml
+Resources:
+  NetworkStack:
+    Type: ALIYUN::ROS::Stack
+    Properties:
+      TemplateBody:
+      Parameters:
+        CidrBlock: 192.168.0.0/16
+```
+
+## 条件部署
+
+通过 Conditions 实现环境差异化：
+
+```yaml
+Conditions:
+  IsProd: !Equals [!Ref Env, prod]
+Resources:
+  ProdBucket:
+    Type: ALIYUN::OSS::Bucket
+    Condition: IsProd
+    Properties:
+      BucketName: prod-bucket
+```
+
+## 资源引用
+
+- 通过 `!Ref` 和 `!GetAtt` 引用参数和资源属性，避免硬编码
+- 使用 `DependsOn` 声明隐式依赖无法表达的顺序关系
+
+## 常用函数
+
+基础函数（Ref、Fn::GetAtt、Fn::Join、Fn::If、Fn::Equals 等）LLM 已熟悉，以下是容易用错的复杂函数。其他函数参考 aliyun_doc_search(keywords="ROS 函数", category_id=28850)。
+
+### Fn::Sub
+
+字符串变量替换。`${VarName}` 支持引用参数、伪参数（如 `${ALIYUN::StackId}`）、资源属性（如 `${Resource.Attr}`）。用 `${!VarName}` 保留字面量不替换。
+
+```yaml
+# 简写
+!Sub "string-${VarName}"
+
+# 带自定义变量映射
+Fn::Sub:
+  - "string-${Var1}-${Var2}"
+  - Var1: value1
+    Var2: value2
+```
+
+### Fn::Select
+
+从列表按索引/切片，或从字典按 Key 选取。索引从 0 开始，支持负数。第三参数为默认值（可选）。
+
+```yaml
+# 按索引
+!Select [index, list, defaultValue]
+
+# 切片（start 默认 0，stop 默认 N，step 默认 1）
+!Select ["start:stop:step", list]
+
+# 按 Key
+!Select [key, map, defaultValue]
+```
+
+### Fn::Replace
+
+替换字符串中的子串，支持多个替换映射。
+
+```yaml
+Fn::Replace:
+  - oldStr1: newStr1
+    oldStr2: newStr2
+  - originalString
+```
+
+### Fn::Jq
+
+对 JSON 数据执行 jq 查询。
+
+```yaml
+Fn::Jq:
+  - First/All
+  - jqScript
+  - jsonObject
+```
+
+- **First**：返回 jq 查询的第一个匹配值（字符串）
+- **All**：返回 jq 查询的所有匹配值（列表）
+
+jqScript 支持 jq 完整语法，包括管道 `|`、过滤 `select()`、变换 `{key: .field}` 等。
+
+## Outputs
+
+所有输出变量必须定义 Label。应用访问链接使用 `Console.` 前缀，会在 ROS 控制台概览页的「使用信息」中展示：
+
+```yaml
+Outputs:
+  EcsPublicIp:
+    Description: ECS 公网 IP
+    Label: ECS Public IP
+    Value: !GetAtt MyEcs.PublicIp
+  Console.NginxUrl:
+    Description: Nginx 访问地址
+    Label: Nginx URL
+    Value:
+      !Sub
+        - http://${Ip}
+        - Ip: !Select [0, !GetAtt MyEcs.PublicIps]
+```

iac_code/skills/bundled/iac_aliyun/references/template-parameters.md

@@ -0,0 +1,206 @@
+# ROS 模板参数规范
+
+本规范适用于所有通过 ROS 部署的模板。Terraform 模板通过 tf2ros 转换后，同样在生成的 ROS 模板中添加 Parameters 和 Metadata。
+
+## 参数化要求
+
+库存相关的 Parameters 不设 Default 和 AllowedValues，部署前通过可用性查询确定。
+
+选填参数设置 `Default: null`，用户可跳过不填。
+
+敏感参数设置 NoEcho: true。
+
+## AssociationProperty
+
+所有 Parameters **必须**添加 AssociationProperty，让 ROS 控制台自动关联候选值。通过 AssociationPropertyMetadata 实现参数间联动过滤。
+
+### 高频参考表
+
+| 参数用途 | AssociationProperty | 关键 Metadata |
+|---------|-------------------|--------------|
+| 地域 | ALIYUN::ECS::RegionId | - |
+| ECS 可用区 | ALIYUN::ECS::ZoneId | RegionId |
+| ECS 实例规格 | ALIYUN::ECS::Instance::InstanceType | RegionId, ZoneId, InstanceChargeType |
+| ECS 镜像 | ALIYUN::ECS::Image::ImageId | RegionId, InstanceType |
+| 系统盘类型 | ALIYUN::ECS::Disk::SystemDiskCategory | RegionId, ZoneId, InstanceType |
+| 数据盘类型 | ALIYUN::ECS::Disk::DataDiskCategory | RegionId, ZoneId, InstanceType |
+| VPC | ALIYUN::ECS::VPC::VPCId | RegionId |
+| 交换机 | ALIYUN::VPC::VSwitch::VSwitchId | RegionId, ZoneId, VpcId |
+| 安全组 | ALIYUN::ECS::SecurityGroup::SecurityGroupId | RegionId, VpcId |
+| 密钥对 | ALIYUN::ECS::KeyPair::KeyPairName | RegionId |
+| 密码 | ALIYUN::ECS::Instance::Password | - |
+| RDS 引擎 | ALIYUN::RDS::Engine::EngineId | - |
+| RDS 引擎版本 | ALIYUN::RDS::Engine::EngineVersion | Engine |
+| RDS 实例规格 | ALIYUN::RDS::Instance::InstanceType | RegionId, ZoneId, Engine, EngineVersion, DBInstanceStorageType, Category |
+| Redis 实例规格 | ALIYUN::Redis::Instance::InstanceType | RegionId, ZoneId, InstanceChargeType |
+| SLB 实例规格 | ALIYUN::SLB::Instance::InstanceType | RegionId, ZoneId |
+| 付费类型 | ChargeType | - |
+
+> 不在此表中的 AssociationProperty，使用 aliyun_doc_search(keywords="AssociationProperty <产品名>", category_id=28850) 搜索 ROS 文档获取。
+
+## Label
+
+为每个 Parameter 添加 Label，提供中英文显示名：
+
+```yaml
+Label:
+  en: Zone ID
+  zh-cn: 可用区
+```
+
+## 参数分组
+
+使用 Metadata 的 ParameterGroups 将参数按逻辑分组，提升控制台体验：
+
+```yaml
+Metadata:
+  ALIYUN::ROS::Interface:
+    ParameterGroups:
+      - Parameters:
+          - VpcId
+          - ZoneId
+          - VSwitchId
+        Label:
+          default: 网络配置
+      - Parameters:
+          - InstanceType
+          - SystemDiskCategory
+        Label:
+          default: ECS 配置
+      - Parameters:
+          - DBInstanceClass
+          - DBInstanceStorageType
+        Label:
+          default: RDS 配置
+```
+
+所有 Parameters 都应归入某个分组，按资源类型或功能模块分类。
+
+## 完整示例
+
+```yaml
+ROSTemplateFormatVersion: '2015-09-01'
+Metadata:
+  ALIYUN::ROS::Interface:
+    ParameterGroups:
+      - Parameters:
+          - ZoneId
+          - VpcId
+          - VSwitchId
+        Label:
+          default: 网络配置
+      - Parameters:
+          - InstanceType
+          - SystemDiskCategory
+        Label:
+          default: ECS 配置
+Parameters:
+  ZoneId:
+    Type: String
+    Label:
+      en: Zone ID
+      zh-cn: 可用区
+    AssociationProperty: ALIYUN::ECS::ZoneId
+    AssociationPropertyMetadata:
+      RegionId: ${ALIYUN::Region}
+  VpcId:
+    Type: String
+    Label:
+      en: VPC
+      zh-cn: 专有网络
+    AssociationProperty: ALIYUN::ECS::VPC::VPCId
+    AssociationPropertyMetadata:
+      RegionId: ${ALIYUN::Region}
+  VSwitchId:
+    Type: String
+    Label:
+      en: VSwitch
+      zh-cn: 交换机
+    AssociationProperty: ALIYUN::VPC::VSwitch::VSwitchId
+    AssociationPropertyMetadata:
+      ZoneId: ${ZoneId}
+      VpcId: ${VpcId}
+  InstanceType:
+    Type: String
+    Label:
+      en: Instance Type
+      zh-cn: 实例规格
+    AssociationProperty: ALIYUN::ECS::Instance::InstanceType
+    AssociationPropertyMetadata:
+      ZoneId: ${ZoneId}
+      InstanceChargeType: PostPaid
+  SystemDiskCategory:
+    Type: String
+    Label:
+      en: System Disk Category
+      zh-cn: 系统盘类型
+    AssociationProperty: ALIYUN::ECS::Disk::SystemDiskCategory
+    AssociationPropertyMetadata:
+      ZoneId: ${ZoneId}
+      InstanceType: ${InstanceType}
+```
+
+Metadata 中用 `${ParamName}` 引用其他参数，`${ALIYUN::Region}` 引用栈所在地域。
+
+## Terraform 模板的参数规范
+
+Terraform 模板通过 ROS 部署时，参数元信息通过以下方式定义（不需要转换后再修改 ROS 模板）：
+
+### 变量级：description 中嵌入 JSON
+
+AssociationProperty、AssociationPropertyMetadata、Label 写在 variable 的 `description` 中：
+
+```hcl
+variable "zone_id" {
+  type = string
+  description = <<EOT
+  {
+    "AssociationProperty": "ALIYUN::ECS::ZoneId",
+    "Label": {
+      "en": "Zone ID",
+      "zh-cn": "可用区"
+    }
+  }
+  EOT
+}
+
+variable "instance_type" {
+  type = string
+  description = <<EOT
+  {
+    "AssociationProperty": "ALIYUN::ECS::Instance::InstanceType",
+    "AssociationPropertyMetadata": {
+      "ZoneId": "$${zone_id}",
+      "InstanceChargeType": "$${instance_charge_type}"
+    },
+    "Label": {
+      "en": "Instance Type",
+      "zh-cn": "实例规格"
+    }
+  }
+  EOT
+}
+```
+
+> description 必须是合法 JSON。Metadata 中用 `$${var_name}` 引用其他变量（双 `$$` 避免 Terraform 插值）。
+
+### 模板级：.metadata 文件
+
+在 Terraform 目录下创建 `.metadata` 文件（JSON 格式），结构与 ROS Metadata 完全一致，用于定义 ParameterGroups 等。该文件会被 tf2ros.py 自动收入 Workspace 中（这是 ROS Terraform 模板的标准做法）：
+
+```json
+{
+  "ALIYUN::ROS::Interface": {
+    "ParameterGroups": [
+      {
+        "Parameters": ["zone_id", "vpc_id", "vswitch_id"],
+        "Label": {"default": "网络配置"}
+      },
+      {
+        "Parameters": ["instance_type", "system_disk_category"],
+        "Label": {"default": "ECS 配置"}
+      }
+    ]
+  }
+}
+```