Amazon EC2 Construct Library

The aws-cdk-lib/aws-ec2 package contains primitives for setting up networking and instances.

require 'aws-cdk-lib'

VPC

Most projects need a Virtual Private Cloud to provide security by means of network partitioning. This is achieved by creating an instance of Vpc:

vpc = AWSCDK::EC2::VPC.new(self, "VPC")

All default constructs require EC2 instances to be launched inside a VPC, so you should generally start by defining a VPC whenever you need to launch instances for your project.

Subnet Types

A VPC consists of one or more subnets that instances can be placed into. CDK distinguishes three different subnet types:

• Public (SubnetType.PUBLIC) - public subnets connect directly to the Internet using an Internet Gateway. If you want your instances to have a public IP address and be directly reachable from the Internet, you must place them in a public subnet.
• Private with Internet Access (SubnetType.PRIVATE_WITH_EGRESS) - instances in private subnets are not directly routable from the Internet, and you must provide a way to connect out to the Internet. By default, a NAT gateway is created in every public subnet for maximum availability. Be aware that you will be charged for NAT gateways. Alternatively you can set natGateways:0 and provide your own egress configuration (i.e through Transit Gateway)
• Isolated (SubnetType.PRIVATE_ISOLATED) - isolated subnets do not route from or to the Internet, and as such do not require NAT gateways. They can only connect to or be connected to from other instances in the same VPC. A default VPC configuration will not include isolated subnets,

A default VPC configuration will create public and private subnets. However, if natGateways:0 and subnet_configuration is undefined, default VPC configuration will create public and isolated subnets. See Advanced Subnet Configuration below for information on how to change the default subnet configuration.

Constructs using the VPC will "launch instances" (or more accurately, create Elastic Network Interfaces) into one or more of the subnets. They all accept a property called subnet_selection (sometimes called vpc_subnets) to allow you to select in what subnet to place the ENIs, usually defaulting to private subnets if the property is omitted.

If you would like to save on the cost of NAT gateways, you can use isolated subnets instead of private subnets (as described in Advanced Subnet Configuration). If you need private instances to have internet connectivity, another option is to reduce the number of NAT gateways created by setting the nat_gateways property to a lower value (the default is one NAT gateway per availability zone). Be aware that this may have availability implications for your application.

Read more about subnets.

Control over availability zones

By default, a VPC will spread over at most 3 Availability Zones available to it. To change the number of Availability Zones that the VPC will spread over, specify the max_azs property when defining it.

The number of Availability Zones that are available depends on the region and account of the Stack containing the VPC. If the region and account are specified on the Stack, the CLI will look up the existing Availability Zones and get an accurate count. The result of this operation will be written to a file called cdk.context.json. You must commit this file to source control so that the lookup values are available in non-privileged environments such as CI build steps, and to ensure your template builds are repeatable.

If region and account are not specified, the stack could be deployed anywhere and it will have to make a safe choice, limiting itself to 2 Availability Zones.

Therefore, to get the VPC to spread over 3 or more availability zones, you must specify the environment where the stack will be deployed.

You can gain full control over the availability zones selection strategy by overriding the Stack's get availabilityZones() method:

// This example is only available in TypeScript

class MyStack extends Stack {

  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // ...
  }

  get availabilityZones(): string[] {
    return ['us-west-2a', 'us-west-2b'];
  }

}

Note that overriding the get availabilityZones() method will override the default behavior for all constructs defined within the Stack.

Choosing subnets for resources

When creating resources that create Elastic Network Interfaces (such as databases or instances), there is an option to choose which subnets to place them in. For example, a VPC endpoint by default is placed into a subnet in every availability zone, but you can override which subnets to use. The property is typically called one of subnets, vpc_subnets or subnet_selection.

The example below will place the endpoint into two AZs (us-east-1a and us-east-1c), in Isolated subnets:

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::InterfaceVPCEndpoint.new(self, "VPC Endpoint", {
    vpc: vpc,
    service: AWSCDK::EC2::InterfaceVPCEndpointService.new("com.amazonaws.vpce.us-east-1.vpce-svc-uuddlrlrbastrtsvc", 443),
    subnets: {
        subnet_type: AWSCDK::EC2::SubnetType::PRIVATE_ISOLATED,
        availability_zones: ["us-east-1a", "us-east-1c"],
    },
})

You can also specify specific subnet objects for granular control:

vpc = nil # AWSCDK::EC2::VPC
subnet1 = nil # AWSCDK::EC2::Subnet
subnet2 = nil # AWSCDK::EC2::Subnet


AWSCDK::EC2::InterfaceVPCEndpoint.new(self, "VPC Endpoint", {
    vpc: vpc,
    service: AWSCDK::EC2::InterfaceVPCEndpointService.new("com.amazonaws.vpce.us-east-1.vpce-svc-uuddlrlrbastrtsvc", 443),
    subnets: {
        subnets: [subnet1, subnet2],
    },
})

Which subnets are selected is evaluated as follows:

• subnets: if specific subnet objects are supplied, these are selected, and no other logic is used.

• subnet_type/subnet_group_name: otherwise, a set of subnets is selected by supplying either type or name:

  • subnet_type will select all subnets of the given type.
  • subnet_group_name should be used to distinguish between multiple groups of subnets of the same type (for example, you may want to separate your application instances and your RDS instances into two distinct groups of Isolated subnets).
  • If neither are given, the first available subnet group of a given type that exists in the VPC will be used, in this order: Private, then Isolated, then Public. In short: by default ENIs will preferentially be placed in subnets not connected to the Internet.

• availability_zones/one_per_az: finally, some availability-zone based filtering may be done. This filtering by availability zones will only be possible if the VPC has been created or looked up in a non-environment agnostic stack (so account and region have been set and availability zones have been looked up).

  • availability_zones: only the specific subnets from the selected subnet groups that are in the given availability zones will be returned.
  • one_per_az: per availability zone, a maximum of one subnet will be returned (Useful for resource types that do not allow creating two ENIs in the same availability zone).

• subnet_filters: additional filtering on subnets using any number of user-provided filters which extend SubnetFilter. The following methods on the SubnetFilter class can be used to create a filter:

  • by_ids: chooses subnets from a list of ids
  • availability_zones: chooses subnets in the provided list of availability zones
  • one_per_az: chooses at most one subnet per availability zone
  • contains_ip_addresses: chooses a subnet which contains any of the listed ip addresses
  • by_cidr_mask: chooses subnets that have the provided CIDR netmask
  • by_cidr_ranges: chooses subnets which are inside any of the specified CIDR ranges

Using NAT instances

By default, the Vpc construct will create NAT gateways for you, which are managed by AWS. If you would prefer to use your own managed NAT instances instead, specify a different value for the nat_gateway_provider property, as follows:

The construct will automatically selects the latest version of Amazon Linux 2023. If you prefer to use a custom AMI, use machineImage: MachineImage.genericLinux({ ... }) and configure the right AMI ID for the regions you want to deploy to.

Warning The NAT instances created using this method will be unmonitored. They are not part of an Auto Scaling Group, and if they become unavailable or are terminated for any reason, will not be restarted or replaced.

By default, the NAT instances will route all traffic. To control what traffic gets routed, pass a custom value for default_allowed_traffic and access the NatInstanceProvider.connections member after having passed the NAT provider to the VPC:

instance_type = nil # AWSCDK::EC2::InstanceType


provider = AWSCDK::EC2::NatProvider.instance_v2({
    instance_type: instance_type,
    default_allowed_traffic: AWSCDK::EC2::NatTrafficDirection::OUTBOUND_ONLY,
})
AWSCDK::EC2::VPC.new(self, "TheVPC", {
    nat_gateway_provider: provider,
})
provider.connections.allow_from(AWSCDK::EC2::Peer.ipv4("1.2.3.4/8"), AWSCDK::EC2::Port.HTTP)

You can also customize the characteristics of your NAT instances, including their security group, as well as their initialization scripts:

bucket = nil # AWSCDK::S3::Bucket


user_data = AWSCDK::EC2::UserData.for_linux
user_data.add_commands(*AWSCDK::EC2::NatInstanceProviderV2.DEFAULT_USER_DATA_COMMANDS, "echo \"hello world!\" > hello.txt", "aws s3 cp hello.txt s3://#{bucket.bucket_name}")

provider = AWSCDK::EC2::NatProvider.instance_v2({
    instance_type: AWSCDK::EC2::InstanceType.new("t3.small"),
    credit_specification: AWSCDK::EC2::CpuCredits::UNLIMITED,
    default_allowed_traffic: AWSCDK::EC2::NatTrafficDirection::NONE,
})

vpc = AWSCDK::EC2::VPC.new(self, "TheVPC", {
    nat_gateway_provider: provider,
    nat_gateways: 2,
})

security_group = AWSCDK::EC2::SecurityGroup.new(self, "SecurityGroup", {vpc: vpc})
security_group.add_egress_rule(AWSCDK::EC2::Peer.any_ipv4, AWSCDK::EC2::Port.tcp(443))
provider.gateway_instances.each do |gateway|
  bucket.grants.write(gateway)
  gateway.add_security_group(security_group)
end

# Configure the `natGatewayProvider` when defining a Vpc
nat_gateway_provider = AWSCDK::EC2::NatProvider.instance({
    instance_type: AWSCDK::EC2::InstanceType.new("t3.small"),
})

vpc = AWSCDK::EC2::VPC.new(self, "MyVpc", {
    nat_gateway_provider: nat_gateway_provider,

    # The 'natGateways' parameter now controls the number of NAT instances
    nat_gateways: 2,
})

The V1 NatProvider.instance construct will use the AWS official NAT instance AMI, which has already reached EOL on Dec 31, 2023. For more information, see the following blog post: Amazon Linux AMI end of life.

instance_type = nil # AWSCDK::EC2::InstanceType


provider = AWSCDK::EC2::NatProvider.instance({
    instance_type: instance_type,
    default_allowed_traffic: AWSCDK::EC2::NatTrafficDirection::OUTBOUND_ONLY,
})
AWSCDK::EC2::VPC.new(self, "TheVPC", {
    nat_gateway_provider: provider,
})
provider.connections.allow_from(AWSCDK::EC2::Peer.ipv4("1.2.3.4/8"), AWSCDK::EC2::Port.HTTP)

Associate Public IP Address to NAT Instance

You can choose to associate public IP address to a NAT instance V2 by specifying associate_public_ip_address like the following:

nat_gateway_provider = AWSCDK::EC2::NatProvider.instance_v2({
    instance_type: AWSCDK::EC2::InstanceType.new("t3.small"),
    associate_public_ip_address: true,
})

