Import an Existing VPC in AWS CDK with fromLookup

To import an existing VPC into AWS CDK, call ec2.Vpc.fromLookup() with its vpcId and set the stack's AWS account and region. CDK looks up the network during synthesis and caches its details; it does not create a second VPC or take ownership of the existing one.

Import a VPC by ID: minimal TypeScript example

In a CDK v2 TypeScript project, replace lib/import-vpc-stack.ts with:

COPY
import { CfnOutput, Stack, StackProps } from "aws-cdk-lib";
import * as ec2 from "aws-cdk-lib/aws-ec2";
import { Construct } from "constructs";

export class ImportVpcStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const vpc = ec2.Vpc.fromLookup(this, "ExistingVpc", {
      vpcId: "vpc-091234567ee1234567",
    });

    new CfnOutput(this, "VpcId", { value: vpc.vpcId });
  }
}

Replace the example VPC ID with yours. The app configuration below supplies the account and region. This minimal stack only references a network and exports its ID; the later examples are alternatives to its lookup expression.

The minimal stack was type-checked with TypeScript 5.9.3, aws-cdk-lib 2.272.0, and constructs 10.5.0. This revision has not been deployed to an AWS account; synthesis with real VPC lookups requires your credentials and network configuration. See the official Vpc API reference for the lookup contract.

Prerequisites

• AWS CDK Installed: Ensure you have the AWS CDK installed. If not, follow the installation guide.
• Existing VPC: An existing VPC in your AWS account that you intend to import.
• Configured AWS Credentials: Ensure your AWS credentials are properly configured.

Overview

Importing an existing VPC into AWS CDK involves using the fromLookup static method provided by the Vpc construct. This method allows CDK to reference a VPC that already exists in your AWS environment. It's essential to explicitly specify the stack environment (account and region) to enable CDK to locate the VPC accurately.

Defining the Stack Environment

Start by explicitly setting the stack's environment with the AWS account and region. This step ensures that CDK performs the lookup in the correct context.

COPY
// bin/app.ts
import * as cdk from "aws-cdk-lib";
import { ImportVpcStack } from "../lib/import-vpc-stack";

const app = new cdk.App();

new ImportVpcStack(app, "import-vpc-stack", {
  env: {
    region: "us-east-1", // specify your AWS region
    account: "123456789012", // replace with your AWS account ID
  },
});

Importing an Existing VPC by Name

To look up by name instead, replace the fromLookup call in the minimal stack with the following. Use a name that identifies exactly one VPC in the selected account and region.

COPY
const vpc = ec2.Vpc.fromLookup(this, "ExistingVpc", {
  vpcName: "YOUR_VPC_NAME",
});

Additional Lookup Options

The fromLookup method provides several options to identify the VPC:

• isDefault: Boolean value to match the default VPC.
• tags: Key-value pairs to filter the VPC based on tags.
• vpcId: Directly specify the VPC ID.

These options offer flexibility in selecting the appropriate VPC, especially in environments with multiple VPCs.

Viewing Synthesized CloudFormation

After defining your stack, you can inspect the synthesized CloudFormation template using:

COPY
npx aws-cdk synth

# Alternatively:
cdk synth

The CDK CLI resolves missing lookup context and reruns the app as needed. Inspect the resulting template and cdk.context.json; the minimal example should not declare a new AWS::EC2::VPC resource. Run npx aws-cdk diff before deploying changes to an existing stack.

Deploying the Stack

The minimal stack only publishes an output. Add application resources before deploying if you want to use the VPC for a workload. Check the diff so you understand which resources the stack will own.

COPY
npx aws-cdk deploy

# Alternatively:
cdk deploy

After deployment, check the VpcId stack output against the VPC you selected.

Refreshing Cached VPC Values

If the VPC's configuration changes, you need to refresh the cached values to reflect these updates in your CDK stack. Follow these steps to reset the cache:

1. Identify the Cache Key or Number:

   COPY
   npx aws-cdk context
   
   # Alternatively:
   cdk context

   This command lists all cached context values with their corresponding keys and numbers.

2. Reset the Cache:

   COPY
   npx aws-cdk context --reset KEY_OR_NUMBER
   
   # Alternatively:
   cdk context --reset KEY_OR_NUMBER

   Replace KEY_OR_NUMBER with the appropriate identifier from the previous step.

3. Synthesize Again:

   COPY
   npx aws-cdk synth
   
   # Alternatively:
   cdk synth

   CDK will perform a fresh lookup for the VPC, updating the cdk.context.json file with the latest values.

Importing the Default VPC

To import the default VPC, set the isDefault option to true in the fromLookup method. Since there is only one default VPC per account and region, this configuration is sufficient for CDK to identify it.

COPY
// lib/import-vpc-stack.ts
const defaultVpc = ec2.Vpc.fromLookup(this, "default-vpc-id", {
  isDefault: true,
});

Ensure that the stack environment is explicitly set to help CDK locate the default VPC accurately.

Importing an Existing VPC by Tags

Tag-based lookup allows you to import a VPC by specifying key-value pairs. This method is particularly useful when managing multiple VPCs with distinct tags.

1. Tag Your VPC: Add a tag to your VPC, for example:

   • Key: app
   • Value: web

2. Import the VPC Using Tags:

   COPY
   // lib/import-vpc-stack.ts
   const myVpc = ec2.Vpc.fromLookup(this, "by-tags-id", {
     tags: {
       app: "web",
     },
   });

This approach ensures that CDK imports the VPC matching the specified tag criteria.

Importing an Existing VPC by VPC ID

Directly specifying the VPC ID provides a precise method to import a VPC without ambiguity.

COPY
// lib/cdk-starter-stack.ts
const myVpc = ec2.Vpc.fromLookup(this, "external-vpc", {
  vpcId: "vpc-091234567ee1234567", // replace with your VPC ID
});

This method is straightforward and eliminates the need for additional lookup parameters.

Considerations for Importing Existing VPCs

When importing existing VPCs into your CDK stacks, consider the following limitations and best practices:

1. Explicit Environment Specification:

   • Requirement: Always set the stack's environment (account and region).
   • Reason: CDK needs to know where to perform the VPC lookup accurately.

2. Ownership of Existing Resources:

   • Limitation: Lookup does not transfer the VPC's existing resources into this stack.
   • Implication: Create new resources in the imported VPC as needed, and coordinate changes to existing networking with its owner.

3. Context Caching:

   • Behavior: After the initial lookup, VPC details are cached in cdk.context.json.
   • Action: If the VPC's configuration changes, reset the cache using the --reset flag to perform a fresh lookup.

4. Cache Reset Procedure:

   COPY
   npx aws-cdk context --reset CONTEXT_NUMBER_OR_KEY
   
   # Alternatively:
   cdk context --reset CONTEXT_NUMBER_OR_KEY

   Replace CONTEXT_NUMBER_OR_KEY with the appropriate identifier from the cdk.context.json file.

Troubleshooting VPC lookups

Commit cdk.context.json with your infrastructure source so other environments use the reviewed lookup values. AWS explains the caching and reset workflow in Context values and the AWS CDK.

Choose subnets and use the imported VPC

VPC lookup and subnet selection are separate decisions. Before placing a workload, follow subnet selection in AWS CDK and check its routing requirements. A Lambda function does not gain a public IP or internet access merely by being placed in a public subnet.

For a complete database and client example, continue with RDS PostgreSQL and EC2 using AWS CDK. That guide creates a new VPC; substitute this imported VPC only after verifying that its subnets and security boundaries meet the example's requirements.