feat(ec2): network interface definitions for launch templates #34327

watersry · 2025-05-01T13:04:49Z

This PR implements basic functionality for defining network interfaces as part of Launch Template.

I'm just reviving #29875 to try and get those changes merged. All the work was done by @pasiorovuo, I made some modifications to try and address the feedback from his original PR.

Issue # (if applicable)

Fixes #14494

Reason for this change

Current Launch Template L2 is missing the ability to define multiple interfaces, their subnets etc. This functionality is required in advanced scenarios where instances need multiple public IP addresses or need to be multi-homed etc.
Description of changes

Multiple new types have been introduced in packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts. Many of them are just renamed extends of the ec2-generated types. This made sense as the Cloudformation type definition is suitable, but I'm a bit uncertain if this violates the design requirement Do not “leak” the details or types of the CFN layer when defining your construct API.

Main type is NetworkInterface which defines the attributes for the interfaces. Additional changes are in LaunchTemplate constructor to accommodate the new functionality.

README has been updated to include a simple usage example.

Description of how you validated changes

A single test has been added. I have also verified the implementation by creating stacks in different configurations and deployed them. There too many combinations to check them all, so only a subset has been tested, unfortunately.

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

…ations as part of Launch Template definitions

aws-cdk-automation

(This review is outdated)

…unch-templates

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

…unch-templates

aws-cdk-automation · 2025-05-01T20:54:04Z

AWS CodeBuild CI Report

CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
Commit ID: c29affd
Result: SUCCEEDED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