In certain scenarios where the public subnet has set map_public_ip_on_launch to false, NAT instances does not get public IP addresses assigned which would result in non-working NAT instance as NAT instance requires a public IP address to enable outbound internet connectivity. Users can specify associate_public_ip_address to true to solve this problem.

Ip Address Management

The VPC spans a supernet IP range, which contains the non-overlapping IPs of its contained subnets. Possible sources for this IP range are:

• You specify an IP range directly by specifying a CIDR
• You allocate an IP range of a given size automatically from AWS IPAM

By default the Vpc will allocate the 10.0.0.0/16 address range which will be exhaustively spread across all subnets in the subnet configuration. This behavior can be changed by passing an object that implements IIpAddresses to the ip_address property of a Vpc. See the subsequent sections for the options.

Be aware that if you don't explicitly reserve subnet groups in subnet_configuration, the address space will be fully allocated! If you predict you may need to add more subnet groups later, add them early on and set reserved: true (see the "Advanced Subnet Configuration" section for more information).

Specifying a CIDR directly

Use IpAddresses.cidr to define a Cidr range for your Vpc directly in code:

require 'aws-cdk-lib'


AWSCDK::EC2::VPC.new(self, "TheVPC", {
    ip_addresses: AWSCDK::EC2::IPAddresses.cidr("10.0.1.0/20"),
})

Space will be allocated to subnets in the following order:

• First, spaces is allocated for all subnets groups that explicitly have a cidr_mask set as part of their configuration (including reserved subnets).
• Afterwards, any remaining space is divided evenly between the rest of the subnets (if any).

The argument to IpAddresses.cidr may not be a token, and concrete Cidr values are generated in the synthesized CloudFormation template.

Allocating an IP range from AWS IPAM

Amazon VPC IP Address Manager (IPAM) manages a large IP space, from which chunks can be allocated for use in the Vpc. For information on Amazon VPC IP Address Manager please see the official documentation. An example of allocating from AWS IPAM looks like this:

require 'aws-cdk-lib'

pool = nil # AWSCDK::EC2::CfnIPAMPool


AWSCDK::EC2::VPC.new(self, "TheVPC", {
    ip_addresses: AWSCDK::EC2::IPAddresses.aws_ipam_allocation({
        ipv4_ipam_pool_id: pool.ref,
        ipv4_netmask_length: 18,
        default_subnet_ipv4_netmask_length: 24,
    }),
})

IpAddresses.awsIpamAllocation requires the following:

• ipv4_ipam_pool_id, the id of an IPAM Pool from which the VPC range should be allocated.
• ipv4_netmask_length, the size of the IP range that will be requested from the Pool at deploy time.
• default_subnet_ipv4_netmask_length, the size of subnets in groups that don't have cidr_mask set.

With this method of IP address management, no attempt is made to guess at subnet group sizes or to exhaustively allocate the IP range. All subnet groups must have an explicit cidr_mask set as part of their subnet configuration, or default_subnet_ipv4_netmask_length must be set for a default size. If not, synthesis will fail and you must provide one or the other.

Dual Stack configuration

To allocate both IPv4 and IPv6 addresses in your VPC, you can configure your VPC to have a dual stack protocol.

AWSCDK::EC2::VPC.new(self, "DualStackVpc", {
    ip_protocol: AWSCDK::EC2::IPProtocol::DUAL_STACK,
})

By default, a dual stack VPC will create an Amazon provided IPv6 /56 CIDR block associated to the VPC. It will then assign /64 portions of the block to each subnet. For each subnet, auto-assigning an IPv6 address will be enabled, and auto-asigning a public IPv4 address will be disabled. An egress only internet gateway will be created for PRIVATE_WITH_EGRESS subnets, and IPv6 routes will be added for IGWs and EIGWs.

Disabling the auto-assigning of a public IPv4 address by default can avoid the cost of public IPv4 addresses starting 2/1/2024. For use cases that need an IPv4 address, the map_public_ip_on_launch property in subnet_configuration can be set to auto-assign the IPv4 address. Note that private IPv4 address allocation will not be changed.

See Advanced Subnet Configuration for all IPv6 specific properties.

Reserving availability zones

There are situations where the IP space for availability zones will need to be reserved. This is useful in situations where availability zones would need to be added after the vpc is originally deployed, without causing IP renumbering for availability zones subnets. The IP space for reserving n availability zones can be done by setting the reserved_azs to n in vpc props, as shown below:

vpc = AWSCDK::EC2::VPC.new(self, "TheVPC", {
    cidr: "10.0.0.0/21",
    max_azs: 3,
    reserved_azs: 1,
})

In the example above, the subnets for reserved availability zones is not actually provisioned but its IP space is still reserved. If, in the future, new availability zones needs to be provisioned, then we would decrement the value of reserved_azs and increment the max_azs or availability_zones accordingly. This action would not cause the IP address of subnets to get renumbered, but rather the IP space that was previously reserved will be used for the new availability zones subnets.

Advanced Subnet Configuration

If the default VPC configuration (public and private subnets spanning the size of the VPC) don't suffice for you, you can configure what subnets to create by specifying the subnet_configuration property. It allows you to configure the number and size of all subnets. Specifying an advanced subnet configuration could look like this:

vpc = AWSCDK::EC2::VPC.new(self, "TheVPC", {
    # 'IpAddresses' configures the IP range and size of the entire VPC.
    # The IP space will be divided based on configuration for the subnets.
    ip_addresses: AWSCDK::EC2::IPAddresses.cidr("10.0.0.0/21"),

    # 'maxAzs' configures the maximum number of availability zones to use.
    # If you want to specify the exact availability zones you want the VPC
    # to use, use `availabilityZones` instead.
    max_azs: 3,

    # 'subnetConfiguration' specifies the "subnet groups" to create.
    # Every subnet group will have a subnet for each AZ, so this
    # configuration will create `3 groups × 3 AZs = 9` subnets.
    subnet_configuration: [
        {
            # 'subnetType' controls Internet access, as described above.
            subnet_type: AWSCDK::EC2::SubnetType::PUBLIC,

            # 'name' is used to name this particular subnet group. You will have to
            # use the name for subnet selection if you have more than one subnet
            # group of the same type.
            name: "Ingress",

            # 'cidrMask' specifies the IP addresses in the range of individual
            # subnets in the group. Each of the subnets in this group will contain
            # `2^(32 address bits - 24 subnet bits) - 2 reserved addresses = 254`
            # usable IP addresses.
            # If 'cidrMask' is left out the available address space is evenly
            # divided across the remaining subnet groups.
            cidr_mask: 24,
        },
        {
            cidr_mask: 24,
            name: "Application",
            subnet_type: AWSCDK::EC2::SubnetType::PRIVATE_WITH_EGRESS,
        },
        {
            cidr_mask: 28,
            name: "Database",
            subnet_type: AWSCDK::EC2::SubnetType::PRIVATE_ISOLATED,

            # 'reserved' can be used to reserve IP address space. No resources will
            # be created for this subnet, but the IP range will be kept available for
            # future creation of this subnet, or even for future subdivision.
            reserved: true,
        },
    ],
})

The example above is one possible configuration, but the user can use the constructs above to implement many other network configurations.

The Vpc from the above configuration in a Region with three availability zones will be the following:

Dual Stack Configurations

Here is a break down of IPv4 and IPv6 specific subnet_configuration properties in a dual stack VPC:

vpc = AWSCDK::EC2::VPC.new(self, "TheVPC", {
    ip_protocol: AWSCDK::EC2::IPProtocol::DUAL_STACK,

    subnet_configuration: [
        {
            # general properties
            name: "Public",
            subnet_type: AWSCDK::EC2::SubnetType::PUBLIC,
            reserved: false,

            # IPv4 specific properties
            map_public_ip_on_launch: true,
            cidr_mask: 24,

            # new IPv6 specific property
            ipv6_assign_address_on_creation: true,
        },
    ],
})

The property map_public_ip_on_launch controls if a public IPv4 address will be assigned. This defaults to false for dual stack VPCs to avoid inadvertant costs of having the public address. However, a public IP must be enabled (or otherwise configured with BYOIP or IPAM) in order for services that rely on the address to function.

The ipv6_assign_address_on_creation property controls the same behavior for the IPv6 address. It defaults to true.

Using IPv6 specific properties in an IPv4 only VPC will result in errors.

Accessing the Internet Gateway

If you need access to the internet gateway, you can get its ID like so:

vpc = nil # AWSCDK::EC2::VPC


igw_id = vpc.internet_gateway_id

For a VPC with only ISOLATED subnets, this value will be undefined.

This is only supported for VPCs created in the stack - currently you're unable to get the ID for imported VPCs. To do that you'd have to specifically look up the Internet Gateway by name, which would require knowing the name beforehand.

This can be useful for configuring routing using a combination of gateways: for more information see Routing below.

Disabling the creation of the default internet gateway

If you need to control the creation of the internet gateway explicitly, you can disable the creation of the default one using the create_internet_gateway property:

vpc = AWSCDK::EC2::VPC.new(self, "VPC", {
    create_internet_gateway: false,
    subnet_configuration: [
        {
            subnet_type: AWSCDK::EC2::SubnetType::PUBLIC,
            name: "Public",
        },
    ],
})

Routing

It's possible to add routes to any subnets using the add_route() method. If for example you want an isolated subnet to have a static route via the default Internet Gateway created for the public subnet - perhaps for routing a VPN connection - you can do so like this:

vpc = AWSCDK::EC2::VPC.new(self, "VPC", {
    subnet_configuration: [
        {
            subnet_type: AWSCDK::EC2::SubnetType::PUBLIC,
            name: "Public",
        },
        {
            subnet_type: AWSCDK::EC2::SubnetType::PRIVATE_ISOLATED,
            name: "Isolated",
        },
    ],
})

(vpc.isolated_subnets[0]).add_route("StaticRoute", {
    router_id: vpc.internet_gateway_id,
    router_type: AWSCDK::EC2::RouterType::GATEWAY,
    destination_cidr_block: "8.8.8.8/32",
})

Note that we cast to Subnet here because the list of subnets only returns an ISubnet.

Reserving subnet IP space

There are situations where the IP space for a subnet or number of subnets will need to be reserved. This is useful in situations where subnets would need to be added after the vpc is originally deployed, without causing IP renumbering for existing subnets. The IP space for a subnet may be reserved by setting the reserved subnetConfiguration property to true, as shown below:

vpc = AWSCDK::EC2::VPC.new(self, "TheVPC", {
    nat_gateways: 1,
    subnet_configuration: [
        {
            cidr_mask: 26,
            name: "Public",
            subnet_type: AWSCDK::EC2::SubnetType::PUBLIC,
        },
        {
            cidr_mask: 26,
            name: "Application1",
            subnet_type: AWSCDK::EC2::SubnetType::PRIVATE_WITH_EGRESS,
        },
        {
            cidr_mask: 26,
            name: "Application2",
            subnet_type: AWSCDK::EC2::SubnetType::PRIVATE_WITH_EGRESS,
            reserved: true,
        },
        {
            cidr_mask: 27,
            name: "Database",
            subnet_type: AWSCDK::EC2::SubnetType::PRIVATE_ISOLATED,
        },
    ],
})

In the example above, the subnet for Application2 is not actually provisioned but its IP space is still reserved. If in the future this subnet needs to be provisioned, then the reserved: true property should be removed. Reserving parts of the IP space prevents the other subnets from getting renumbered.

Sharing VPCs between stacks

If you are creating multiple Stacks inside the same CDK application, you can reuse a VPC defined in one Stack in another by simply passing the VPC instance around:

#
# Stack1 creates the VPC
#
class Stack1 < AWSCDK::Stack
  attr_reader :vpc

  def initialize(scope, id, props = nil)
    super(scope, id, props)

    @vpc = AWSCDK::EC2::VPC.new(self, "VPC")
  end
end

#
# Stack2 consumes the VPC
#
class Stack2 < AWSCDK::Stack
  def initialize(scope, id, props)
    super(scope, id, props)

    # Pass the VPC to a construct that needs it
    ConstructThatTakesAVpc.new(self, "Construct", {
        vpc: props[:vpc],
    })
  end
end

stack1 = Stack1.new(app, "Stack1")
stack2 = Stack2.new(app, "Stack2", {
    vpc: stack1.vpc,
})

Note: If you encounter an error like "Delete canceled. Cannot delete export ..." when using a cross-stack reference to a VPC, it's likely due to CloudFormation export/import constraints. In such cases, it's safer to use Vpc.fromLookup() in the consuming stack instead of directly referencing the VPC object, more details is provided in Importing an existing VPC. This avoids creating CloudFormation exports and gives more flexibility, especially when stacks need to be deleted or updated independently.

Importing an existing VPC

If your VPC is created outside your CDK app, you can use Vpc.fromLookup(). The CDK CLI will search for the specified VPC in the stack's region and account, and import the subnet configuration. Looking up can be done by VPC ID, but more flexibly by searching for a specific tag on the VPC.

Subnet types will be determined from the aws-cdk:subnet-type tag on the subnet if it exists, or the presence of a route to an Internet Gateway otherwise. Subnet names will be determined from the aws-cdk:subnet-name tag on the subnet if it exists, or will mirror the subnet type otherwise (i.e. a public subnet will have the name "Public").

The result of the Vpc.fromLookup() operation will be written to a file called cdk.context.json. You must commit this file to source control so that the lookup values are available in non-privileged environments such as CI build steps, and to ensure your template builds are repeatable.

Here's how Vpc.fromLookup() can be used:

vpc = AWSCDK::EC2::VPC.from_lookup(stack, "VPC", {
    # This imports the default VPC but you can also
    # specify a 'vpcName' or 'tags'.
    is_default: true,
})

Vpc.fromLookup is the recommended way to import VPCs. If for whatever reason you do not want to use the context mechanism to look up a VPC at synthesis time, you can also use Vpc.fromVpcAttributes. This has the following limitations:

• Every subnet group in the VPC must have a subnet in each availability zone (for example, each AZ must have both a public and private subnet). Asymmetric VPCs are not supported.
• All VpcId, SubnetId, RouteTableId, ... parameters must either be known at synthesis time, or they must come from deploy-time list parameters whose deploy-time lengths are known at synthesis time.

Using Vpc.fromVpcAttributes() looks like this:

vpc = AWSCDK::EC2::VPC.from_vpc_attributes(self, "VPC", {
    vpc_id: "vpc-1234",
    availability_zones: ["us-east-1a", "us-east-1b"],

    # Either pass literals for all IDs
    public_subnet_ids: ["s-12345", "s-67890"],

    # OR: import a list of known length
    private_subnet_ids: AWSCDK::Fn.import_list_value("PrivateSubnetIds", 2),

    # OR: split an imported string to a list of known length
    isolated_subnet_ids: AWSCDK::Fn.split(",", AWSCDK::SSM::StringParameter.value_for_string_parameter(self, "MyParameter"), 2),
})

For each subnet group the import function accepts optional parameters for subnet names, route table ids and IPv4 CIDR blocks. When supplied, the length of these lists are required to match the length of the list of subnet ids, allowing the lists to be zipped together to form ISubnet instances.

Public subnet group example (for private or isolated subnet groups, use the properties with the respective prefix):

vpc = AWSCDK::EC2::VPC.from_vpc_attributes(self, "VPC", {
    vpc_id: "vpc-1234",
    availability_zones: ["us-east-1a", "us-east-1b", "us-east-1c"],
    public_subnet_ids: ["s-12345", "s-34567", "s-56789"],
    public_subnet_names: ["Subnet A", "Subnet B", "Subnet C"],
    public_subnet_route_table_ids: ["rt-12345", "rt-34567", "rt-56789"],
    public_subnet_ipv4_cidr_blocks: ["10.0.0.0/24", "10.0.1.0/24", "10.0.2.0/24"],
})

The above example will create an IVpc instance with three public subnets:

| Subnet id | Availability zone | Subnet name | Route table id | IPv4 CIDR | | --------- | ----------------- | ----------- | -------------- | ----------- | | s-12345 | us-east-1a | Subnet A | rt-12345 | 10.0.0.0/24 | | s-34567 | us-east-1b | Subnet B | rt-34567 | 10.0.1.0/24 | | s-56789 | us-east-1c | Subnet B | rt-56789 | 10.0.2.0/24 |

Restricting access to the VPC default security group

AWS Security best practices recommend that the VPC default security group should not allow inbound and outbound traffic. When the @aws-cdk/aws-ec2:restrictDefaultSecurityGroup feature flag is set to true (default for new projects) this will be enabled by default. If you do not have this feature flag set you can either set the feature flag or you can set the restrict_default_security_group property to true.

AWSCDK::EC2::VPC.new(self, "VPC", {
    restrict_default_security_group: true,
})

If you set this property to true and then later remove it or set it to false the default ingress/egress will be restored on the default security group.

Allowing Connections

In AWS, all network traffic in and out of Elastic Network Interfaces (ENIs) is controlled by Security Groups. You can think of Security Groups as a firewall with a set of rules. By default, Security Groups allow no incoming (ingress) traffic and all outgoing (egress) traffic. You can add ingress rules to them to allow incoming traffic streams. To exert fine-grained control over egress traffic, set allowAllOutbound: false on the SecurityGroup, after which you can add egress traffic rules.

You can manipulate Security Groups directly:

my_security_group = AWSCDK::EC2::SecurityGroup.new(self, "SecurityGroup", {
    vpc: vpc,
    description: "Allow ssh access to ec2 instances",
    allow_all_outbound: true,
})
my_security_group.add_ingress_rule(AWSCDK::EC2::Peer.any_ipv4, AWSCDK::EC2::Port.tcp(22), "allow ssh access from the world")

All constructs that create ENIs on your behalf (typically constructs that create EC2 instances or other VPC-connected resources) will all have security groups automatically assigned. Those constructs have an attribute called connections, which is an object that makes it convenient to update the security groups. If you want to allow connections between two constructs that have security groups, you have to add an Egress rule to one Security Group, and an Ingress rule to the other. The connections object will automatically take care of this for you:

load_balancer = nil # AWSCDK::ElasticLoadBalancingv2::ApplicationLoadBalancer
app_fleet = nil # AWSCDK::Autoscaling::AutoScalingGroup
db_fleet = nil # AWSCDK::Autoscaling::AutoScalingGroup


# Allow connections from anywhere
load_balancer.connections.allow_from_any_ipv4(AWSCDK::EC2::Port.HTTPS, "Allow inbound HTTPS")

# The same, but an explicit IP address
load_balancer.connections.allow_from(AWSCDK::EC2::Peer.ipv4("1.2.3.4/32"), AWSCDK::EC2::Port.HTTPS, "Allow inbound HTTPS")

# Allow connection between AutoScalingGroups
app_fleet.connections.allow_to(db_fleet, AWSCDK::EC2::Port.HTTPS, "App can call database")

Connection Peers

There are various classes that implement the connection peer part:

app_fleet = nil # AWSCDK::Autoscaling::AutoScalingGroup
db_fleet = nil # AWSCDK::Autoscaling::AutoScalingGroup


# Simple connection peers
peer = AWSCDK::EC2::Peer.ipv4("10.0.0.0/16")
peer = AWSCDK::EC2::Peer.any_ipv4
peer = AWSCDK::EC2::Peer.ipv6("::0/0")
peer = AWSCDK::EC2::Peer.any_ipv6
app_fleet.connections.allow_to(peer, AWSCDK::EC2::Port.HTTPS, "Allow outbound HTTPS")

Any object that has a security group can itself be used as a connection peer:

fleet1 = nil # AWSCDK::Autoscaling::AutoScalingGroup
fleet2 = nil # AWSCDK::Autoscaling::AutoScalingGroup
app_fleet = nil # AWSCDK::Autoscaling::AutoScalingGroup


# These automatically create appropriate ingress and egress rules in both security groups
fleet1.connections.allow_to(fleet2, AWSCDK::EC2::Port.HTTP, "Allow between fleets")

app_fleet.connections.allow_from_any_ipv4(AWSCDK::EC2::Port.HTTP, "Allow from load balancer")

A managed prefix list is also a connection peer:

app_fleet = nil # AWSCDK::Autoscaling::AutoScalingGroup


prefix_list = AWSCDK::EC2::PrefixList.new(self, "PrefixList", {max_entries: 10})
app_fleet.connections.allow_from(prefix_list, AWSCDK::EC2::Port.HTTPS)

Rule Configuration Interfaces

The IPeer interface provides type-safe methods for generating security group rule configurations. The to_ingress_rule_config() and to_egress_rule_config() methods return strongly-typed interfaces instead of any, enabling better IDE autocompletion and compile-time type checking:

• IngressRuleConfig: Configuration for ingress rules with properties like cidr_ip, cidr_ipv6, source_prefix_list_id, source_security_group_id, and source_security_group_owner_id
• EgressRuleConfig: Configuration for egress rules with properties like cidr_ip, cidr_ipv6, destination_prefix_list_id, and destination_security_group_id

Port Ranges

The connections that are allowed are specified by port ranges. A number of classes provide the connection specifier:

AWSCDK::EC2::Port.tcp(80)
AWSCDK::EC2::Port.HTTPS
AWSCDK::EC2::Port.tcp_range(60000, 65535)
AWSCDK::EC2::Port.all_tcp
AWSCDK::EC2::Port.all_icmp
AWSCDK::EC2::Port.all_icmp_v6
AWSCDK::EC2::Port.all_traffic

NOTE: Not all protocols have corresponding helper methods. In the absence of a helper method, you can instantiate Port yourself with your own settings. You are also welcome to contribute new helper methods.

Default Ports

Some Constructs have default ports associated with them. For example, the listener of a load balancer does (it's the public port), or instances of an RDS database (it's the port the database is accepting connections on).

If the object you're calling the peering method on has a default port associated with it, you can call allow_default_port_from() and omit the port specifier. If the argument has an associated default port, call allow_default_port_to().

For example:

listener = nil # AWSCDK::ElasticLoadBalancingv2::ApplicationListener
app_fleet = nil # AWSCDK::Autoscaling::AutoScalingGroup
rds_database = nil # AWSCDK::RDS::DatabaseCluster


# Port implicit in listener
listener.connections.allow_default_port_from_any_ipv4("Allow public")

# Port implicit in peer
app_fleet.connections.allow_default_port_to(rds_database, "Fleet can access database")

Security group rules

By default, security group wills be added inline to the security group in the output cloud formation template, if applicable. This includes any static rules by ip address and port range. This optimization helps to minimize the size of the template.

In some environments this is not desirable, for example if your security group access is controlled via tags. You can disable inline rules per security group or globally via the context key @aws-cdk/aws-ec2.securityGroupDisableInlineRules.

my_security_group_without_inline_rules = AWSCDK::EC2::SecurityGroup.new(self, "SecurityGroup", {
    vpc: vpc,
    description: "Allow ssh access to ec2 instances",
    allow_all_outbound: true,
    disable_inline_rules: true,
})
# This will add the rule as an external cloud formation construct
my_security_group_without_inline_rules.add_ingress_rule(AWSCDK::EC2::Peer.any_ipv4, AWSCDK::EC2::Port.SSH, "allow ssh access from the world")

Importing an existing security group

If you know the ID and the configuration of the security group to import, you can use SecurityGroup.fromSecurityGroupId:

sg = AWSCDK::EC2::SecurityGroup.from_security_group_id(self, "SecurityGroupImport", "sg-1234", {
    allow_all_outbound: true,
})

Alternatively, use lookup methods to import security groups if you do not know the ID or the configuration details. Method SecurityGroup.fromLookupByName looks up a security group if the security group ID is unknown.

sg = AWSCDK::EC2::SecurityGroup.from_lookup_by_name(self, "SecurityGroupLookup", "security-group-name", vpc)

If the security group ID is known and configuration details are unknown, use method SecurityGroup.fromLookupById instead. This method will lookup property allow_all_outbound from the current configuration of the security group.

sg = AWSCDK::EC2::SecurityGroup.from_lookup_by_id(self, "SecurityGroupLookup", "sg-1234")

The result of SecurityGroup.fromLookupByName and SecurityGroup.fromLookupById operations will be written to a file called cdk.context.json. You must commit this file to source control so that the lookup values are available in non-privileged environments such as CI build steps, and to ensure your template builds are repeatable.

Cross Stack Connections

If you are attempting to add a connection from a peer in one stack to a peer in a different stack, sometimes it is necessary to ensure that you are making the connection in a specific stack in order to avoid a cyclic reference. If there are no other dependencies between stacks then it will not matter in which stack you make the connection, but if there are existing dependencies (i.e. stack1 already depends on stack2), then it is important to make the connection in the dependent stack (i.e. stack1).

Whenever you make a connections function call, the ingress and egress security group rules will be added to the stack that the calling object exists in. So if you are doing something like peer1.connections.allowFrom(peer2), then the security group rules (both ingress and egress) will be created in peer1's Stack.

As an example, if we wanted to allow a connection from a security group in one stack (egress) to a security group in a different stack (ingress), we would make the connection like:

If Stack1 depends on Stack2

# Stack 1
stack1 = nil # AWSCDK::Stack
stack2 = nil # AWSCDK::Stack


sg1 = AWSCDK::EC2::SecurityGroup.new(stack1, "SG1", {
    allow_all_outbound: false,
    vpc: vpc,
})

# Stack 2
sg2 = AWSCDK::EC2::SecurityGroup.new(stack2, "SG2", {
    allow_all_outbound: false,
    vpc: vpc,
})

# `connections.allowTo` on `sg1` since we want the
# rules to be created in Stack1
sg1.connections.allow_to(sg2, AWSCDK::EC2::Port.tcp(3333))

In this case both the Ingress Rule for sg2 and the Egress Rule for sg1 will both be created in Stack 1 which avoids the cyclic reference.

If Stack2 depends on Stack1

# Stack 1
stack1 = nil # AWSCDK::Stack
stack2 = nil # AWSCDK::Stack


sg1 = AWSCDK::EC2::SecurityGroup.new(stack1, "SG1", {
    allow_all_outbound: false,
    vpc: vpc,
})

# Stack 2
sg2 = AWSCDK::EC2::SecurityGroup.new(stack2, "SG2", {
    allow_all_outbound: false,
    vpc: vpc,
})

# `connections.allowFrom` on `sg2` since we want the
# rules to be created in Stack2
sg2.connections.allow_from(sg1, AWSCDK::EC2::Port.tcp(3333))

In this case both the Ingress Rule for sg2 and the Egress Rule for sg1 will both be created in Stack 2 which avoids the cyclic reference.

Machine Images (AMIs)

AMIs control the OS that gets launched when you start your EC2 instance. The EC2 library contains constructs to select the AMI you want to use.

Depending on the type of AMI, you select it a different way. Here are some examples of images you might want to use:

# Pick the right Amazon Linux edition. All arguments shown are optional
# and will default to these values when omitted.
amzn_linux = AWSCDK::EC2::MachineImage.latest_amazon_linux({
    generation: AWSCDK::EC2::AmazonLinuxGeneration::AMAZON_LINUX,
    edition: AWSCDK::EC2::AmazonLinuxEdition::STANDARD,
    virtualization: AWSCDK::EC2::AmazonLinuxVirt::HVM,
    storage: AWSCDK::EC2::AmazonLinuxStorage::GENERAL_PURPOSE,
    cpu_type: AWSCDK::EC2::AmazonLinuxCpuType::X86_64,
})

# Pick a Windows edition to use
windows = AWSCDK::EC2::MachineImage.latest_windows(AWSCDK::EC2::WindowsVersion::WINDOWS_SERVER_2019_ENGLISH_FULL_BASE)

# Read AMI id from SSM parameter store
ssm = AWSCDK::EC2::MachineImage.from_ssm_parameter("/my/ami", {os: AWSCDK::EC2::OperatingSystemType::LINUX})

# Look up the most recent image matching a set of AMI filters.
# In this case, look up the NAT instance AMI, by using a wildcard
# in the 'name' field:
nat_ami = AWSCDK::EC2::MachineImage.lookup({
    name: "amzn-ami-vpc-nat-*",
    owners: ["amazon"],
})

# For other custom (Linux) images, instantiate a `GenericLinuxImage` with
# a map giving the AMI to in for each region:
linux = AWSCDK::EC2::MachineImage.generic_linux({
    "us-east-1" => "ami-97785bed",
    "eu-west-1" => "ami-12345678",
})

# For other custom (Windows) images, instantiate a `GenericWindowsImage` with
# a map giving the AMI to in for each region:
generic_windows = AWSCDK::EC2::MachineImage.generic_windows({
    "us-east-1" => "ami-97785bed",
    "eu-west-1" => "ami-12345678",
})

NOTE: The AMIs selected by MachineImage.lookup() will be cached in cdk.context.json, so that your AutoScalingGroup instances aren't replaced while you are making unrelated changes to your CDK app.

To query for the latest AMI again, remove the relevant cache entry from cdk.context.json, or use the cdk context command. For more information, see Runtime Context in the CDK developer guide.

To customize the cache key, use the additional_cache_key parameter. This allows you to have multiple lookups with the same parameters cache their values separately. This can be useful if you want to scope the context variable to a construct (ie, using additionalCacheKey: this.node.path), so that if the value in the cache needs to be updated, it does not need to be updated for all constructs at the same time.

MachineImage.genericLinux(), MachineImage.genericWindows() will use CfnMapping in an agnostic stack.

Special VPC configurations

VPN connections to a VPC

Create your VPC with VPN connections by specifying the vpn_connections props (keys are construct ids):

require 'aws-cdk-lib'


vpc = AWSCDK::EC2::VPC.new(self, "MyVpc", {
    vpn_connections: {
        dynamic: {
             # Dynamic routing (BGP)
            ip: "1.2.3.4",
            tunnel_options: [
                {
                    pre_shared_key_secret: AWSCDK::SecretValue.unsafe_plain_text("secretkey1234"),
                },
                {
                    pre_shared_key_secret: AWSCDK::SecretValue.unsafe_plain_text("secretkey5678"),
                },
            ],
        },
        static: {
             # Static routing
            ip: "4.5.6.7",
            static_routes: [
                "192.168.10.0/24",
                "192.168.20.0/24",
            ],
        },
    },
})

To create a VPC that can accept VPN connections, set vpn_gateway to true:

vpc = AWSCDK::EC2::VPC.new(self, "MyVpc", {
    vpn_gateway: true,
})

VPN connections can then be added:

vpc.add_vpn_connection("Dynamic", {
    ip: "1.2.3.4",
})

By default, routes will be propagated on the route tables associated with the private subnets. If no private subnets exist, isolated subnets are used. If no isolated subnets exist, public subnets are used. Use the Vpc property vpn_route_propagation to customize this behavior.

VPN connections expose metrics (cloudwatch.Metric) across all tunnels in the account/region and per connection:

# Across all tunnels in the account/region
all_data_out = AWSCDK::EC2::VpnConnection.metric_all_tunnel_data_out

# For a specific vpn connection
vpn_connection = vpc.add_vpn_connection("Dynamic", {
    ip: "1.2.3.4",
})
state = vpn_connection.metric_tunnel_state

VPC endpoints

A VPC endpoint enables you to privately connect your VPC to supported AWS services and VPC endpoint services powered by PrivateLink without requiring an internet gateway, NAT device, VPN connection, or AWS Direct Connect connection. Instances in your VPC do not require public IP addresses to communicate with resources in the service. Traffic between your VPC and the other service does not leave the Amazon network.

Endpoints are virtual devices. They are horizontally scaled, redundant, and highly available VPC components that allow communication between instances in your VPC and services without imposing availability risks or bandwidth constraints on your network traffic.

