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, a Route53 zone ID in a DNS module. Simfra lets you create resources with exact IDs. Resources go through the full creation path: validation, side effects, and state machine transitions all run normally.

Prerequisites

Choosing a Mechanism

Tag overrides work only when the Terraform AWS provider includes tags in the initial create request. Many resources support tags in the AWS API but the Terraform provider adds them in a separate call after creation - by which point the resource already has a random ID. Use the Simfra provider for those resources.

Mechanism Use when Examples
simfra: tags The Terraform AWS provider sends tags in the create request EC2 (VPCs, subnets, SGs, instances, TGWs), KMS keys, Organizations accounts and OUs
Simfra Terraform provider The Terraform AWS provider adds tags after creation, or the API has no tags Route53 hosted zones, Organizations (org + root ID)
X-Simfra-* headers You are not using Terraform (scripts, SDK code) Any resource, via boto3 or curl

Tag-Based Overrides

Add a tag with the simfra: prefix to the resource. The tag key suffix is the field name to override, and the tag value is the ID to use. Tags are preserved on the created resource, so Terraform detects no drift on subsequent applies.

This only works for resources where the Terraform AWS provider includes tags in the create API call (e.g. via TagSpecifications for EC2, or Tags for KMS and Organizations). For resources where Terraform creates first and tags separately (like Route53 zones), use the Simfra provider instead.

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_REGION=us-east-1
export AWS_S3_USE_PATH_STYLE=true

provider "aws" {
  region = "us-east-1"
}

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

  tags = {
    Name           = "main"
    "simfra:VpcId" = "vpc-0abc123def456789a"
  }
}

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

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

resource "aws_organizations_account" "dev" {
  name  = "dev-account"
  email = "dev@example.com"

  tags = {
    "simfra:AccountId" = "111111111111"
  }
}

Supported Tag Fields

EC2

Resource Tag field ID format Example
VPC simfra:VpcId vpc- + 8-32 hex vpc-0abc123def456789a
Subnet simfra:SubnetId subnet- + 8-32 hex subnet-0abc123def456789a
Security group simfra:GroupId sg- + 8-32 hex sg-0abc123def456789a
EC2 instance simfra:InstanceId i- + 8-32 hex i-0abc123def456789a
Internet gateway simfra:InternetGatewayId igw- + 8-32 hex igw-0abc123def456789a
NAT gateway simfra:NatGatewayId nat- + 8-32 hex nat-0abc123def456789a
Network interface simfra:NetworkInterfaceId eni- + 8-32 hex eni-0abc123def456789a
Elastic IP simfra:AllocationId eipalloc- + 8-32 hex eipalloc-0abc123def456789a
Transit gateway simfra:TransitGatewayId tgw- + 8-32 hex tgw-0abc123def456789a
TGW route table simfra:TransitGatewayRouteTableId tgw-rtb- + 8-32 hex tgw-rtb-0abc123def456789a
TGW default route table simfra:DefaultRouteTableId tgw-rtb- + 8-32 hex tgw-rtb-0abc123def456789a
TGW attachment simfra:TransitGatewayAttachmentId tgw-attach- + 8-32 hex tgw-attach-0abc123def456789a
TGW connect peer simfra:TransitGatewayConnectPeerId tgw-connect-peer- + 8-32 hex tgw-connect-peer-0abc123
TGW policy table simfra:TransitGatewayPolicyTableId tgw-ptb- + 8-32 hex tgw-ptb-0abc123def456789a
TGW multicast domain simfra:TransitGatewayMulticastDomainId tgw-mcast-domain- + 8-32 hex tgw-mcast-domain-0abc123
VPN gateway simfra:VpnGatewayId vgw- + 8-32 hex vgw-0abc123def456789a
VPN connection simfra:VpnConnectionId vpn- + 8-32 hex vpn-0abc123def456789a
Customer gateway simfra:CustomerGatewayId cgw- + 8-32 hex cgw-0abc123def456789a
VPC endpoint simfra:VpcEndpointId vpce- + 8-32 hex vpce-0abc123def456789a
VPC endpoint service simfra:ServiceId vpce-svc- + 8-32 hex vpce-svc-0abc123def456789a
Client VPN endpoint simfra:ClientVpnEndpointId cvpn-endpoint- + 8-32 hex cvpn-endpoint-0abc123
Launch template simfra:LaunchTemplateId lt- + 8-32 hex lt-0abc123def456789a
VPC default security group simfra:DefaultSecurityGroupId sg- + 8-32 hex sg-0abc123def456789a
VPC main route table simfra:MainRouteTableId rtb- + 8-32 hex rtb-0abc123def456789a
VPC default NACL simfra:DefaultNetworkAclId acl- + 8-32 hex acl-0abc123def456789a

