Volcengine IaC Skill

Generate, plan, and apply Volcengine infrastructure with Terraform when the user chooses IaC. volcengine-deploy still owns application packaging, runtime rollout, health checks, and CLI resource-ledger deployment.

When writing new examples, prefer the Cloud Control provider volcengine/volcenginecc. Clean no-op verified volcenginecc examples now cover network, VPC extras, VPC traffic mirror filters and CLB targets, private NAT, ECS, ECS placement/template extras, EBS snapshots, VKE, CR, TOS including bucket notification to veFaaS, TLS including scheduled SQL and TOS import tasks, CloudMonitor disabled alert rules, Redis, IAM, IAM users/groups, CLB instance/certificate/ACL, ALB full private entry traffic plus health check template/certificate/ACL/customized config, APIG private gateway/service, VPN IPsec gateway/connection/route plus SSL server, CEN with VPC attachment, DirectConnect gateway, TransitRouter, PrivateLink CLB endpoint service and endpoint, veFaaS, RDS MySQL, RDS PostgreSQL, Kafka allowlist, FileNAS, EFS, DNS, and PrivateZone under assets/examples/; volcenginecc-ebs-snapshot-group, volcenginecc-autoscaling, and volcenginecc-rdsmssql are lifecycle-verified only and have documented provider drift/destroy caveats. See the matching references/volcenginecc-*.md file for validation results and pitfalls. Blocked resources are tracked in references/volcenginecc-blocked.md. Existing reusable modules under assets/modules/ still use the legacy volcengine/volcengine provider until each component is re-verified with volcenginecc.

Use this skill when one of these is true:

• the user asks for Terraform or IaC,
• the user already has Terraform state/workspace,
• plan/diff/drift detection matters,
• the infrastructure is intended for long-term team-managed operation and the user chooses IaC,
• the deployment needs VKE, managed databases/cache/storage, load balancers, domains/certificates, IAM/KMS, logging, monitoring, or Serverless triggers and the user chooses IaC.

Do not use this skill just because a deployment is long-lived, VKE-based, or has managed dependencies. Recommend IaC where appropriate, but let the user choose. Do not use this skill when the user asks for CLI, a temporary demo/quick validation, a pure ECS single-VM service with no plan/diff/destroy requirement, or when Terraform/provider installation is blocked and the target can safely use the CLI fallback.

The skill ships forty-six clean no-op verified volcenginecc examples (volcenginecc-network, volcenginecc-vpc-extras, volcenginecc-vpc-traffic-mirror-filter, volcenginecc-vpc-traffic-mirror-target, volcenginecc-private-nat, volcenginecc-ecs, volcenginecc-ecs-extras, volcenginecc-ecs-launch-template-version, volcenginecc-ebs-snapshot, volcenginecc-vke, volcenginecc-cr, volcenginecc-tos, volcenginecc-tos-notification, volcenginecc-tls, volcenginecc-tls-schedule-sql, volcenginecc-tls-import-task, volcenginecc-cloudmonitor, volcenginecc-redis, volcenginecc-redis-public-address, volcenginecc-iam, volcenginecc-iam-users, volcenginecc-iam-oidc-provider, volcenginecc-iam-saml-provider, volcenginecc-clb, volcenginecc-clb-certificate, volcenginecc-clb-acl, volcenginecc-alb, volcenginecc-alb-health-check, volcenginecc-alb-certificate, volcenginecc-alb-acl, volcenginecc-alb-customized-cfg, volcenginecc-apig, volcenginecc-vpn, volcenginecc-vpn-ssl, volcenginecc-cen, volcenginecc-directconnect, volcenginecc-transitrouter, volcenginecc-privatelink, volcenginecc-vefaas, volcenginecc-rdsmysql, volcenginecc-rdspostgresql, volcenginecc-kafka-allow-list, volcenginecc-filenas, volcenginecc-efs, volcenginecc-dns, volcenginecc-privatezone), three lifecycle-verified examples (volcenginecc-ebs-snapshot-group, volcenginecc-autoscaling, volcenginecc-rdsmssql), six legacy reusable modules (network, vke, cr, rds-mysql, redis, tos), and four wrapper scripts (gen_tfvars.py, plan_summary.sh, export_outputs.sh, check_drift.sh).

Resources outside the six legacy modules (CLB/ALB, VKE, CR, databases, caches, object storage) should be added as verified volcenginecc examples first, then wrapped only after repeated use proves the interface is stable.

0. Prerequisites

Required env vars: VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, VOLCENGINE_REGION.

Required tools: terraform >= 1.5, jq, git, python3 (for gen_tfvars.py).

Optional: .volcengine/deploy-choice.json from volcengine-prepare/volcengine-deploy. If absent, ask a short batch of Terraform-specific questions.

