Skip to content

Latest commit

 

History

History
462 lines (285 loc) · 16.3 KB

API.md

File metadata and controls

462 lines (285 loc) · 16.3 KB
Raw

CDK fck-nat

A CDK construct for deploying NAT Instances using fck-nat. The (f)easible (c)ost (k)onfigurable NAT!

  • Overpaying for AWS Managed NAT Gateways? fck-nat.
  • Want to use NAT instances and stay up-to-date with the latest security patches? fck-nat.
  • Want to reuse your Bastion hosts as a NAT? fck-nat.

fck-nat offers a ready-to-use ARM and x86 based AMIs built on Amazon Linux 2023 which can support up to 5Gbps NAT traffic on a t4g.nano instance. How does that compare to a Managed NAT Gateway?

Hourly rates:

  • Managed NAT Gateway hourly: $0.045
  • t4g.nano hourly: $0.0042

Per GB rates:

  • Managed NAT Gateway per GB: $0.045
  • fck-nat per GB: $0.00

Sitting idle, fck-nat costs 10% of a Managed NAT Gateway. In practice, the savings are even greater.

"But what about AWS' NAT Instance AMI?"

The official AWS supported NAT Instance AMI hasn't been updates since 2018, is still running Amazon Linux 1 which is now EOL, and has no ARM support, meaning it can't be deployed on EC2's most cost effective instance types. fck-nat.

"When would I want to use a Managed NAT Gateway instead of fck-nat?"

AWS limits outgoing internet bandwidth on EC2 instances to 5Gbps. This means that the highest bandwidth that fck-nat can support is 5Gbps. This is enough to cover a very broad set of use cases, but if you need additional bandwidth, you should use Managed NAT Gateway. If AWS were to lift the limit on internet egress bandwidth from EC2, you could cost-effectively operate fck-nat at speeds up to 25Gbps, but you wouldn't need Managed NAT Gateway then would you? fck-nat.

Read more about EC2 bandwidth limits here: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html

API Reference

Structs

FckNatInstanceProps

Properties for a fck-nat instance.

Initializer 

import { FckNatInstanceProps } from 'cdk-fck-nat'

const fckNatInstanceProps: FckNatInstanceProps = { ... }

Properties

Name Type Description
instanceType aws-cdk-lib.aws_ec2.InstanceType Instance type of the fck-nat instance.
cloudWatchConfigParam aws-cdk-lib.aws_ssm.IStringParameter Optionally override the base Cloudwatch metric configuration found at https://fck-nat.dev/develop/features/#metrics.
eipPool string[] A list of EIP allocation IDs which can be attached to NAT instances.
enableCloudWatch boolean Add necessary role permissions and configuration for supplementary CloudWatch metrics.
enableSsm boolean Add necessary role permissions for SSM automatically.
keyName string Name of SSH keypair to grant access to instance.
keyPair aws-cdk-lib.aws_ec2.IKeyPair SSH keypair to attach to instances.
machineImage aws-cdk-lib.aws_ec2.IMachineImage The machine image (AMI) to use.
securityGroup aws-cdk-lib.aws_ec2.ISecurityGroup Security Group for fck-nat instances.
instanceTypeRequired 
public readonly instanceType: InstanceType;
  • Type: aws-cdk-lib.aws_ec2.InstanceType

Instance type of the fck-nat instance.

cloudWatchConfigParamOptional 
public readonly cloudWatchConfigParam: IStringParameter;
  • Type: aws-cdk-lib.aws_ssm.IStringParameter
  • Default: If Cloudwatch metrics are enabled, a default configuration will be used.

Optionally override the base Cloudwatch metric configuration found at https://fck-nat.dev/develop/features/#metrics.

If you wish to override the default parameter name, the default configuration contents are stored on the FckNatInstanceProvider.DEFAULT_CLOUDWATCH_CONFIG constant

eipPoolOptional 
public readonly eipPool: string[];
  • Type: string[]

A list of EIP allocation IDs which can be attached to NAT instances.

The number of allocations supplied must be greater than or equal to the number of egress subnets in your VPC.

enableCloudWatchOptional 
public readonly enableCloudWatch: boolean;
  • Type: boolean
  • Default: Additional Cloudwatch metrics are disabled

Add necessary role permissions and configuration for supplementary CloudWatch metrics.

ENABLING THIS FEATURE WILL INCUR ADDITIONAL COSTS! See https://fck-nat.dev/develop/features/#metrics for more details.

enableSsmOptional 
public readonly enableSsm: boolean;
  • Type: boolean
  • Default: SSM is enabled

Add necessary role permissions for SSM automatically.

keyNameOptional
  • Deprecated: - CDK has deprecated the keyName parameter, use keyPair instead.
public readonly keyName: string;
  • Type: string
  • Default: No SSH access will be possible.

Name of SSH keypair to grant access to instance.

Setting this value will not automatically update security groups, that must be done separately.

keyPairOptional 
public readonly keyPair: IKeyPair;
  • Type: aws-cdk-lib.aws_ec2.IKeyPair
  • Default: No SSH access will be possible.

SSH keypair to attach to instances.

Setting this value will not automatically update security groups, that must be done separately.

