@aws-cdk/aws-ec2

What is @aws-cdk/aws-ec2?

@aws-cdk/aws-ec2 is an AWS Cloud Development Kit (CDK) library that allows you to define and manage Amazon EC2 instances and related networking infrastructure using code. This package provides a high-level, object-oriented abstraction to create and configure EC2 instances, VPCs, security groups, and other networking components in a programmatic way.

What are @aws-cdk/aws-ec2's main functionalities?

Create a VPC

This code sample demonstrates how to create a Virtual Private Cloud (VPC) with the maximum number of Availability Zones (AZs) in the region. The VPC is a logically isolated network that you can use to launch AWS resources.

const ec2 = require('@aws-cdk/aws-ec2');
const cdk = require('@aws-cdk/core');

class MyStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    const vpc = new ec2.Vpc(this, 'MyVpc', {
      maxAzs: 3 // Default is all AZs in the region
    });
  }
}

const app = new cdk.App();
new MyStack(app, 'MyStack');
app.synth();

Create an EC2 Instance

This code sample demonstrates how to create an EC2 instance within a VPC. The instance is of type 't2.micro' and uses the Amazon Linux AMI.

const ec2 = require('@aws-cdk/aws-ec2');
const cdk = require('@aws-cdk/core');

class MyStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    const vpc = new ec2.Vpc(this, 'MyVpc');

    const instance = new ec2.Instance(this, 'MyInstance', {
      vpc,
      instanceType: new ec2.InstanceType('t2.micro'),
      machineImage: new ec2.AmazonLinuxImage(),
    });
  }
}

const app = new cdk.App();
new MyStack(app, 'MyStack');
app.synth();

Create a Security Group

This code sample demonstrates how to create a Security Group within a VPC. The Security Group allows inbound SSH access (port 22) from any IPv4 address.

const ec2 = require('@aws-cdk/aws-ec2');
const cdk = require('@aws-cdk/core');

class MyStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    const vpc = new ec2.Vpc(this, 'MyVpc');

    const securityGroup = new ec2.SecurityGroup(this, 'MySecurityGroup', {
      vpc,
      description: 'Allow ssh access to ec2 instances',
      allowAllOutbound: true
    });

    securityGroup.addIngressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(22), 'allow ssh access from the world');
  }
}

const app = new cdk.App();
new MyStack(app, 'MyStack');
app.synth();

Other packages similar to @aws-cdk/aws-ec2

aws-sdk

The aws-sdk package is the official AWS SDK for JavaScript, which allows you to interact with various AWS services, including EC2. Unlike @aws-cdk/aws-ec2, which is used for defining infrastructure as code, aws-sdk is used for making API calls to manage AWS resources at runtime.

terraform

Terraform is an open-source infrastructure as code software tool created by HashiCorp. It allows you to define and provision data center infrastructure using a high-level configuration language. While @aws-cdk/aws-ec2 is specific to AWS and uses TypeScript/JavaScript, Terraform is cloud-agnostic and uses its own configuration language called HCL.

pulumi

Pulumi is an infrastructure as code tool that allows you to define cloud resources using general-purpose programming languages like TypeScript, JavaScript, Python, and Go. Similar to @aws-cdk/aws-ec2, Pulumi provides a way to define AWS resources programmatically, but it supports multiple cloud providers and languages.

README

AWS Compute and Networking Construct Library

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

VPC

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

import ec2 = require('@aws-cdk/aws-ec2');

const vpc = new ec2.VpcNetwork(this, 'VPC');

All default Constructs requires 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.

Our default VpcNetwork class creates a private and public subnet for every availability zone. Classes that use the VPC will generally launch instances into all private subnets, and provide a parameter called vpcSubnets to allow you to override the placement. Read more about subnets.

Advanced Subnet Configuration

If you require the ability to configure subnets the VpcNetwork can be customized with SubnetConfiguration array. This is best explained by an example:

import ec2 = require('@aws-cdk/aws-ec2');

const vpc = new ec2.VpcNetwork(this, 'TheVPC', {
  cidr: '10.0.0.0/21',
  subnetConfiguration: [
    {
      cidrMask: 24,
      name: 'Ingress',
      subnetType: SubnetType.Public,
    },
    {
      cidrMask: 24,
      name: 'Application',
      subnetType: SubnetType.Private,
    },
    {
      cidrMask: 28,
      name: 'Database',
      subnetType: SubnetType.Isolated,
    }
  ],
});

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

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

• IngressSubnet1: 10.0.0.0/24
• IngressSubnet2: 10.0.1.0/24
• IngressSubnet3: 10.0.2.0/24
• ApplicationSubnet1: 10.0.3.0/24
• ApplicationSubnet2: 10.0.4.0/24
• ApplicationSubnet3: 10.0.5.0/24
• DatabaseSubnet1: 10.0.6.0/28
• DatabaseSubnet2: 10.0.6.16/28
• DatabaseSubnet3: 10.0.6.32/28

Each Public Subnet will have a NAT Gateway. Each Private Subnet will have a route to the NAT Gateway in the same availability zone. Each Isolated subnet will not have a route to the internet, but is routeable inside the VPC. The numbers [1-3] will consistently map to availability zones (e.g. IngressSubnet1 and ApplicationSubnet1 will be in the same avialbility zone).