The skill writes Terraform working files into .volcengine/terraform/ by default. State can use a TOS S3-compatible backend when the user wants remote state; see references/backend-tos.md. Local state is acceptable for small one-off experiments when the user accepts the tradeoff.

If invoked by volcengine-deploy, return outputs in .volcengine/iac-outputs.json and let deploy continue with image build/push, Cloud Assistant commands, Kubernetes manifests, veFaaS release, migrations, and health checks.

1. Generation Flow

Path A — driven by .volcengine/deploy-choice.json

skill_dir="$(dirname "$0")"
work_dir="${work_dir:-.volcengine/terraform}"
workload="${workload:-standard}"
mkdir -p "$work_dir"

python3 "$skill_dir/scripts/gen_tfvars.py" \
  --input ".volcengine/deploy-choice.json" \
  --output "$work_dir/terraform.tfvars" \
  --workload "$workload"

gen_tfvars.py derives:

• project, region, AZ pair from the choice file and environment
• enable_vke / enable_cr / enable_rds / enable_redis / enable_tos flags from the chosen mode and known dependencies
• Sizing (instance type, node count, RDS spec, Redis capacity) from a coarse --workload tier

The user can override any value before applying.

Path B — natural language input

When no prepare report exists, ask the user one batch of questions, then create a Terraform working directory from verified examples or legacy modules and generate matching variable values. Required answers:

1. Project name (resource prefix)
2. Region (e.g. cn-beijing)
3. Need VKE? (yes/no)
4. Stateful deps needed: MySQL? PostgreSQL? Redis? TOS bucket?
5. Workload tier: light / standard / heavy

Files written

gen_tfvars.py writes only terraform.tfvars. The Terraform configuration files come from copied verified examples under assets/examples/ or from a small root module assembled from assets/modules/; edit those files to match the selected stack instead of expecting the script to generate them.

The full per-module variable schema lives in references/modules.md. For new volcenginecc work, start from a verified example under assets/examples/ instead of these legacy modules unless the user explicitly needs the old provider.

Path C — volcenginecc verified examples

Copy the relevant verified example, then run the same init/validate/plan sequence:

cp -R "$skill_dir/assets/examples/\x3Cexample-name>" "$work_dir/\x3Ccomponent>"
cd "$work_dir/\x3Ccomponent>"
terraform init -backend=false -input=false
terraform validate
terraform plan -out=tfplan.binary -input=false

Before apply, show the plan summary and require explicit user confirmation. Read the matching reference before changing inputs or destroying resources; the references contain field choices, validation notes, import IDs, and provider pitfalls.

2. Deployment stack mapping

Use these opinionated stacks to choose verified examples. Start with examples; wrap into reusable modules only after repeated use proves the interface stable.

The stack mapping is a selection guide, not a promise that a prebuilt module exists. Copy the relevant verified examples into .volcengine/terraform/\x3Ccomponent> and keep component boundaries clear so plan/destroy output remains readable.

For the end-to-end VKE private CR nginx path, use assets/examples/volcengine-vke-cr-nginx/ and read references/volcengine-vke-cr-nginx.md first. That example exists for the CR credential addon, core-dns, CR token expiry, and image architecture pitfalls found in a real run.

3. Catalog

Verified volcenginecc examples

Legacy volcengine modules

Why ECS / CLB are not modules yet: ECS workloads vary too widely (build host vs runtime vs jumphost) for a single helpful interface, so ECS is a verified example rather than a module. EIP and NAT are covered in the verified volcenginecc-network example. CLB/ALB should be added as verified examples before they become reusable modules.

4. Init & Backend

cd "$work_dir"

# Map Volcengine creds to the Terraform s3 backend's required env variable names.
export AWS_ACCESS_KEY_ID="$VOLCENGINE_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$VOLCENGINE_SECRET_KEY"
export AWS_EC2_METADATA_DISABLED=true

terraform init -input=false
tf_workspace="${tf_workspace:-default}"
terraform workspace select "$tf_workspace" || \
  terraform workspace new "$tf_workspace"

When remote state is requested, generate backend.tf from references/backend-tos.md. The verified TOS backend shape requires skip_requesting_account_id = true and must not set force_path_style or use_path_style.

Provider download (~30–60 seconds first time) goes through registry.terraform.io. In China networks this may be blocked or slow. If public registry access fails and the user still wants IaC, configure Terraform provider_installation with a filesystem or internal mirror. Otherwise return to volcengine-deploy and ask whether to use the CLI resource-ledger path.

For the TOS bucket prerequisite (must exist before init), see references/backend-tos.md. Without a TOS bucket, omit backend.tf and Terraform falls back to local state.

5. Plan

terraform plan -out=tfplan.binary -input=false
terraform show -json tfplan.binary > tfplan.json
bash "$skill_dir/scripts/plan_summary.sh" tfplan.json

