Terraform for AI Agents (3): A Reusable VPC and Security Baseline

This article builds the single most copied piece of Terraform in my agent projects: a vpc-baseline module that gives every later component (ECS, RDS, OpenSearch, ACK) a sane place to land.

By the end you’ll have:

A VPC across three availability zones in one region
Six subnets (one public + one private per zone) with non-overlapping CIDRs
A NAT gateway with EIP for private-subnet outbound to LLM APIs
Three security groups stacked by tier (ALB → agent runtime → memory)
Three KMS customer master keys, one per data domain (memory, secrets, logs)
A clean module interface: name + CIDR + zones in, IDs out

It’s about 200 lines of HCL all-in. Worth typing once, refer to it forever.

The mental model

Before code, the picture:

VPC topology — 3 zones, public + private, NAT egress

Why three zones? Because Aliyun reserves the right to do a zone-level maintenance on any given Sunday, and a single-zone deployment means your agents are offline for the whole window. Cross-zone traffic inside a VPC is free; the only cost of three zones is the operational complexity of subnet math.

Why public + private? The agent runtime should live in private subnets so a misconfigured security group can’t accidentally expose it on 0.0.0.0/0. Public subnets hold the ALB (load balancer) and the NAT gateway — things that must reach the internet. The agent reaches the internet via NAT, not directly.

The CIDR layout I use:

Subnet	Zone	CIDR	Hosts
`public-a`	l	`10.20.0.0/28`	11
`public-b`	m	`10.20.0.16/28`	11
`public-c`	n	`10.20.0.32/28`	11
`private-a`	l	`10.20.1.0/24`	251
`private-b`	m	`10.20.2.0/24`	251
`private-c`	n	`10.20.3.0/24`	251

Public subnets are /28 because they only hold a NAT and an ALB IP. Private subnets are /24 because that’s where the agent ECS, RDS, OpenSearch nodes live.

The module skeleton

Create the directory layout:

modules/vpc-baseline/
├── main.tf
├── variables.tf
├── outputs.tf
└── versions.tf

Inputs (variables.tf):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
variable "name" {
  description = "Name prefix for all resources, e.g. agents-prod"
  type        = string
}

variable "cidr_block" {
  description = "Top-level VPC CIDR; subnets are derived from this"
  type        = string
  default     = "10.20.0.0/16"
}

variable "zones" {
  description = "Three availability zone IDs in the target region"
  type        = list(string)
  validation {
    condition     = length(var.zones) == 3
    error_message = "vpc-baseline requires exactly 3 zones."
  }
}

variable "tags" {
  description = "Tags applied to every resource the module creates"
  type        = map(string)
  default     = {}
}

Forcing exactly three zones is opinionated but matches the diagram. If you need two-zone or four-zone, fork the module — don’t make it conditional. Conditional modules become unreadable.

The VPC and subnets

main.tf, part one:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
resource "alicloud_vpc" "this" {
  vpc_name   = var.name
  cidr_block = var.cidr_block
  tags       = var.tags
}

resource "alicloud_vswitch" "public" {
  for_each = { for i, z in var.zones : i => z }

  vpc_id     = alicloud_vpc.this.id
  zone_id    = each.value
  cidr_block = cidrsubnet(var.cidr_block, 12, each.key)        # /28 starting at .0
  vswitch_name = "${var.name}-public-${substr(each.value, -1, 1)}"
  tags       = var.tags
}

resource "alicloud_vswitch" "private" {
  for_each = { for i, z in var.zones : i => z }

  vpc_id     = alicloud_vpc.this.id
  zone_id    = each.value
  cidr_block = cidrsubnet(var.cidr_block, 8, each.key + 1)     # /24 starting at .1.0
  vswitch_name = "${var.name}-private-${substr(each.value, -1, 1)}"
  tags       = var.tags
}

Three things worth noting:

cidrsubnet(prefix, newbits, netnum) is Terraform’s CIDR math. cidrsubnet("10.20.0.0/16", 8, 1) returns "10.20.1.0/24". Memorise this — you’ll use it constantly.
for_each with the index/value map gives stable resource addresses — alicloud_vswitch.private["0"] always points to the first zone, even if you rearrange the list. Compare to count, where reordering causes wholesale recreation.
substr(each.value, -1, 1) extracts the last char of the zone ID (the l/m/n) so resource names sort nicely.

NAT gateway and EIP

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
resource "alicloud_nat_gateway" "this" {
  vpc_id           = alicloud_vpc.this.id
  vswitch_id       = alicloud_vswitch.public["0"].id
  nat_gateway_name = "${var.name}-nat"
  nat_type         = "Enhanced"
  payment_type     = "PayAsYouGo"
  tags             = var.tags
}