# Add gateway endpoints when creating the VPC
vpc = AWSCDK::EC2::VPC.new(self, "MyVpc", {
    gateway_endpoints: {
        S3: {
            service: AWSCDK::EC2::GatewayVPCEndpointAWSService.S3,
        },
    },
})

# Alternatively gateway endpoints can be added on the VPC
dynamo_db_endpoint = vpc.add_gateway_endpoint("DynamoDbEndpoint", {
    service: AWSCDK::EC2::GatewayVPCEndpointAWSService.DYNAMODB,
})

# This allows to customize the endpoint policy
dynamo_db_endpoint.add_to_policy(
AWSCDK::IAM::PolicyStatement.new({
     # Restrict to listing and describing tables
    principals: [AWSCDK::IAM::AnyPrincipal.new],
    actions: ["dynamodb:DescribeTable", "dynamodb:ListTables"],
    resources: ["*"],
}))

# Add an interface endpoint
vpc.add_interface_endpoint("EcrDockerEndpoint", {
    service: AWSCDK::EC2::InterfaceVPCEndpointAWSService.ECR_DOCKER,
})

By default, CDK will place a VPC endpoint in one subnet per AZ. If you wish to override the AZs CDK places the VPC endpoint in, use the subnets parameter as follows:

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::InterfaceVPCEndpoint.new(self, "VPC Endpoint", {
    vpc: vpc,
    service: AWSCDK::EC2::InterfaceVPCEndpointService.new("com.amazonaws.vpce.us-east-1.vpce-svc-uuddlrlrbastrtsvc", 443),
    # Choose which availability zones to place the VPC endpoint in, based on
    # available AZs
    subnets: {
        availability_zones: ["us-east-1a", "us-east-1c"],
    },
})

Per the AWS documentation, not all VPC endpoint services are available in all AZs. If you specify the parameter lookup_supported_azs, CDK attempts to discover which AZs an endpoint service is available in, and will ensure the VPC endpoint is not placed in a subnet that doesn't match those AZs. These AZs will be stored in cdk.context.json.

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::InterfaceVPCEndpoint.new(self, "VPC Endpoint", {
    vpc: vpc,
    service: AWSCDK::EC2::InterfaceVPCEndpointService.new("com.amazonaws.vpce.us-east-1.vpce-svc-uuddlrlrbastrtsvc", 443),
    # Choose which availability zones to place the VPC endpoint in, based on
    # available AZs
    lookup_supported_azs: true,
})

Pre-defined AWS services are defined in the InterfaceVpcEndpointAwsService class, and can be used to create VPC endpoints without having to configure name, ports, etc. For example, a Keyspaces endpoint can be created for use in your VPC:

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::InterfaceVPCEndpoint.new(self, "VPC Endpoint", {
    vpc: vpc,
    service: AWSCDK::EC2::InterfaceVPCEndpointAWSService.KEYSPACES,
})

For cross-region VPC endpoints, specify the service_region parameter:

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::InterfaceVPCEndpoint.new(self, "CrossRegionEndpoint", {
    vpc: vpc,
    service: AWSCDK::EC2::InterfaceVPCEndpointService.new("com.amazonaws.vpce.us-east-1.vpce-svc-123456", 443),
    service_region: "us-east-1",
})

Security groups for interface VPC endpoints

By default, interface VPC endpoints create a new security group and all traffic to the endpoint from within the VPC will be automatically allowed.

Use the connections object to allow other traffic to flow to the endpoint:

my_endpoint = nil # AWSCDK::EC2::InterfaceVPCEndpoint


my_endpoint.connections.allow_default_port_from_any_ipv4

Alternatively, existing security groups can be used by specifying the security_groups prop.

IPv6 and Dualstack support

As IPv4 addresses are running out, many AWS services are adding support for IPv6 or Dualstack (IPv4 and IPv6 support) for their VPC Endpoints.

IPv6 and Dualstack address types can be configured by using:

vpc.add_interface_endpoint("ExampleEndpoint", {
    service: AWSCDK::EC2::InterfaceVPCEndpointAWSService.ECR,
    ip_address_type: AWSCDK::EC2::VPCEndpointIPAddressType::IPV6,
    dns_record_ip_type: AWSCDK::EC2::VPCEndpointDNSRecordIPType::IPV6,
})

The possible values for ip_address_type are:

• IPV4 This option is supported only if all selected subnets have IPv4 address ranges and the endpoint service accepts IPv4 requests.
• IPV6 This option is supported only if all selected subnets are IPv6 only subnets and the endpoint service accepts IPv6 requests.
• DUALSTACK Assign both IPv4 and IPv6 addresses to the endpoint network interfaces. This option is supported only if all selected subnets have both IPv4 and IPv6 address ranges and the endpoint service accepts both IPv4 and IPv6 requests. The possible values for dns_record_ip_type are:
• IPV4 Create A records for the private, Regional, and zonal DNS names. ip_address_type MUST be IPV4 or DUALSTACK
• IPV6 Create AAAA records for the private, Regional, and zonal DNS names. ip_address_type MUST be IPV6 or DUALSTACK
• DUALSTACK Create A and AAAA records for the private, Regional, and zonal DNS names. ip_address_type MUST be DUALSTACK
• SERVICE_DEFINED Create A records for the private, Regional, and zonal DNS names and AAAA records for the Regional and zonal DNS names. ip_address_type MUST be DUALSTACK We can only configure dnsRecordIpType when ipAddressType is specified and private DNS must be enabled to use any DNS related features. To avoid complications, it is recommended to always set private_dns_enabled to true (defaults to true) and set the ip_address_type and dns_record_ip_type explicitly when needing specific IP type behavior. Furthermore, check that the VPC being used supports the IP address type that is being configued. More documentation on compatibility and specifications can be found here

VPC endpoint services

A VPC endpoint service enables you to expose a Network Load Balancer(s) as a provider service to consumers, who connect to your service over a VPC endpoint. You can restrict access to your service via allowed principals (anything that extends ArnPrincipal), and require that new connections be manually accepted. You can also enable Contributor Insight rules.

network_load_balancer1 = nil # AWSCDK::ElasticLoadBalancingv2::NetworkLoadBalancer
network_load_balancer2 = nil # AWSCDK::ElasticLoadBalancingv2::NetworkLoadBalancer


AWSCDK::EC2::VPCEndpointService.new(self, "EndpointService", {
    vpc_endpoint_service_load_balancers: [network_load_balancer1, network_load_balancer2],
    acceptance_required: true,
    allowed_principals: [AWSCDK::IAM::ARNPrincipal.new("arn:aws:iam::123456789012:root")],
    contributor_insights: true,
})

You can also include a service principal in the allowed_principals property by specifying it as a parameter to the ArnPrincipal constructor. The resulting VPC endpoint will have an allowlisted principal of type Service, instead of Arn for that item in the list.

network_load_balancer = nil # AWSCDK::ElasticLoadBalancingv2::NetworkLoadBalancer


AWSCDK::EC2::VPCEndpointService.new(self, "EndpointService", {
    vpc_endpoint_service_load_balancers: [network_load_balancer],
    allowed_principals: [AWSCDK::IAM::ARNPrincipal.new("ec2.amazonaws.com")],
})

You can specify which IP address types (IPv4, IPv6, or both) are supported for your VPC endpoint service:

network_load_balancer = nil # AWSCDK::ElasticLoadBalancingv2::NetworkLoadBalancer


AWSCDK::EC2::VPCEndpointService.new(self, "EndpointService", {
    vpc_endpoint_service_load_balancers: [network_load_balancer],
    # Support both IPv4 and IPv6 connections to the endpoint service
    supported_ip_address_types: [
        AWSCDK::EC2::IPAddressType::IPV4,
        AWSCDK::EC2::IPAddressType::IPV6,
    ],
})

You can restrict access to your endpoint service to specific AWS regions:

network_load_balancer = nil # AWSCDK::ElasticLoadBalancingv2::NetworkLoadBalancer


AWSCDK::EC2::VPCEndpointService.new(self, "EndpointService", {
    vpc_endpoint_service_load_balancers: [network_load_balancer],
    # Allow service consumers from these regions only
    allowed_regions: ["us-east-1", "eu-west-1"],
})

Endpoint services support private DNS, which makes it easier for clients to connect to your service by automatically setting up DNS in their VPC. You can enable private DNS on an endpoint service like so:

require 'aws-cdk-lib'
zone = nil # AWSCDK::Route53::PublicHostedZone
vpces = nil # AWSCDK::EC2::VPCEndpointService


AWSCDK::Route53::VPCEndpointServiceDomainName.new(self, "EndpointDomain", {
    endpoint_service: vpces,
    domain_name: "my-stuff.aws-cdk.dev",
    public_hosted_zone: zone,
})

Note: The domain name must be owned (registered through Route53) by the account the endpoint service is in, or delegated to the account. The VpcEndpointServiceDomainName will handle the AWS side of domain verification, the process for which can be found here

Client VPN endpoint

AWS Client VPN is a managed client-based VPN service that enables you to securely access your AWS resources and resources in your on-premises network. With Client VPN, you can access your resources from any location using an OpenVPN-based VPN client.

Use the add_client_vpn_endpoint() method to add a client VPN endpoint to a VPC:

vpc.add_client_vpn_endpoint("Endpoint", {
    cidr: "10.100.0.0/16",
    server_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/server-certificate-id",
    # Mutual authentication
    client_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/client-certificate-id",
    # User-based authentication
    user_based_authentication: AWSCDK::EC2::ClientVpnUserBasedAuthentication.federated(saml_provider),
})

The endpoint must use at least one authentication method:

• Mutual authentication with a client certificate
• User-based authentication (directory or federated)

If user-based authentication is used, the self-service portal URL is made available via a CloudFormation output.

By default, a new security group is created, and logging is enabled. Moreover, a rule to authorize all users to the VPC CIDR is created.

To customize authorization rules, set the authorize_all_users_to_vpc_cidr prop to false and use add_authorization_rule():

endpoint = vpc.add_client_vpn_endpoint("Endpoint", {
    cidr: "10.100.0.0/16",
    server_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/server-certificate-id",
    user_based_authentication: AWSCDK::EC2::ClientVpnUserBasedAuthentication.federated(saml_provider),
    authorize_all_users_to_vpc_cidr: false,
})

endpoint.add_authorization_rule("Rule", {
    cidr: "10.0.10.0/32",
    group_id: "group-id",
})

Use add_route() to configure network routes:

endpoint = vpc.add_client_vpn_endpoint("Endpoint", {
    cidr: "10.100.0.0/16",
    server_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/server-certificate-id",
    user_based_authentication: AWSCDK::EC2::ClientVpnUserBasedAuthentication.federated(saml_provider),
})