plan_summary.sh groups changes by action (CREATE / UPDATE / DELETE / REPLACE) and prints a one-line summary at the end. Show this to the user before any apply.

Watch for:

• DELETEs you didn't ask for — usually a sign of drift or a mistakenly removed module call
• REPLACEs on stateful resources — RDS / Redis replace = data loss; abort and inspect the diff with terraform show tfplan.binary

6. Apply

Always require explicit user confirmation. Do not pass -auto-approve. The pattern:

The plan above will create N resources, change M, destroy K. Approve apply? [yes/no]

After yes:

terraform apply tfplan.binary

VKE cluster creation takes ~10–15 minutes. RDS HA instances take ~20 minutes. Surface the long-running message to the user once at apply start so they don't think it hung.

After apply succeeds, run export_outputs.sh automatically:

bash "$skill_dir/scripts/export_outputs.sh"
echo "Resources ready. .volcengine/iac-outputs.json now contains downstream consumption keys."

7. Outputs for Downstream

export_outputs.sh writes terraform output -json to .volcengine/iac-outputs.json (mode 0600). The schema downstream skills (volcengine-deploy) consume:

{
  "vpc_id":            { "value": "vpc-xxxx" },
  "subnet_ids":        { "value": ["subnet-aaa", "subnet-bbb"] },
  "security_group_id": { "value": "sg-xxxx" },
  "cluster_id":        { "value": "cluster-xxxx" },
  "kubeconfig_private":{ "value": "\x3Cbase64>", "sensitive": true },
  "registry_endpoint": { "value": "cr-xxx.cr.volces.com" },
  "repository_uri":    { "value": "cr-xxx.cr.volces.com/myapp/myapp" },
  "cr_username":       { "value": "..." },
  "mysql_endpoint":    { "value": "\x3Caddr>:\x3Cport>" },
  "redis_instance_id": { "value": "redis-xxxx" },
  "tos_bucket":        { "value": "myapp-bucket" }
}

Some keys are conditional on which modules were enabled. Consumers must jq defensively (use // empty defaults).

8. Destroy

# Show what will be destroyed first
terraform plan -destroy -out=destroy.binary
terraform show -json destroy.binary | bash "$skill_dir/scripts/plan_summary.sh"

Then:

This will permanently delete N resources including RDS / Redis / TOS bucket data. Confirm? [yes/no]

On yes:

terraform destroy
# Note: provider does not accept -auto-approve=false; we rely on the agent-level prompt above.

Hard rule: never destroy in prod workspace without a second confirmation. The agent should explicitly re-prompt:

Workspace = prod. Re-confirm destroy by typing 'destroy prod':

9. Drift Detection

bash "$skill_dir/scripts/check_drift.sh"

Returns:

• 0 and {"drift": false, ...} — no drift
• 2 and {"drift": true, "changed_resources": N, ...} — N resources changed outside Terraform
• 1 and {"drift": "error", ...} — refresh-only plan errored

Use this:

• After known manual interventions (someone resized a node pool via console)
• Periodically as a CI job (weekly)
• Before any non-trivial apply to confirm baseline matches state

10. Import Existing Resources

If the user has resources created via volcengine-cli (or console) and wants to adopt them under Terraform, use terraform import. The import ID format differs per resource. Common cases:

# VPC
terraform import 'module.network.volcengine_vpc.main' vpc-xxxxxxxx

# Subnet
terraform import 'module.network.volcengine_subnet.primary' subnet-xxxxxxxx

# VKE cluster
terraform import 'module.vke.volcengine_vke_cluster.main' cluster-xxxxxxxx

# CR registry — replace cr-basic with the actual registry name
terraform import 'module.cr.volcengine_cr_registry.main' cr-basic

# CR namespace (compound ID: registry:namespace)
terraform import 'module.cr.volcengine_cr_namespace.main' cr-basic:my-namespace

# CR repository (compound ID: registry:namespace:repo)
terraform import 'module.cr.volcengine_cr_repository.main' cr-basic:my-namespace:my-repo

# RDS MySQL
terraform import 'module.rds_mysql.volcengine_rds_mysql_instance.main' mysql-xxxxxxxx

# Redis
terraform import 'module.redis.volcengine_redis_instance.main' redis-xxxxxxxx

# TOS bucket — replace my-bucket with the actual globally-unique name
terraform import 'module.tos.volcengine_tos_bucket.main' my-bucket

After import, run terraform plan to surface any divergence between your .tf config and the imported reality, and reconcile by editing the config (not the state).

11. Safety Rules

The skill's scripts enforce most of these mechanically (export_outputs.sh chmods 0600). Apply and destroy gates are the agent's responsibility.

12. Troubleshooting