resource "alicloud_eip_address" "nat" {
  address_name         = "${var.name}-nat-eip"
  bandwidth            = "100"
  internet_charge_type = "PayByTraffic"
  isp                  = "BGP"
  tags                 = var.tags
}

resource "alicloud_eip_association" "nat" {
  allocation_id = alicloud_eip_address.nat.id
  instance_id   = alicloud_nat_gateway.this.id
}

resource "alicloud_snat_entry" "private" {
  for_each = alicloud_vswitch.private

  snat_table_id     = alicloud_nat_gateway.this.snat_table_ids
  source_vswitch_id = each.value.id
  snat_ip           = alicloud_eip_address.nat.ip_address
}

The Enhanced NAT type is the modern one — required for Tablestore, PrivateLink, and most newer services. PayByTraffic is right for agent workloads where outbound bandwidth is bursty (LLM streaming) rather than steady.

The SNAT entries are what actually let private-subnet instances reach the internet. Without them, an agent in private-a cannot resolve dashscope.aliyuncs.com.

Security groups, layered

The right way to do security groups on Aliyun is one SG per tier, with rules that reference SG IDs not CIDRs:

Security group strategy — tight ingress, loose egress, layered

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
resource "alicloud_security_group" "alb_public" {
  name   = "${var.name}-alb-public"
  vpc_id = alicloud_vpc.this.id
  tags   = var.tags
}

resource "alicloud_security_group_rule" "alb_https_in" {
  security_group_id = alicloud_security_group.alb_public.id
  type              = "ingress"
  ip_protocol       = "tcp"
  port_range        = "443/443"
  cidr_ip           = "0.0.0.0/0"
  policy            = "accept"
  priority          = 1
}

resource "alicloud_security_group" "agent_runtime" {
  name   = "${var.name}-agent-runtime"
  vpc_id = alicloud_vpc.this.id
  tags   = var.tags
}

resource "alicloud_security_group_rule" "agent_from_alb" {
  security_group_id        = alicloud_security_group.agent_runtime.id
  type                     = "ingress"
  ip_protocol              = "tcp"
  port_range               = "8080/8080"
  source_security_group_id = alicloud_security_group.alb_public.id
  policy                   = "accept"
  priority                 = 1
}

The key line is source_security_group_id = alicloud_security_group.alb_public.id. This says “accept inbound 8080 only from any instance in the ALB SG” — not from a CIDR. Re-IPing the ALB later doesn’t break anything.

Real-world tip: Aliyun’s default behaviour is to deny all ingress and allow all egress. The default is correct — don’t add a “deny all egress” rule, you’ll just break SDK calls. Limit egress only when you have a specific compliance requirement; for an agent system, all-egress-open is normal.

I extend this pattern for every downstream tier:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
resource "alicloud_security_group" "memory_rds" {
  name   = "${var.name}-memory-rds"
  vpc_id = alicloud_vpc.this.id
  tags   = var.tags
}

resource "alicloud_security_group_rule" "rds_from_agent" {
  security_group_id        = alicloud_security_group.memory_rds.id
  type                     = "ingress"
  ip_protocol              = "tcp"
  port_range               = "5432/5432"
  source_security_group_id = alicloud_security_group.agent_runtime.id
  policy                   = "accept"
  priority                 = 1
}

resource "alicloud_security_group" "vector_store" {
  name   = "${var.name}-vector-store"
  vpc_id = alicloud_vpc.this.id
  tags   = var.tags
}

resource "alicloud_security_group_rule" "vector_from_agent" {
  security_group_id        = alicloud_security_group.vector_store.id
  type                     = "ingress"
  ip_protocol              = "tcp"
  port_range               = "9200/9200"
  source_security_group_id = alicloud_security_group.agent_runtime.id
  policy                   = "accept"
  priority                 = 1
}

By the time you’re done, attaching an ECS to the right SG is just security_groups = [module.vpc.agent_runtime_sg_id] and the network tier is correct by construction.

KMS keys per data domain

Encryption-at-rest is mandatory for any compliance regime worth its salt. The Aliyun way is one Customer Master Key (CMK) per data domain, so you can rotate one without touching another and audit access per-key.

KMS encryption — one CMK per data domain

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
locals {
  cmks = {
    memory  = "Encryption for RDS data and OSS objects"
    secrets = "Encryption for KMS Secrets Manager entries"
    logs    = "Encryption for SLS log data"
  }
}