5d · 2025-05-13T21:22:17Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+/**
+ * InterfaceType
+ */
+export enum InterfaceType {


Is there any particular reason why the EFA-only interface type wasn't included?

5d · 2025-05-13T21:32:40Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+ *
+ * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-networkinterface.html
+ */
+export interface Ipv6Add extends CfnLaunchTemplate.Ipv6AddProperty { }


In AWS CDK, interface and class names typically use full, descriptive words rather than abbreviations. The naming Ipv6Add appears to be shortened from what would more conventionally be named Ipv6Address.

5d · 2025-05-13T22:28:54Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+/**
+ * Specifies the parameters for a Launch Template network interface definition.
+ */
+export interface NetworkInterface {


Thanks for contributing. The current approach in this PR is simply taking the CloudFormation (L1) properties and exposing them directly with minimal changes:

The NetworkInterface interface is almost identical to CfnLaunchTemplate.NetworkInterfaceProperty

The mutually exclusive options (like ipv4PrefixCount vs ipv4Prefixes) are carried over without any type safety improvements

It doesn't provide the higher-level abstractions that make L2 constructs easier to use

This approach doesn't leverage TypeScript's type system to prevent configuration errors, which is one of the key benefits of using L2 constructs in CDK. Users could still provide mutually exclusive options and only discover the error at runtime.

A proper L2 implementation would:

Use TypeScript's type system to prevent invalid configurations

Provide more intuitive property names and structures

Add validation logic to catch errors early

Include helper methods for common operations

Abstract away CloudFormation-specific details

ozelalisen · 2025-05-19T09:52:41Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+    if ( props.versionDescription && !Token.isUnresolved(props.versionDescription) && props.versionDescription.length > 255) {
+      throw new ValidationError(`versionDescription must be less than or equal to 255 characters, got ${props.versionDescription.length}`, this );
+    }
+
+    if (
+      props.versionDescription &&
+      !Token.isUnresolved(props.versionDescription) &&
+      props.versionDescription.length > 255
+    ) {
+      throw new ValidationError(`versionDescription must be less than or equal to 255 characters, got ${props.versionDescription.length}`, this );
+    }

    if (props.versionDescription && !Token.isUnresolved(props.versionDescription) && props.versionDescription.length > 255) {
      throw new ValidationError(`versionDescription must be less than or equal to 255 characters, got ${props.versionDescription.length}`, this);


There are three identical validation blocks for versionDescription length. This appears to be a mistake.

ozelalisen · 2025-05-19T09:55:06Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+  /**
+   * efa
+   *
+   * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa.html
+   */
+  EFA = 'efa',
+
+  /**
+   * interface
+   */
+  INTERFACE = 'interface',
+}


The documentation for InterfaceType enum is minimal and doesn't fully explain what each option means. Enhance the documentation to better explain what each interface type represents

ozelalisen · 2025-05-19T09:59:44Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+ *
+ * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-connection-tracking.html#connection-tracking-timeouts
+ */
+export interface ConnectionTrackingSpecification extends CfnLaunchTemplate.ConnectionTrackingSpecificationProperty {}


These interfaces are simply extending CloudFormation types without adding any L2 construct value. We should avoid "leaking" the details or types of the CFN layer when defining construct APIs

ozelalisen · 2025-05-19T10:00:45Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+ * To improve the reliability of network packet delivery, ENA Express reorders network packets on the receiving end by default. However, some UDP-based applications are designed to handle network packets that are out of order to reduce the overhead for packet delivery at the network layer. When ENA Express is enabled, you can specify whether UDP network traffic uses it.
+ */
+export interface EnaSrdSpecification
+  extends CfnLaunchTemplate.EnaSrdSpecificationProperty { }


Same comment as above: leaking CFN layer

ozelalisen · 2025-05-19T10:01:20Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+/**
+ * Specifies a secondary private IPv4 address for a network interface.
+ */
+export interface PrivateIpAdd extends CfnLaunchTemplate.PrivateIpAddProperty { }


Same comment as above: leaking CFN layer

ozelalisen · 2025-05-19T10:02:13Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+  /**
+   * List of subnets to which to place the interface in
+   *
+   * @default No subnets are defined.
+   */
+  readonly subnet?: ISubnet;


The property name subnet is singular but the documentation refers to "List of subnets". This is confusing.

ozelalisen · 2025-05-19T10:05:58Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+   *
+   * Note: If defined, overrides settings `associatePublicIpAddress` and `securityGroup`.
+   *
+   * @default: A single network interface using `associatePublicIpAddress` and `securityGroup`is created


There's a typo in the default documentation - missing space between "securityGroup" and "is".

ozelalisen · 2025-05-19T10:06:45Z

packages/@aws-cdk-testing/framework-integ/test/aws-ec2/test/integ.launch-template.ts

+new ec2.LaunchTemplate(stack, 'LTWithNetworkInterfaces', {
+  networkInterfaces: [
+    { associatePublicIpAddress: false, deviceIndex: 0, deleteOnTermination: true },
+    { associatePublicIpAddress: false, deviceIndex: 1, deleteOnTermination: true },
+  ],
+});
+


The integration test only covers a basic case with minimal properties. It doesn't test more complex scenarios like using security groups, subnets, or other network interface properties.

ozelalisen · 2025-05-19T10:08:31Z

packages/aws-cdk-lib/aws-ec2/README.md

@@ -2479,6 +2479,35 @@ const launchTemplate = new ec2.LaunchTemplate(this, 'LaunchTemplate', {
 });
 ```

+Following demonstrates how to add multiple network interface cards to launch template.


Consider adding a comment explaining the real-world use case this example addresses, such as multi-homed instances or instances with multiple public IPs.

ozelalisen · 2025-05-19T10:14:19Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+        ipv4Prefixes: networkInterface.ipv4Prefixes?.map(p => ({ ipv4Prefix: p })),
+        ipv6Prefixes: networkInterface.ipv6Prefixes?.map(p => ({ ipv6Prefix: p })),


The arrow functions don't use parentheses around the parameter, which is inconsistent with other arrow functions in the file that use parentheses.

vishaalmehrishi · 2025-05-19T12:22:58Z

packages/aws-cdk-lib/aws-ec2/lib/launch-template.ts

+    if ( props.versionDescription && !Token.isUnresolved(props.versionDescription) && props.versionDescription.length > 255) {
+      throw new ValidationError(`versionDescription must be less than or equal to 255 characters, got ${props.versionDescription.length}`, this );
+    }
+
+    if (
+      props.versionDescription &&
+      !Token.isUnresolved(props.versionDescription) &&
+      props.versionDescription.length > 255
+    ) {
+      throw new ValidationError(`versionDescription must be less than or equal to 255 characters, got ${props.versionDescription.length}`, this );


Looks like there is a duplicate check here.

Pasi Orovuo and others added 3 commits April 30, 2025 12:04

Implement basic functionality for defining network interface configur…

5ad5aa2

…ations as part of Launch Template definitions

Add test and test snapshot

3c3d94b

PR feedback

18c396c

github-actions bot added beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK effort/medium Medium work item – several days of effort feature-request A feature should be added or improved. p1 labels May 1, 2025

aws-cdk-automation requested a review from a team May 1, 2025 13:04

aws-cdk-automation previously requested changes May 1, 2025

View reviewed changes

watersry changed the title ~~Feature/network interface definitions for launch templates~~ feat(aws-ec2): network interface definitions for launch templates May 1, 2025

Merge branch 'main' into feature/network-interface-definitions-for-la…

b07cee8

…unch-templates

watersry changed the title ~~feat(aws-ec2): network interface definitions for launch templates~~ feat(ec2): network interface definitions for launch templates May 1, 2025

aws-cdk-automation added the pr/needs-maintainer-review This PR needs a review from a Core Team Member label May 1, 2025

Merge branch 'main' into feature/network-interface-definitions-for-la…

c29affd

…unch-templates

paulhcsun assigned 5d May 13, 2025

5d requested changes May 13, 2025

View reviewed changes

ozelalisen reviewed May 19, 2025

View reviewed changes

vishaalmehrishi reviewed May 19, 2025

View reviewed changes

5d removed their assignment May 31, 2025

github-actions bot mentioned this pull request Jun 1, 2025

Monthly PR metrics report #34601

Open

ozelalisen self-assigned this Jun 4, 2025

		ipv4Prefixes: networkInterface.ipv4Prefixes?.map(p => ({ ipv4Prefix: p })),
		ipv6Prefixes: networkInterface.ipv6Prefixes?.map(p => ({ ipv6Prefix: p })),

feat(ec2): network interface definitions for launch templates #34327

Are you sure you want to change the base?

feat(ec2): network interface definitions for launch templates #34327

Uh oh!

Conversation

watersry commented May 1, 2025

Issue # (if applicable)

Reason for this change

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aws-cdk-automation commented May 1, 2025

AWS CodeBuild CI Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

5d May 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aws-cdk-automation left a comment •

edited

Loading

5d May 13, 2025 •

edited

Loading