CDK NAT ASG Provider

Use this AWS Cloud Development Kit (CDK) library to configure and deploy network address translation (NAT) instances individually within their own auto scaling group (ASG) to improve reliability and availability.

Works with AWS CDK v2.

Problem

Although the NAT gateways offered by AWS have high availability, high bandwidth scalability, and minimal administration needs, they can be too expensive for small scale applications. A cheaper alternative, one that AWS mentions in its documentation but does not recommend, is to configure and manage your own NAT instances. One way of doing this is with the CDK using NatInstanceProvider.

import { aws_ec2 as ec2 } from 'aws-cdk-lib';

// Factory method constructs and configures a `NatInstanceProvider` object
const provider = ec2.NatProvider.instance({
  instanceType: new ec2.InstanceType('t2.micro'),
});

const vpc = new ec2.Vpc(this, 'Vpc', {
  natGatewayProvider: provider,
});

A major downside of this approach is that the created NAT instances will not be automatically replaced if they are stopped for whatever reason.

Solution

To provide better fault tolerance and availability, I implemented a NAT provider called NatAsgProvider that places each created NAT instance in its own ASG.

import { aws_ec2 as ec2 } from 'aws-cdk-lib';
import { NatAsgProvider } from 'cdk-nat-asg-provider';

const provider = new NatAsgProvider({});

const vpc = new ec2.Vpc(this, 'Vpc', {
  natGatewayProvider: provider,
});

Like NatInstanceProvider, NatAsgProvider extends NatProvider.

How it works

The number of NAT instances to create and the placement of those NAT instances is dictated by the configuration of the relevant VPC object using the following configuration properties provided to the VPC constructor:

• natGatewaySubnets
  • Selects the subnets that will have NAT instances
  • By default, all public subnets are selected
• natGateways
  • The number of NAT instances to create
  • By default, one NAT instance per AZ

At a high-level, this is how NatAsgProvider achieves its purpose:

• Enables NAT in the EC2 instances, which are running Amazon Linux 2
• Places each NAT instance in its own ASG, configured by a launch template
• Uses cfn-signal in conjunction with a CreationPolicy and UpdatePolicy to suspend work on the stack until the NAT instance signals successful creation or update, respectively, of its ASG
• Attaches an additional elastic network interface (ENI) to each NAT instance
  • Each of these ENI is assigned an elastic IP (EIP) address
  • Sets the default gateway to be the newly attached ENI

Installation

TypeScript (npm)

npm install cdk-nat-asg-provider

or

yarn install cdk-nat-asg-provider

Python (PyPI)

pip install cdk-nat-asg-provider

Usage

For general usage, check out the API documentation.

Example: Manual testing of NAT configuration

I implemented a test environment similar to the one described in the AWS VPC docs. It allows you to manually check whether instances in private subnets can access the internet through the NAT instances by using the NAT instances as bastion servers.

The implementation is in src/manual.integ.ts. It's worth taking a look if you're confused about how to configure Vpc and NatAsgProvider.

To deploy the manual integration test, execute the sh script scripts/manual-integ-test and use the deploy command:

./scripts/manual-integ-test deploy <ACCOUNT> <AWS_REGION> <KEY_PAIR_NAME> [MAX_AZS]

MAX_AZS is optional.

To destroy the manual integration test, execute the same script with same arguments using the destroy command:

./scripts/manual-integ-test destroy <ACCOUNT> <AWS_REGION> <KEY_PAIR_NAME> [MAX_AZS]

Project configuration via projen

projen synthesizes and maintains project configuration. Most of the configuration files, such as package.json, .gitignore, and those defining Github Actions workflows, are managed by projen and are read-only. To add, remove, or modify configuration files, edit .projenrc.js and then run npx projen. Check out projen's documentation website for more details.

Contributing

Feel free to open issues to report bugs or suggest features. Contributions via pull requests are much appreciated.

License

Released under the Apache 2.0 license.