resource "alicloud_kms_key" "this" {
  for_each = local.cmks

  description            = each.value
  key_usage              = "ENCRYPT/DECRYPT"
  key_spec               = "Aliyun_AES_256"
  pending_window_in_days = 7
  status                 = "Enabled"
  automatic_rotation     = "Enabled"
  rotation_interval      = "365d"
  protection_level       = "SOFTWARE"
  tags                   = merge(var.tags, { Domain = each.key })
}

resource "alicloud_kms_alias" "this" {
  for_each = local.cmks

  alias_name = "alias/${var.name}-${each.key}"
  key_id     = alicloud_kms_key.this[each.key].id
}

Why the alias? Because the CMK ID is a UUID nobody remembers; the alias alias/agents-prod-memory is human-readable and stable across key rotations. Reference the alias from RDS, OSS, etc. and you can swap the underlying key without touching downstream config.

pending_window_in_days = 7 means a deleted key has a 7-day window where you can recover it. Don’t shorten this — accidental key deletion is the kind of mistake that ends careers.

The module outputs

outputs.tf:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
output "vpc_id" {
  value = alicloud_vpc.this.id
}

output "private_vswitch_ids" {
  value = [for s in alicloud_vswitch.private : s.id]
}

output "public_vswitch_ids" {
  value = [for s in alicloud_vswitch.public : s.id]
}

output "nat_gateway_id" {
  value = alicloud_nat_gateway.this.id
}

output "nat_eip_address" {
  value = alicloud_eip_address.nat.ip_address
}

output "alb_public_sg_id" {
  value = alicloud_security_group.alb_public.id
}

output "agent_runtime_sg_id" {
  value = alicloud_security_group.agent_runtime.id
}

output "memory_rds_sg_id" {
  value = alicloud_security_group.memory_rds.id
}

output "vector_store_sg_id" {
  value = alicloud_security_group.vector_store.id
}

output "kms_keys" {
  value = { for k, v in alicloud_kms_key.this : k => v.id }
}

output "kms_aliases" {
  value = { for k, v in alicloud_kms_alias.this : k => v.alias_name }
}

These are exactly the IDs the next five articles need from us. By naming and shaping outputs deliberately, callers can do:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
module "vpc" {
  source = "./modules/vpc-baseline"
  name   = "agents-prod"
  zones  = ["cn-shanghai-l", "cn-shanghai-m", "cn-shanghai-n"]
}

resource "alicloud_instance" "agent" {
  vswitch_id      = module.vpc.private_vswitch_ids[0]
  security_groups = [module.vpc.agent_runtime_sg_id]
  # ...
}

Calling the module

In your top-level main.tf:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
module "vpc" {
  source = "./modules/vpc-baseline"

  name       = "agents-${terraform.workspace}"
  cidr_block = "10.20.0.0/16"
  zones      = ["cn-shanghai-l", "cn-shanghai-m", "cn-shanghai-n"]

  tags = {
    Project     = "research-agent-stack"
    Environment = terraform.workspace
    ManagedBy   = "terraform"
  }
}

terraform plan from the project root will produce something like:

Plan: 27 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + agent_runtime_sg_id = (known after apply)
  + nat_eip_address     = (known after apply)
  + private_vswitch_ids = [
      + (known after apply),
      + (known after apply),
      + (known after apply),
    ]
  + vpc_id              = (known after apply)

27 resources is about right (1 VPC + 6 vSwitch + 1 NAT + 1 EIP + 1 EIP-assoc + 3 SNAT + 4 SG + 4 SG-rule + 3 KMS key + 3 KMS alias = 27). Apply, and you have a production-grade network in about 90 seconds.

What it costs

Roughly, in cn-shanghai, monthly:

VPC, vSwitch, security groups, KMS keys: free
NAT gateway: ~¥120/mo for the Enhanced type, plus per-GB egress
EIP: ~¥20/mo for IP reservation, plus PayByTraffic data
KMS: free for the first 100 calls/day per key, then ~¥0.005/call

Call it ¥150-300/month for the network baseline at low-to-moderate traffic. Cheap for what you get — every later article inherits this skeleton.

What’s next

Article 4 lands compute on this network. Three patterns — ECS with pm2, ACK for production fleets, Function Compute for event-driven agents — and the cost-crossover model I use to pick between them. Then a real alicloud_instance block that bootstraps Python + Node + the agent runtime via cloud-init.

Real-world tip: If you ever need to add a fourth zone (Aliyun adds them periodically), it is a terraform apply away — the for_each pattern handles a longer list cleanly. But: the validation block in variables.tf will reject it, so you’ll first relax the validation. That deliberate friction is the point — adding a zone is a network change worth thinking about.