machineImageOptional 
public readonly machineImage: IMachineImage;
  • Type: aws-cdk-lib.aws_ec2.IMachineImage
  • Default: Latest fck-nat instance image

The machine image (AMI) to use.

By default, will do an AMI lookup for the latest fck-nat instance image.

If you have a specific AMI ID you want to use, pass a GenericLinuxImage. For example:

FckNatInstanceProvider({
  instanceType: new ec2.InstanceType('t3.micro'),
  machineImage: new LookupMachineImage({
    name: 'fck-nat-al2023-*-arm64-ebs',
    owners: ['568608671756'],
  })
})
securityGroupOptional 
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup
  • Default: A new security group will be created

Security Group for fck-nat instances.

Classes

FckNatInstanceProvider

  • Implements: aws-cdk-lib.aws_ec2.IConnectable

Initializers 

import { FckNatInstanceProvider } from 'cdk-fck-nat'

new FckNatInstanceProvider(props: FckNatInstanceProps)
Name Type Description
props FckNatInstanceProps No description.
propsRequired

Methods

Name Description
configureNat Called by the VPC to configure NAT.
configureSubnet Configures subnet with the gateway.
configureNat 
public configureNat(options: ConfigureNatOptions): void

Called by the VPC to configure NAT.

Don't call this directly, the VPC will call it automatically.

optionsRequired
  • Type: aws-cdk-lib.aws_ec2.ConfigureNatOptions
configureSubnet 
public configureSubnet(subnet: PrivateSubnet): void

Configures subnet with the gateway.

Don't call this directly, the VPC will call it automatically.

subnetRequired
  • Type: aws-cdk-lib.aws_ec2.PrivateSubnet

Static Functions

Name Description
gateway Use NAT Gateways to provide NAT services for your VPC.
instance Use NAT instances to provide NAT services for your VPC.
gateway 
import { FckNatInstanceProvider } from 'cdk-fck-nat'

FckNatInstanceProvider.gateway(props?: NatGatewayProps)

Use NAT Gateways to provide NAT services for your VPC.

NAT gateways are managed by AWS.

https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html

propsOptional
  • Type: aws-cdk-lib.aws_ec2.NatGatewayProps
instance 
import { FckNatInstanceProvider } from 'cdk-fck-nat'

FckNatInstanceProvider.instance(props: NatInstanceProps)

Use NAT instances to provide NAT services for your VPC.

NAT instances are managed by you, but in return allow more configuration.

Be aware that instances created using this provider will not be automatically replaced if they are stopped for any reason. You should implement your own NatProvider based on AutoScaling groups if you need that.

https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html

propsRequired
  • Type: aws-cdk-lib.aws_ec2.NatInstanceProps

Properties

Name Type Description
configuredGateways aws-cdk-lib.aws_ec2.GatewayConfig[] Return list of gateways spawned by the provider.
autoScalingGroups aws-cdk-lib.aws_autoscaling.AutoScalingGroup[] The ASGs (Auto Scaling Groups) managing the NAT instances.
connections aws-cdk-lib.aws_ec2.Connections Manage the Security Groups associated with the NAT instances.
role aws-cdk-lib.aws_iam.Role The instance role attached with the NAT instances.
securityGroup aws-cdk-lib.aws_ec2.ISecurityGroup The Security Group associated with the NAT instances.
configuredGatewaysRequired 
public readonly configuredGateways: GatewayConfig[];
  • Type: aws-cdk-lib.aws_ec2.GatewayConfig[]

Return list of gateways spawned by the provider.

autoScalingGroupsRequired 
public readonly autoScalingGroups: AutoScalingGroup[];
  • Type: aws-cdk-lib.aws_autoscaling.AutoScalingGroup[]

The ASGs (Auto Scaling Groups) managing the NAT instances.

These can be retrieved to get metrics and

connectionsRequired 
public readonly connections: Connections;
  • Type: aws-cdk-lib.aws_ec2.Connections

Manage the Security Groups associated with the NAT instances.

roleRequired 
public readonly role: Role;
  • Type: aws-cdk-lib.aws_iam.Role

The instance role attached with the NAT instances.

securityGroupRequired 
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup

The Security Group associated with the NAT instances.

Constants

Name Type Description
AMI_NAME string The AMI name used internally when calling LookupMachineImage.
AMI_OWNER string The AMI owner used internally when calling LookupMachineImage.
DEFAULT_CLOUDWATCH_CONFIG any The default CloudWatch config used when additional CloudWatch metric reporting is enabled.
AMI_NAMERequired 
public readonly AMI_NAME: string;
  • Type: string

The AMI name used internally when calling LookupMachineImage.

Can be referenced if you wish to do AMI lookups externally.

AMI_OWNERRequired 
public readonly AMI_OWNER: string;
  • Type: string

The AMI owner used internally when calling LookupMachineImage.

Can be referenced if you wish to do AMI lookups externally.

DEFAULT_CLOUDWATCH_CONFIGRequired 
public readonly DEFAULT_CLOUDWATCH_CONFIG: any;
  • Type: any

The default CloudWatch config used when additional CloudWatch metric reporting is enabled.