# Client-to-client access
endpoint.add_route("Route", {
    cidr: "10.100.0.0/16",
    target: AWSCDK::EC2::ClientVpnRouteTarget.local,
})

Use the connections object of the endpoint to allow traffic to other security groups.

To enable client route enforcement, configure the clientRouteEnforcementOptions.enforced prop to true:

endpoint = vpc.add_client_vpn_endpoint("Endpoint", {
    cidr: "10.100.0.0/16",
    server_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/server-certificate-id",
    client_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/client-certificate-id",
    client_route_enforcement_options: {
        enforced: true,
    },
})

To control whether clients are automatically disconnected when the maximum session duration is reached, use the disconnect_on_session_timeout prop. By default (true), clients are disconnected and must manually reconnect. Set to false to allow automatic reconnection attempts:

endpoint = vpc.add_client_vpn_endpoint("Endpoint", {
    cidr: "10.100.0.0/16",
    server_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/server-certificate-id",
    client_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/client-certificate-id",
    disconnect_on_session_timeout: false,
})

Detail information about maximum VPN session duration timeout can be found in the AWS documentation.

Instances

You can use the Instance class to start up a single EC2 instance. For production setups, we recommend you use an AutoScalingGroup from the aws-autoscaling module instead, as AutoScalingGroups will take care of restarting your instance if it ever fails.

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType


# Amazon Linux 2
AWSCDK::EC2::Instance.new(self, "Instance2", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2,
})

# Amazon Linux 2 with kernel 5.x
AWSCDK::EC2::Instance.new(self, "Instance3", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2({
        kernel: AWSCDK::EC2::AmazonLinux2Kernel.KERNEL_5_10,
    }),
})

# Amazon Linux 2023
AWSCDK::EC2::Instance.new(self, "Instance4", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023,
})

# Graviton 3 Processor
AWSCDK::EC2::Instance.new(self, "Instance5", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023({
        cpu_type: AWSCDK::EC2::AmazonLinuxCpuType::ARM_64,
    }),
})

Latest Amazon Linux Images

Rather than specifying a specific AMI ID to use, it is possible to specify a SSM Parameter that contains the AMI ID. AWS publishes a set of public parameters that contain the latest Amazon Linux AMIs. To make it easier to query a particular image parameter, the CDK provides a couple of constructs AmazonLinux2ImageSsmParameter, AmazonLinux2022ImageSsmParameter, & AmazonLinux2023SsmParameter. For example to use the latest al2023 image:

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::Instance.new(self, "LatestAl2023", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023,
})

Warning Since this retrieves the value from an SSM parameter at deployment time, the value will be resolved each time the stack is deployed. This means that if the parameter contains a different value on your next deployment, the instance will be replaced.

It is also possible to perform the lookup once at synthesis time and then cache the value in CDK context. This way the value will not change on future deployments unless you manually refresh the context.

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::Instance.new(self, "LatestAl2023", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023({
        cached_in_context: true,
    }),
})

# or
AWSCDK::EC2::Instance.new(self, "LatestAl2023", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    # context cache is turned on by default
    machine_image: AWSCDK::EC2::AmazonLinux2023ImageSSMParameter.new,
})

# or
AWSCDK::EC2::Instance.new(self, "LatestAl2023", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023({
        cached_in_context: true,
        # creates a distinct context variable for this image, instead of resolving to the same
        # value anywhere this lookup is done in your app
        additional_cache_key: @node.path,
    }),
})

# or
AWSCDK::EC2::Instance.new(self, "LatestAl2023", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    # context cache is turned on by default
    machine_image: AWSCDK::EC2::AmazonLinux2023ImageSSMParameter.new({
        # creates a distinct context variable for this image, instead of resolving to the same
        # value anywhere this lookup is done in your app
        additional_cache_key: @node.path,
    }),
})

Kernel Versions

Each Amazon Linux AMI uses a specific kernel version. Most Amazon Linux generations come with an AMI using the "default" kernel and then 1 or more AMIs using a specific kernel version, which may or may not be different from the default kernel version.

For example, Amazon Linux 2 has two different AMIs available from the SSM parameters.

• /aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-ebs

  • This is the "default" kernel which uses kernel-4.14

• /aws/service/ami-amazon-linux-latest/amzn2-ami-kernel-5.10-hvm-x86_64-ebs

If a new Amazon Linux generation AMI is published with a new kernel version, then a new SSM parameter will be created with the new version (e.g. /aws/service/ami-amazon-linux-latest/amzn2-ami-kernel-5.15-hvm-x86_64-ebs), but the "default" AMI may or may not be updated.

If you would like to make sure you always have the latest kernel version, then either specify the specific latest kernel version or opt-in to using the CDK latest kernel version.

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::Instance.new(self, "LatestAl2023", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    # context cache is turned on by default
    machine_image: AWSCDK::EC2::AmazonLinux2023ImageSSMParameter.new({
        kernel: AWSCDK::EC2::AmazonLinux2023Kernel.KERNEL_6_1,
    }),
})

CDK managed latest

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::Instance.new(self, "LatestAl2023", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    # context cache is turned on by default
    machine_image: AWSCDK::EC2::AmazonLinux2023ImageSSMParameter.new({
        kernel: AWSCDK::EC2::AmazonLinux2023Kernel.CDK_LATEST,
    }),
})

# or

AWSCDK::EC2::Instance.new(self, "LatestAl2023", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::C7G, AWSCDK::EC2::InstanceSize::LARGE),
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023,
})

When using the CDK managed latest version, when a new kernel version is made available the LATEST will be updated to point to the new kernel version. You then would be required to update the newest CDK version for it to take effect.

Configuring Instances using CloudFormation Init (cfn-init)

CloudFormation Init allows you to configure your instances by writing files to them, installing software packages, starting services and running arbitrary commands. By default, if any of the instance setup commands throw an error; the deployment will fail and roll back to the previously known good state. The following documentation also applies to AutoScalingGroups.

For the full set of capabilities of this system, see the documentation for AWS::CloudFormation::Init. Here is an example of applying some configuration to an instance:

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType
machine_image = nil # AWSCDK::EC2::IMachineImage


AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: machine_image,

    # Showing the most complex setup, if you have simpler requirements
    # you can use `CloudFormationInit.fromElements()`.
    init: AWSCDK::EC2::CloudFormationInit.from_config_sets({
        config_sets: {
            # Applies the configs below in this order
            default: ["yumPreinstall", "config"],
        },
        configs: {
            yum_preinstall: AWSCDK::EC2::InitConfig.new([
                AWSCDK::EC2::InitPackage.yum("git"),
            ]),
            config: AWSCDK::EC2::InitConfig.new([
                AWSCDK::EC2::InitFile.from_object("/etc/stack.json", {
                    stack_id: AWSCDK::Stack.of(self).stack_id,
                    stack_name: AWSCDK::Stack.of(self).stack_name,
                    region: AWSCDK::Stack.of(self).region,
                }),
                AWSCDK::EC2::InitGroup.from_name("my-group"),
                AWSCDK::EC2::InitUser.from_name("my-user"),
                AWSCDK::EC2::InitPackage.rpm("http://mirrors.ukfast.co.uk/sites/dl.fedoraproject.org/pub/epel/8/Everything/x86_64/Packages/r/rubygem-git-1.5.0-2.el8.noarch.rpm"),
            ]),
        },
    }),
    init_options: {
        # Optional, which configsets to activate (['default'] by default)
        config_sets: ["default"],

        # Optional, how long the installation is expected to take (5 minutes by default)
        timeout: AWSCDK::Duration.minutes(30),

        # Optional, whether to include the --url argument when running cfn-init and cfn-signal commands (false by default)
        include_url: true,

        # Optional, whether to include the --role argument when running cfn-init and cfn-signal commands (false by default)
        include_role: true,
    },
})

InitCommand can not be used to start long-running processes. At deploy time, cfn-init will always wait for the process to exit before continuing, causing the CloudFormation deployment to fail because the signal hasn't been received within the expected timeout.

Instead, you should install a service configuration file onto your machine InitFile, and then use InitService to start it.

If your Linux OS is using SystemD (like Amazon Linux 2 or higher), the CDK has helpers to create a long-running service using CFN Init. You can create a SystemD-compatible config file using InitService.systemdConfigFile(), and start it immediately. The following examples shows how to start a trivial Python 3 web server:

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType


AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023,

    init: AWSCDK::EC2::CloudFormationInit.from_elements(AWSCDK::EC2::InitService.systemd_config_file("simpleserver", {
        command: "/usr/bin/python3 -m http.server 8080",
        cwd: "/var/www/html",
    }), AWSCDK::EC2::InitService.enable("simpleserver", {
        service_manager: AWSCDK::EC2::ServiceManager::SYSTEMD,
    }), AWSCDK::EC2::InitFile.from_string("/var/www/html/index.html", "Hello! It's working!")),
})

You can have services restarted after the init process has made changes to the system. To do that, instantiate an InitServiceRestartHandle and pass it to the config elements that need to trigger the restart and the service itself. For example, the following config writes a config file for nginx, extracts an archive to the root directory, and then restarts nginx so that it picks up the new config and files:

my_bucket = nil # AWSCDK::S3::Bucket


handle = AWSCDK::EC2::InitServiceRestartHandle.new

AWSCDK::EC2::CloudFormationInit.from_elements(AWSCDK::EC2::InitFile.from_string("/etc/nginx/nginx.conf", "...", {service_restart_handles: [handle]}), AWSCDK::EC2::InitSource.from_s3_object("/var/www/html", my_bucket, "html.zip", {service_restart_handles: [handle]}), AWSCDK::EC2::InitService.enable("nginx", {
    service_restart_handle: handle,
}))

You can use the environment_variables or environment_files parameters to specify environment variables for your services:

AWSCDK::EC2::InitConfig.new([
    AWSCDK::EC2::InitFile.from_string("/myvars.env", "VAR_FROM_FILE=\"VAR_FROM_FILE\""),
    AWSCDK::EC2::InitService.systemd_config_file("myapp", {
        command: "/usr/bin/python3 -m http.server 8080",
        cwd: "/var/www/html",
        environment_variables: {
            MY_VAR: "MY_VAR",
        },
        environment_files: ["/myvars.env"],
    }),
])

Bastion Hosts