Isolated Subnets provide simplified secure networking principles, but come at an operational complexity. The lack of an internet route means that if you deploy instances in this subnet you will not be able to patch from the internet, this is commonly reffered to as fully baked images. Features such as cfn-signal are also unavailable. Using these subnets for managed services (RDS, Elasticache, Redshift) is a very practical use because the managed services do not incur additional operational overhead.

Many times when you plan to build an application you don't know how many instances of the application you will need and therefore you don't know how much IP space to allocate. For example, you know the application will only have Elastic Loadbalancers in the public subnets and you know you will have 1-3 RDS databases for your data tier, and the rest of the IP space should just be evenly distributed for the application.

import ec2 = require('@aws-cdk/aws-ec2');

const vpc = new ec2.VpcNetwork(this, 'TheVPC', {
  cidr: '10.0.0.0/16',
  natGateways: 1,
  subnetConfiguration: [
    {
      cidrMask: 26,
      name: 'Public',
      subnetType: SubnetType.Public,
    },
    {
      name: 'Application',
      subnetType: SubnetType.Private,
    },
    {
      cidrMask: 27,
      name: 'Database',
      subnetType: SubnetType.Isolated,
    }
  ],
});

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

• PublicSubnet1: 10.0.0.0/26
• PublicSubnet2: 10.0.0.64/26
• PublicSubnet3: 10.0.2.128/26
• DatabaseSubnet1: 10.0.0.192/27
• DatabaseSubnet2: 10.0.0.224/27
• DatabaseSubnet3: 10.0.1.0/27
• ApplicationSubnet1: 10.0.64.0/18
• ApplicationSubnet2: 10.0.128.0/18
• ApplicationSubnet3: 10.0.192.0/18

Any subnet configuration without a cidrMask will be counted up and allocated evenly across the remaining IP space.

Teams may also become cost conscious and be willing to trade availability for cost. For example, in your test environments perhaps you would like the same VPC as production, but instead of 3 NAT Gateways you would like only 1. This will save on the cost, but trade the 3 availability zone to a 1 for all egress traffic. This can be accomplished with a single parameter configuration:

import ec2 = require('@aws-cdk/aws-ec2');

const vpc = new ec2.VpcNetwork(this, 'TheVPC', {
  cidr: '10.0.0.0/16',
  natGateways: 1,
  natGatewayPlacement: {subnetName: 'Public'},
  subnetConfiguration: [
    {
      cidrMask: 26,
      name: 'Public',
      subnetType: SubnetType.Public,
      natGateway: true,
    },
    {
      name: 'Application',
      subnetType: SubnetType.Private,
    },
    {
      cidrMask: 27,
      name: 'Database',
      subnetType: SubnetType.Isolated,
    }
  ],
});

The VpcNetwork above will have the exact same subnet definitions as listed above. However, this time the VPC will have only 1 NAT Gateway and all Application subnets will route to the NAT Gateway.

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:

import ec2 = require('@aws-cdk/aws-ec2');
const vpc = new ec2.VpcNetwork(this, 'TheVPC', {
  cidr: '10.0.0.0/16',
  natGateways: 1,
  subnetConfiguration: [
    {
      cidrMask: 26,
      name: 'Public',
      subnetType: SubnetType.Public,
    },
    {
      cidrMask: 26,
      name: 'Application1',
      subnetType: SubnetType.Private,
    },
    {
      cidrMask: 26,
      name: 'Application2',
      subnetType: SubnetType.Private,
      reserved: true,
    },
    {
      cidrMask: 27,
      name: 'Database',
      subnetType: SubnetType.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. Most importantly, this action would not cause the Database subnet to get renumbered, but rather the IP space that was previously reserved will be used for the subnet provisioned for Application2. The reserved property also takes into consideration the number of availability zones when reserving IP space.

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 using export() and import():

sharing VPCs between stacks

Importing an existing VPC

If your VPC is created outside your CDK app, you can use importFromContext():

importing existing VPCs

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:

const mySecurityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', {
  vpc,
  description: 'Allow ssh access to ec2 instances',
  allowAllOutbound: true   // Can be set to false
});
mySecurityGroup.addIngressRule(new ec2.AnyIPv4(), new ec2.TcpPort(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:

// Allow connections from anywhere
loadBalancer.connections.allowFromAnyIpv4(new ec2.TcpPort(443), 'Allow inbound HTTPS');

// The same, but an explicit IP address
loadBalancer.connections.allowFrom(new ec2.CidrIpv4('1.2.3.4/32'), new ec2.TcpPort(443), 'Allow inbound HTTPS');

// Allow connection between AutoScalingGroups
appFleet.connections.allowTo(dbFleet, new ec2.TcpPort(443), 'App can call database');

Connection Peers

There are various classes that implement the connection peer part:

// Simple connection peers
let peer = new ec2.CidrIp("10.0.0.0/16");
let peer = new ec2.AnyIPv4();
let peer = new ec2.CidrIpv6("::0/0");
let peer = new ec2.AnyIPv6();
let peer = new ec2.PrefixList("pl-12345");
fleet.connections.allowTo(peer, new ec2.TcpPort(443), 'Allow outbound HTTPS');

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

// These automatically create appropriate ingress and egress rules in both security groups
fleet1.connections.allowTo(fleet2, new ec2.TcpPort(80), 'Allow between fleets');

fleet.connections.allowTcpPort(80), 'Allow from load balancer');

Port Ranges

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

new ec2.TcpPort(80)
new ec2.TcpPortRange(60000, 65535)
new ec2.TcpAllPorts()
new ec2.AllConnections()

NOTE: This set is not complete yet; for example, there is no library support for ICMP at the moment. However, you can write your own classes to implement those.

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 allowDefaultPortFrom() and omit the port specifier. If the argument has an associated default port, call allowToDefaultPort().

For example:

// Port implicit in listener
listener.connections.allowDefaultPortFromAnyIpv4('Allow public');

// Port implicit in peer
fleet.connections.allowToDefaultPort(rdsDatabase, 'Fleet can access database');

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.

The latest version of Amazon Linux and Microsoft Windows images are selectable by instantiating one of these classes:

example of creating images

NOTE: The Amazon Linux images selected will be cached in your cdk.json, so that your AutoScalingGroups don't automatically change out from under you when you're making unrelated changes. To update to the latest version of Amazon Linux, remove the cache entry from the context section of your cdk.json.

We will add command-line options to make this step easier in the future.

VPN connections to a VPC

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

const vpc = new ec2.VpcNetwork(stack, 'MyVpc', {
  vpnConnections: {
    dynamic: { // Dynamic routing (BGP)
      ip: '1.2.3.4'
    },
    static: { // Static routing
      ip: '4.5.6.7',
      staticRoutes: [
        '192.168.10.0/24',
        '192.168.20.0/24'
      ]
    }
  }
});

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

const vpc = new ec2.VpcNetwork(stack, 'MyVpc', {
  vpnGateway: true
});

VPN connections can then be added:

vpc.addVpnConnection('Dynamic', {
  ip: '1.2.3.4'
});

Routes will be propagated on the route tables associated with the private subnets.

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

// Across all tunnels in the account/region
const allDataOut = VpnConnection.metricAllTunnelDataOut();

// For a specific vpn connection
const vpnConnection = vpc.addVpnConnection('Dynamic', {
  ip: '1.2.3.4'
});
const state = vpnConnection.metricTunnelState();

Changelog

0.28.0 (2019-04-04)

Bug Fixes

• aws-ecs: use executionRole for event rule target (#2165) (aa6f7bc), closes #2015

• core: remove cdk.Secret (#2068) (b53d04d), closes #2064

• feat(aws-iam): refactor grants, add OrganizationPrincipal (#1623) (1bb8ca9), closes #1623 #236

Code Refactoring

• cdk: introduce SecretValue to represent secrets (#2161) (a3d9f2e)

Features

• codepipeline: move all of the Pipeline Actions to their dedicated package. (#2098) (b314ecf)
• codepipeline: re-factor the CodePipeline Action bind method to take a Role separately from the Pipeline. (#2085) (ffe0046)
• ec2: support reserving IP space in VPCs (#2090) (4819ff4)
• Add python support to cdk init (#2130) (997dbcc)
• ecs: support AWS Cloud Map (service discovery) (#2065) (4864cc8), closes #1554
• lambda: add a newVersion method. (#2099) (6fc179a)
• update CloudFormation resource spec to v2.29.0 (#2170) (ebc490d)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• The secretsmanager.SecretString class has been removed in favor of cdk.SecretValue.secretsManager(id[, options])
• The following prop types have been changed from string to cdk.SecretValue: codepipeline-actions.AlexaSkillDeployAction.clientSecret, codepipeline-actions.AlexaSkillDeployAction.refreshToken, codepipeline-actions.GitHubSourceAction.oauthToken, iam.User.password
• secretsmanager.Secret.stringValue and jsonFieldValue have been removed. Use secretsmanage.Secret.secretValue and secretJsonValue instead.
• secretsmanager.Secret.secretString have been removed. Use cdk.SecretValue.secretsManager() or secretsmanager.Secret.import(..).secretValue.
• The class cdk.Secret has been removed. Use cdk.SecretValue instead.
• The class cdk.DynamicReference is no longer a construct, and it's constructor signature was changed and was renamed cdk.CfnDynamicReference.
• grant(function.role) and grant(project.role) are now grant(function) and grant(role).
• core: Replace use of cdk.Secret with secretsmanager.SecretString (preferred) or ssm.ParameterStoreSecureString.
• codepipeline: this changes the package of all CodePipeline Actions to be aws-codepipeline-actions.
• codepipeline: this moves all classes from the aws-codepipeline-api package to the aws-codepipeline package.
• codepipeline: this changes the CodePipeline Action naming scheme from <service>.Pipeline<Category>Action (s3.PipelineSourceAction) to codepipeline_actions.<Service><Category>Action (codepipeline_actions.S3SourceAction).