Resource ID Overrides

Test code often references specific AWS resource IDs - a VPC ID in a config file, a KMS key ARN in a secret, an instance ID in a monitoring dashboard. Simfra lets you create resources with exact IDs using simfra: tags.

Prerequisites

How It Works

Tags with the simfra: prefix are extracted as ID overrides during resource creation. The override tag is applied, and then stripped - it never appears in DescribeTags, ListTags, or any API response. The resource is stored with your chosen ID and only the non-override tags.

resource "aws_kms_key" "app" {
  description = "Application key"

  tags = {
    "simfra:KeyId" = "12345678-1234-1234-1234-123456789012"
    Environment    = "test"
  }
}

The key is created with ID 12345678-1234-1234-1234-123456789012. Only the Environment tag is stored. The simfra:KeyId tag is consumed and discarded.

Tag Reference

Tag Resource Format Example
simfra:KeyId KMS Key UUID 12345678-1234-1234-1234-123456789012
simfra:VpcId VPC vpc- + 8-32 hex chars vpc-0abc123def456789ab
simfra:DefaultSecurityGroupId Default SG (created with VPC) sg- + hex sg-0abc123def456789ab
simfra:MainRouteTableId Main route table (created with VPC) rtb- + hex rtb-0abc123def456789ab
simfra:DefaultNetworkAclId Default NACL (created with VPC) acl- + hex acl-0abc123def456789ab
simfra:SubnetId Subnet subnet- + hex subnet-0abc123def456789ab
simfra:InstanceId EC2 Instance i- + hex (comma-separated for multiple) i-0abc123def456789ab
simfra:GroupId Security Group sg- + hex sg-0abc123def456789ab
simfra:InternetGatewayId Internet Gateway igw- + hex igw-0abc123def456789ab

Format Rules

  • Override values are validated for correct format. A simfra:VpcId value of bad-id is rejected.
  • Duplicate IDs are rejected. If a VPC with ID vpc-0abc123 already exists, creating another with the same override fails.
  • When no simfra: tags are present, resources get auto-generated IDs as usual.

Terraform Examples

Pinning a KMS Key

resource "aws_kms_key" "encryption" {
  description             = "Data encryption key"
  deletion_window_in_days = 7

  tags = {
    "simfra:KeyId" = "abcd1234-ab12-cd34-ef56-abcdef123456"
  }
}

resource "aws_kms_alias" "encryption" {
  name          = "alias/data-encryption"
  target_key_id = aws_kms_key.encryption.id
}

# The key ARN is now deterministic:
# arn:aws:kms:us-east-1:000000000000:key/abcd1234-ab12-cd34-ef56-abcdef123456

Pinning a VPC and All Associated Resources

When you create a VPC, Simfra automatically creates a default security group, main route table, and default network ACL - just like AWS. You can pin all four IDs at once:

resource "aws_vpc" "main" {
  cidr_block           = "10.0.0.0/16"
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = {
    Name                            = "main-vpc"
    "simfra:VpcId"                  = "vpc-0aaaa00000000000a"
    "simfra:DefaultSecurityGroupId" = "sg-0bbbb00000000000b"
    "simfra:MainRouteTableId"       = "rtb-0cccc00000000000c"
    "simfra:DefaultNetworkAclId"    = "acl-0dddd00000000000d"
  }
}

After apply, the VPC ID is vpc-0aaaa00000000000a, and its implicitly created resources use the specified IDs.

Pinning Subnets

resource "aws_subnet" "private_a" {
  vpc_id            = aws_vpc.main.id
  cidr_block        = "10.0.1.0/24"
  availability_zone = "us-east-1a"

  tags = {
    Name              = "private-a"
    "simfra:SubnetId" = "subnet-0eeee00000000000e"
  }
}

resource "aws_subnet" "private_b" {
  vpc_id            = aws_vpc.main.id
  cidr_block        = "10.0.2.0/24"
  availability_zone = "us-east-1b"

  tags = {
    Name              = "private-b"
    "simfra:SubnetId" = "subnet-0fffff0000000000f"
  }
}

Pinning EC2 Instances

For a single instance:

resource "aws_instance" "web" {
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.micro"
  subnet_id     = aws_subnet.private_a.id

  tags = {
    Name                = "web-server"
    "simfra:InstanceId" = "i-0aabb00000000000a"
  }
}

For multiple instances in one RunInstances call (using count or an ASG), pass comma-separated IDs:

resource "aws_instance" "workers" {
  count         = 3
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.micro"

  tags = {
    Name                = "worker-${count.index}"
    "simfra:InstanceId" = "i-0worker0000000001,i-0worker0000000002,i-0worker0000000003"
  }
}

Note: with Terraform count, each instance is a separate RunInstances call, so each gets the full comma-separated list but only uses the first unused ID. If your code uses an auto scaling group or launch template with a min count greater than 1, the comma-separated form applies.

Pinning a Security Group

resource "aws_security_group" "app" {
  name        = "app-sg"
  description = "Application security group"
  vpc_id      = aws_vpc.main.id

  tags = {
    "simfra:GroupId" = "sg-0aabb00000000000a"
  }
}

Pinning an Internet Gateway

resource "aws_internet_gateway" "main" {
  vpc_id = aws_vpc.main.id

  tags = {
    "simfra:InternetGatewayId" = "igw-0aabb00000000000a"
  }
}

Common Pattern: Full Network Stack

A complete example that pins every resource in a network stack:

resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"

  tags = {
    "simfra:VpcId"                  = "vpc-0aaaa00000000000a"
    "simfra:DefaultSecurityGroupId" = "sg-0bbbb00000000000b"
    "simfra:MainRouteTableId"       = "rtb-0cccc00000000000c"
    "simfra:DefaultNetworkAclId"    = "acl-0dddd00000000000d"
  }
}

resource "aws_internet_gateway" "main" {
  vpc_id = aws_vpc.main.id

  tags = {
    "simfra:InternetGatewayId" = "igw-0eeee00000000000e"
  }
}

resource "aws_subnet" "public" {
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.0.1.0/24"

  tags = {
    "simfra:SubnetId" = "subnet-0fffff0000000000f"
  }
}

resource "aws_security_group" "web" {
  name   = "web-sg"
  vpc_id = aws_vpc.main.id

  tags = {
    "simfra:GroupId" = "sg-01111000000000001"
  }
}

After terraform apply, every resource ID in the Terraform state matches the pinned values. Any downstream code that references these IDs works without modification.

AWS CLI Examples

Override tags also work with the AWS CLI:

# KMS key with specific ID
aws kms create-key \
  --tags TagKey=simfra:KeyId,TagValue=12345678-1234-1234-1234-123456789012

# VPC with specific ID and associated resource IDs
aws ec2 create-vpc --cidr-block 10.0.0.0/16 \
  --tag-specifications 'ResourceType=vpc,Tags=[{Key=simfra:VpcId,Value=vpc-0abc123def456789ab},{Key=simfra:DefaultSecurityGroupId,Value=sg-0abc123def456789ab},{Key=simfra:MainRouteTableId,Value=rtb-0abc123def456789ab}]'

Next Steps