A bastion host functions as an instance used to access servers and resources in a VPC without open up the complete VPC on a network level. You can use bastion hosts using a standard SSH connection targeting port 22 on the host. As an alternative, you can connect the SSH connection feature of AWS Systems Manager Session Manager, which does not need an opened security group. (https://aws.amazon.com/about-aws/whats-new/2019/07/session-manager-launches-tunneling-support-for-ssh-and-scp/)

A default bastion host for use via SSM can be configured like:

host = AWSCDK::EC2::BastionHostLinux.new(self, "BastionHost", {vpc: vpc})

If you want to connect from the internet using SSH, you need to place the host into a public subnet. You can then configure allowed source hosts.

host = AWSCDK::EC2::BastionHostLinux.new(self, "BastionHost", {
    vpc: vpc,
    subnet_selection: {subnet_type: AWSCDK::EC2::SubnetType::PUBLIC},
})
host.allow_ssh_access_from(AWSCDK::EC2::Peer.ipv4("1.2.3.4/32"))

As there are no SSH public keys deployed on this machine, you need to use EC2 Instance Connect with the command aws ec2-instance-connect send-ssh-public-key to provide your SSH public key.

EBS volume for the bastion host can be encrypted like:

host = AWSCDK::EC2::BastionHostLinux.new(self, "BastionHost", {
    vpc: vpc,
    block_devices: [
        {
            device_name: "/dev/sdh",
            volume: AWSCDK::EC2::BlockDeviceVolume.ebs(10, {
                encrypted: true,
            }),
        },
    ],
})

It's recommended to set the @aws-cdk/aws-ec2:bastionHostUseAmazonLinux2023ByDefault feature flag to true to use Amazon Linux 2023 as the bastion host AMI. Without this flag set, the bastion host will default to Amazon Linux 2, which will be unsupported in June 2025.

{
  "context": {
    "@aws-cdk/aws-ec2:bastionHostUseAmazonLinux2023ByDefault": true
  }
}

Placement Group

Specify placement_group to enable the placement group support:

instance_type = nil # AWSCDK::EC2::InstanceType


pg = AWSCDK::EC2::PlacementGroup.new(self, "test-pg", {
    strategy: AWSCDK::EC2::PlacementGroupStrategy::SPREAD,
})

AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023,
    placement_group: pg,
})

Block Devices

To add EBS block device mappings, specify the block_devices property. The following example sets the EBS-backed root device (/dev/sda1) size to 50 GiB, and adds another EBS-backed device mapped to /dev/sdm that is 100 GiB in size:

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType
machine_image = nil # AWSCDK::EC2::IMachineImage


AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: machine_image,

    # ...

    block_devices: [
        {
            device_name: "/dev/sda1",
            volume: AWSCDK::EC2::BlockDeviceVolume.ebs(50),
        },
        {
            device_name: "/dev/sdm",
            volume: AWSCDK::EC2::BlockDeviceVolume.ebs(100),
        },
    ],
})

It is also possible to encrypt the block devices. In this example we will create an customer managed key encrypted EBS-backed root device:

require 'aws-cdk-lib'

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType
machine_image = nil # AWSCDK::EC2::IMachineImage


kms_key = AWSCDK::KMS::Key.new(self, "KmsKey")

AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: machine_image,

    # ...

    block_devices: [
        {
            device_name: "/dev/sda1",
            volume: AWSCDK::EC2::BlockDeviceVolume.ebs(50, {
                encrypted: true,
                kms_key: kms_key,
            }),
        },
    ],
})

To specify the throughput value for gp3 volumes, use the throughput property:

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType
machine_image = nil # AWSCDK::EC2::IMachineImage


AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: machine_image,

    # ...

    block_devices: [
        {
            device_name: "/dev/sda1",
            volume: AWSCDK::EC2::BlockDeviceVolume.ebs(100, {
                volume_type: AWSCDK::EC2::EbsDeviceVolumeType::GP3,
                throughput: 250,
            }),
        },
    ],
})

EBS Optimized Instances

An Amazon EBS–optimized instance uses an optimized configuration stack and provides additional, dedicated capacity for Amazon EBS I/O. This optimization provides the best performance for your EBS volumes by minimizing contention between Amazon EBS I/O and other traffic from your instance.

Depending on the instance type, this features is enabled by default while others require explicit activation. Please refer to the documentation for details.

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType
machine_image = nil # AWSCDK::EC2::IMachineImage


AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: machine_image,
    ebs_optimized: true,
    block_devices: [
        {
            device_name: "/dev/xvda",
            volume: AWSCDK::EC2::BlockDeviceVolume.ebs(8),
        },
    ],
})

Volumes

Whereas a BlockDeviceVolume is an EBS volume that is created and destroyed as part of the creation and destruction of a specific instance. A Volume is for when you want an EBS volume separate from any particular instance. A Volume is an EBS block device that can be attached to, or detached from, any instance at any time. Some types of Volumes can also be attached to multiple instances at the same time to allow you to have shared storage between those instances.

A notable restriction is that a Volume can only be attached to instances in the same availability zone as the Volume itself.

The following demonstrates how to create a 500 GiB encrypted Volume in the us-west-2a availability zone, and give a role the ability to attach that Volume to a specific instance:

instance = nil # AWSCDK::EC2::Instance
role = nil # AWSCDK::IAM::Role


volume = AWSCDK::EC2::Volume.new(self, "Volume", {
    availability_zone: "us-west-2a",
    size: AWSCDK::Size.gibibytes(500),
    encrypted: true,
})

volume.grant_attach_volume(role, [instance])

Instances Attaching Volumes to Themselves

If you need to grant an instance the ability to attach/detach an EBS volume to/from itself, then using grant_attach_volume and grant_detach_volume as outlined above will lead to an unresolvable circular reference between the instance role and the instance. In this case, use grant_attach_volume_by_resource_tag and grant_detach_volume_by_resource_tag as follows:

instance = nil # AWSCDK::EC2::Instance
volume = nil # AWSCDK::EC2::Volume


attach_grant = volume.grant_attach_volume_by_resource_tag(instance.grant_principal, [instance])
detach_grant = volume.grant_detach_volume_by_resource_tag(instance.grant_principal, [instance])

Attaching Volumes

The Amazon EC2 documentation for Linux Instances and Windows Instances contains information on how to attach and detach your Volumes to/from instances, and how to format them for use.

The following is a sample skeleton of EC2 UserData that can be used to attach a Volume to the Linux instance that it is running on:

instance = nil # AWSCDK::EC2::Instance
volume = nil # AWSCDK::EC2::Volume


volume.grant_attach_volume_by_resource_tag(instance.grant_principal, [instance])
target_device = "/dev/xvdz"
instance.user_data.add_commands("TOKEN=$(curl -SsfX PUT \"http://169.254.169.254/latest/api/token\" -H \"X-aws-ec2-metadata-token-ttl-seconds: 21600\")", "INSTANCE_ID=$(curl -SsfH \"X-aws-ec2-metadata-token: $TOKEN\" http://169.254.169.254/latest/meta-data/instance-id)", "aws --region #{AWSCDK::Stack.of(self).region} ec2 attach-volume --volume-id #{volume.volume_id} --instance-id $INSTANCE_ID --device #{target_device}", "while ! test -e #{target_device}; do sleep 1; done")

Tagging Volumes

You can configure tag propagation on volume creation.

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType
machine_image = nil # AWSCDK::EC2::IMachineImage


AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    machine_image: machine_image,
    instance_type: instance_type,
    propagate_tags_to_volume_on_creation: true,
})

Throughput on GP3 Volumes

You can specify the throughput of a GP3 volume from 125 (default) to 2000.

AWSCDK::EC2::Volume.new(self, "Volume", {
    availability_zone: "us-east-1a",
    size: AWSCDK::Size.gibibytes(125),
    volume_type: AWSCDK::EC2::EbsDeviceVolumeType::GP3,
    throughput: 125,
})

Volume initialization rate

When creating an EBS volume from a snapshot, you can specify the volume initialization rate at which the snapshot blocks are downloaded from Amazon S3 to the volume. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation.

AWSCDK::EC2::Volume.new(self, "Volume", {
    availability_zone: "us-east-1a",
    size: AWSCDK::Size.gibibytes(500),
    snapshot_id: "snap-1234567890abcdef0",
    volume_initialization_rate: AWSCDK::Size.mebibytes(250),
})

The volume_initialization_rate must be:

• Between 100 and 300 MiB/s
• Only specified when creating a volume from a snapshot

Configuring Instance Metadata Service (IMDS)

Comprehensive Metadata Options

You can configure EC2 Instance Metadata Service options using individual properties. This provides comprehensive control over all metadata service settings:

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType
machine_image = nil # AWSCDK::EC2::IMachineImage


# Example 1: Enforce IMDSv2 with comprehensive options
AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: machine_image,
    http_endpoint: true,
    http_protocol_ipv6: false,
    http_put_response_hop_limit: 2,
    http_tokens: AWSCDK::EC2::HttpTokens::REQUIRED,
    instance_metadata_tags: true,
})

# Example 2: Enforce IMDSv2 with minimal configuration
AWSCDK::EC2::Instance.new(self, "SecureInstance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: machine_image,
    http_tokens: AWSCDK::EC2::HttpTokens::REQUIRED,
})

Simple IMDSv2 Enforcement

For simple IMDSv2 enforcement without additional configuration, you can use the require_imdsv2 property:

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType
machine_image = nil # AWSCDK::EC2::IMachineImage


AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: machine_image,

    # Simple IMDSv2 enforcement
    require_imdsv2: true,
})

Applying to Multiple Instances

You can also use the either the InstanceRequireImdsv2Aspect for EC2 instances or the LaunchTemplateRequireImdsv2Aspect for EC2 launch templates to apply the operation to multiple instances or launch templates, respectively.

The following example demonstrates how to use the InstanceRequireImdsv2Aspect to require IMDSv2 for all EC2 instances in a stack:

aspect = AWSCDK::EC2::InstanceRequireImdsv2Aspect.new
AWSCDK::Aspects.of(self).add(aspect)

Associating a Public IP Address with an Instance

All subnets have an attribute that determines whether instances launched into that subnet are assigned a public IPv4 address. This attribute is set to true by default for default public subnets. Thus, an EC2 instance launched into a default public subnet will be assigned a public IPv4 address. Nondefault public subnets have this attribute set to false by default and any EC2 instance launched into a nondefault public subnet will not be assigned a public IPv4 address automatically. To automatically assign a public IPv4 address to an instance launched into a nondefault public subnet, you can set the associate_public_ip_address property on the Instance construct to true. Alternatively, to not automatically assign a public IPv4 address to an instance launched into a default public subnet, you can set associate_public_ip_address to false. Including this property, removing this property, or updating the value of this property on an existing instance will result in replacement of the instance.