KMS

Resource Tag field ID format Example
KMS key simfra:KeyId UUID 12345678-abcd-1234-abcd-123456789012

Organizations (tag-supported operations)

Resource Tag field ID format Example
Organizational unit simfra:OrganizationalUnitId ou-XXXX-YYYYYYYY ou-ab12-cdef1234
Member account simfra:AccountId 12 digits 111111111111

Simfra Terraform Provider

For resources where the Terraform AWS provider does not send tags in the create request, use the Simfra Terraform provider. It creates the resource via the AWS SDK and injects the ID override automatically. This covers resources like Route53 hosted zones (Terraform adds tags in a separate ChangeTagsForResource call after creation) and Organizations (the CreateOrganization API has no tags parameter at all).

provider "simfra" {
  endpoint   = "http://localhost:4599"
  access_key = "AKIAIOSFODNN7EXAMPLE"
  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  region     = "us-east-1"
}

resource "simfra_organization" "main" {
  id          = "o-abc1234567"
  root_id     = "r-ab12"
  feature_set = "ALL"
}

resource "simfra_route53_zone" "main" {
  id   = "Z0393724IIOWJEG34GXQ2"
  name = "example.com"
}

Supported Provider Resources

Resource Type ID fields
Organization simfra_organization id (org ID), root_id (root ID)
Route53 hosted zone simfra_route53_zone id (zone ID)

All ID fields are optional - if omitted, Simfra generates a random ID. The resources support full Terraform lifecycle (create, read, destroy, plan).

Header-Based Overrides (Fallback)

For scripts and SDK code outside Terraform, you can add X-Simfra-<FieldName> headers to any AWS API request. This is a lower-level mechanism - prefer tags or the Simfra provider when using Terraform.

boto3 (Python)

Inject headers using the botocore event system:

import boto3

def add_simfra_headers(headers):
    """Return a botocore event handler that injects X-Simfra-* headers."""
    def handler(request, **kwargs):
        for key, value in headers.items():
            request.headers[f"X-Simfra-{key}"] = value
    return handler

r53 = boto3.client("route53", endpoint_url="http://localhost:4599")
r53.meta.events.register("before-sign.route53.CreateHostedZone",
    add_simfra_headers({"Id": "Z0393724IIOWJEG34GXQ2"}))

zone = r53.create_hosted_zone(
    Name="example.com",
    CallerReference="ref-1",
)
print(zone["HostedZone"]["Id"])  # /hostedzone/Z0393724IIOWJEG34GXQ2

curl

curl -s -X POST http://localhost:4599/2013-04-01/hostedzone \
  -H "X-Simfra-Id: Z0393724IIOWJEG34GXQ2" \
  -H "Content-Type: text/xml" \
  --data-raw '<?xml version="1.0" encoding="UTF-8"?>
<CreateHostedZoneRequest xmlns="https://route53.amazonaws.com/doc/2013-04-01/">
  <Name>example.com</Name>
  <CallerReference>unique-ref-001</CallerReference>
</CreateHostedZoneRequest>'

Validation

Override values are validated before use. An invalid value causes the create request to fail with a 400 error.

ID type Validation
EC2 IDs (vpc-, subnet-, sg-, etc.) Correct prefix + 8-32 lowercase hex characters
KMS key ID Valid UUID format
Organization ID o- + exactly 10 lowercase alphanumeric
Root ID r- + exactly 4 lowercase alphanumeric
OU ID ou-XXXX-YYYYYYYY (4-char root suffix, 8-32 char OU suffix)
Account ID Exactly 12 digits
Hosted zone ID Z + 1-32 uppercase alphanumeric

Next Steps