vpc = AWSCDK::EC2::VPC.new(self, "VPC", {
    cidr: "10.0.0.0/16",
    nat_gateways: 0,
    max_azs: 3,
    subnet_configuration: [
        {
            name: "public-subnet-1",
            subnet_type: AWSCDK::EC2::SubnetType::PUBLIC,
            cidr_mask: 24,
        },
    ],
})

instance = AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    vpc_subnets: {subnet_group_name: "public-subnet-1"},
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::T3, AWSCDK::EC2::InstanceSize::NANO),
    machine_image: AWSCDK::EC2::AmazonLinuxImage.new({generation: AWSCDK::EC2::AmazonLinuxGeneration::AMAZON_LINUX_2}),
    detailed_monitoring: true,
    associate_public_ip_address: true,
})

Specifying a key pair

To allow SSH access to an EC2 instance by default, a Key Pair must be specified. Key pairs can be provided with the key_pair property to instances and launch templates. You can create a key pair for an instance like this:

vpc = nil # AWSCDK::EC2::VPC
instance_type = nil # AWSCDK::EC2::InstanceType


key_pair = AWSCDK::EC2::KeyPair.new(self, "KeyPair", {
    type: AWSCDK::EC2::KeyPairType::ED25519,
    format: AWSCDK::EC2::KeyPairFormat::PEM,
})
instance = AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: instance_type,
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2023,
    key_pair: key_pair,
})

When a new EC2 Key Pair is created (without imported material), the private key material is automatically stored in Systems Manager Parameter Store. This can be retrieved from the key pair construct:

key_pair = AWSCDK::EC2::KeyPair.new(self, "KeyPair")
private_key = key_pair.private_key

If you already have an SSH key that you wish to use in EC2, that can be provided when constructing the KeyPair. If public key material is provided, the key pair is considered "imported" and there will not be any data automatically stored in Systems Manager Parameter Store and the type property cannot be specified for the key pair.

key_pair = AWSCDK::EC2::KeyPair.new(self, "KeyPair", {
    public_key_material: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB7jpNzG+YG0s+xIGWbxrxIZiiozHOEuzIJacvASP0mq",
})

Using an existing EC2 Key Pair

If you already have an EC2 Key Pair created outside of the CDK, you can import that key to your CDK stack.

You can import it purely by name:

key_pair = AWSCDK::EC2::KeyPair.from_key_pair_name(self, "KeyPair", "the-keypair-name")

Or by specifying additional attributes:

key_pair = AWSCDK::EC2::KeyPair.from_key_pair_attributes(self, "KeyPair", {
    key_pair_name: "the-keypair-name",
    type: AWSCDK::EC2::KeyPairType::RSA,
})

Using IPv6 IPs

Instances can be given IPv6 IPs by launching them into a subnet of a dual stack VPC.

vpc = AWSCDK::EC2::VPC.new(self, "Ip6VpcDualStack", {
    ip_protocol: AWSCDK::EC2::IPProtocol::DUAL_STACK,
    subnet_configuration: [
        {
            name: "Public",
            subnet_type: AWSCDK::EC2::SubnetType::PUBLIC,
            map_public_ip_on_launch: true,
        },
        {
            name: "Private",
            subnet_type: AWSCDK::EC2::SubnetType::PRIVATE_ISOLATED,
        },
    ],
})

instance = AWSCDK::EC2::Instance.new(self, "MyInstance", {
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::T2, AWSCDK::EC2::InstanceSize::MICRO),
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2,
    vpc: vpc,
    vpc_subnets: {subnet_type: AWSCDK::EC2::SubnetType::PUBLIC},
    allow_all_ipv6_outbound: true,
})

instance.connections.allow_from(AWSCDK::EC2::Peer.any_ipv6, AWSCDK::EC2::Port.all_icmp_v6, "allow ICMPv6")

Note to set map_public_ip_on_launch to true in the subnet_configuration.

Additionally, IPv6 support varies by instance type. Most instance types have IPv6 support with exception of m1-m3, c1, g2, and t1.micro. A full list can be found here: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html#AvailableIpPerENI.

Specifying the IPv6 Address

If you want to specify the number of IPv6 addresses to assign to the instance, you can use the ipv6_addresse_count property:

# dual stack VPC
vpc = nil # AWSCDK::EC2::VPC


instance = AWSCDK::EC2::Instance.new(self, "MyInstance", {
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::M5, AWSCDK::EC2::InstanceSize::LARGE),
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2,
    vpc: vpc,
    vpc_subnets: {subnet_type: AWSCDK::EC2::SubnetType::PUBLIC},
    # Assign 2 IPv6 addresses to the instance
    ipv6_address_count: 2,
})

Credit configuration modes for burstable instances

You can set the credit configuration mode for burstable instances (T2, T3, T3a and T4g instance types):

vpc = nil # AWSCDK::EC2::VPC


instance = AWSCDK::EC2::Instance.new(self, "Instance", {
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::T3, AWSCDK::EC2::InstanceSize::MICRO),
    machine_image: AWSCDK::EC2::MachineImage.latest_amazon_linux2,
    vpc: vpc,
    credit_specification: AWSCDK::EC2::CpuCredits::STANDARD,
})

It is also possible to set the credit configuration mode for NAT instances.

nat_instance_provider = AWSCDK::EC2::NatProvider.instance({
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::T4G, AWSCDK::EC2::InstanceSize::LARGE),
    machine_image: AWSCDK::EC2::AmazonLinuxImage.new,
    credit_specification: AWSCDK::EC2::CpuCredits::UNLIMITED,
})
AWSCDK::EC2::VPC.new(self, "VPC", {
    nat_gateway_provider: nat_instance_provider,
})

Note: CpuCredits.UNLIMITED mode is not supported for T3 instances that are launched on a Dedicated Host.

Shutdown behavior

You can specify the behavior of the instance when you initiate shutdown from the instance (using the operating system command for system shutdown).

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::Instance.new(self, "Instance", {
    vpc: vpc,
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::T3, AWSCDK::EC2::InstanceSize::NANO),
    machine_image: AWSCDK::EC2::AmazonLinuxImage.new({generation: AWSCDK::EC2::AmazonLinuxGeneration::AMAZON_LINUX_2}),
    instance_initiated_shutdown_behavior: AWSCDK::EC2::InstanceInitiatedShutdownBehavior::TERMINATE,
})

Enabling Nitro Enclaves

You can enable AWS Nitro Enclaves for your EC2 instances by setting the enclave_enabled property to true. Nitro Enclaves is a feature of AWS Nitro System that enables creating isolated and highly constrained CPU environments known as enclaves.

vpc = nil # AWSCDK::EC2::VPC


instance = AWSCDK::EC2::Instance.new(self, "Instance", {
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::M5, AWSCDK::EC2::InstanceSize::XLARGE),
    machine_image: AWSCDK::EC2::AmazonLinuxImage.new,
    vpc: vpc,
    enclave_enabled: true,
})

NOTE: You must use an instance type and operating system that support Nitro Enclaves. For more information, see Requirements.

Enabling Termination Protection

You can enable Termination Protection for your EC2 instances by setting the disable_api_termination property to true. Termination Protection controls whether the instance can be terminated using the AWS Management Console, AWS Command Line Interface (AWS CLI), or API.

vpc = nil # AWSCDK::EC2::VPC


instance = AWSCDK::EC2::Instance.new(self, "Instance", {
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::M5, AWSCDK::EC2::InstanceSize::XLARGE),
    machine_image: AWSCDK::EC2::AmazonLinuxImage.new,
    vpc: vpc,
    disable_api_termination: true,
})

Enabling Instance Hibernation

You can enable Instance Hibernation for your EC2 instances by setting the hibernation_enabled property to true. Instance Hibernation saves the instance's in-memory (RAM) state when an instance is stopped, and restores that state when the instance is started.

vpc = nil # AWSCDK::EC2::VPC


instance = AWSCDK::EC2::Instance.new(self, "Instance", {
    instance_type: AWSCDK::EC2::InstanceType.of(AWSCDK::EC2::InstanceClass::M5, AWSCDK::EC2::InstanceSize::XLARGE),
    machine_image: AWSCDK::EC2::AmazonLinuxImage.new,
    vpc: vpc,
    hibernation_enabled: true,
    block_devices: [
        {
            device_name: "/dev/xvda",
            volume: AWSCDK::EC2::BlockDeviceVolume.ebs(30, {
                volume_type: AWSCDK::EC2::EbsDeviceVolumeType::GP3,
                encrypted: true,
                delete_on_termination: true,
            }),
        },
    ],
})

NOTE: You must use an instance and a volume that meet the requirements for hibernation. For more information, see Prerequisites for Amazon EC2 instance hibernation.

VPC Flow Logs

VPC Flow Logs is a feature that enables you to capture information about the IP traffic going to and from network interfaces in your VPC. Flow log data can be published to Amazon CloudWatch Logs and Amazon S3. After you've created a flow log, you can retrieve and view its data in the chosen destination. (https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html).

By default, a flow log will be created with CloudWatch Logs as the destination.

You can create a flow log like this:

vpc = nil # AWSCDK::EC2::VPC


AWSCDK::EC2::FlowLog.new(self, "FlowLog", {
    resource_type: AWSCDK::EC2::FlowLogResourceType.from_vpc(vpc),
})

Or you can add a Flow Log to a VPC by using the addFlowLog method like this:

vpc = AWSCDK::EC2::VPC.new(self, "Vpc")

vpc.add_flow_log("FlowLog")

You can also add multiple flow logs with different destinations.

vpc = AWSCDK::EC2::VPC.new(self, "Vpc")

vpc.add_flow_log("FlowLogS3", {
    destination: AWSCDK::EC2::FlowLogDestination.to_s3,
})

# Only reject traffic and interval every minute.
vpc.add_flow_log("FlowLogCloudWatch", {
    traffic_type: AWSCDK::EC2::FlowLogTrafficType::REJECT,
    max_aggregation_interval: AWSCDK::EC2::FlowLogMaxAggregationInterval::ONE_MINUTE,
})

To create a Transit Gateway flow log, you can use the from_transit_gateway_id method:

tgw = nil # AWSCDK::EC2::CfnTransitGateway


AWSCDK::EC2::FlowLog.new(self, "TransitGatewayFlowLog", {
    resource_type: AWSCDK::EC2::FlowLogResourceType.from_transit_gateway_id(tgw.ref),
})

To create a Transit Gateway Attachment flow log, you can use the from_transit_gateway_attachment_id method:

tgw_attachment = nil # AWSCDK::EC2::CfnTransitGatewayAttachment


AWSCDK::EC2::FlowLog.new(self, "TransitGatewayAttachmentFlowLog", {
    resource_type: AWSCDK::EC2::FlowLogResourceType.from_transit_gateway_attachment_id(tgw_attachment.ref),
})