Skip to content

Latest commit

 

History

History
1000 lines (619 loc) · 31.7 KB

API.md

File metadata and controls

1000 lines (619 loc) · 31.7 KB
Raw

PRs Welcome GitHub npm (scoped) PyPI Nuget Sonatype Nexus (Releases) GitHub Workflow Status (branch) GitHub release (latest SemVer) Gitpod ready-to-code

CDK Vpc

Utility constructs for tagging subnets or creating a cheaper vpc.

Install

TypeScript

npm install @pepperize/cdk-vpc

or

yarn add @pepperize/cdk-vpc

Python

pip install pepperize.cdk-vpc

C# / .Net

dotnet add package Pepperize.CDK.Vpc

Java

<dependency>
  <groupId>com.pepperize</groupId>
  <artifactId>cdk-vpc</artifactId>
  <version>${cdkVpc.version}</version>
</dependency>

Getting Started

  1. Create a new CDK TypeScript App project with projen

    mkdir my-project
cd my-project
git init -b main
npx projen new awscdk-app-ts

  2. Add @pepperize/cdk-vpc to your dependencies in .projenrc.js

    const project = new awscdk.AwsCdkTypeScriptApp({
  //...
  deps: ["@pepperize/cdk-vpc"],
});

  3. Install the dependency

    npx projen

Usage

Create a cheaper Vpc

Use this as a cheaper drop-in replacement to create a vpc with 2 AvailabilityZones and a t3.nano NatInstance.

import { App, Stack } from "aws-cdk-lib";
import { CheapVpc } from "@pepperize/cdk-vpc";

const app = new App();
const stack = new Stack(app, "MyCheapVpcStack");

new CheapVpc(stack, "MyCheapVpc");

Tag your imported subnets

Subnets imported by Vpc.fromLookup wouldn't be tagged by Tags.of automatically. To tag them (or any other imported vpc resource) use:

import { CheapVpc } from "@pepperize/cdk-vpc";
import * as ec2 from "aws-cdk-lib/aws-ec2";

const app = new App();
const stack = new Stack(app, "VpcStack");
const vpc = ec2.Vpc.fromLookup(stack, "VpcLookup", {
  vpcId: "vpc-1234567890",
  region: env.region,
});

new CreateTags(vpcStack, "TagPrivateSubnets", {
  resourceIds: vpc.privateSubnets.map((subnet) => {
    return subnet.subnetId;
  }),
  tags: [
    {
      key: "kubernetes.io/role/internal-elb",
      value: "1",
    },
  ],
});

Contributing

Contributions of all kinds are welcome 🚀 Check out our contributor's guide.

For a quick start, check out a development environment:

git clone git@github.com:pepperize/cdk-vpc
cd cdk-vpc
 # install dependencies
yarn
# build with projen
yarn build

API Reference

Constructs

CheapVpc

Initializers 

import { CheapVpc } from '@pepperize/cdk-vpc'

new CheapVpc(scope: Construct, id: string, props?: VpcProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props aws-cdk-lib.aws_ec2.VpcProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsOptional
  • Type: aws-cdk-lib.aws_ec2.VpcProps

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
addClientVpnEndpoint Adds a new client VPN endpoint to this VPC.
addFlowLog Adds a new flow log to this VPC.
addGatewayEndpoint Adds a new gateway endpoint to this VPC.
addInterfaceEndpoint Adds a new interface endpoint to this VPC.
addVpnConnection Adds a new VPN connection to this VPC.
enableVpnGateway Adds a VPN Gateway to this VPC.
selectSubnets Returns IDs of selected subnets.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
addClientVpnEndpoint 
public addClientVpnEndpoint(id: string, options: ClientVpnEndpointOptions): ClientVpnEndpoint

Adds a new client VPN endpoint to this VPC.

idRequired
  • Type: string
optionsRequired
  • Type: aws-cdk-lib.aws_ec2.ClientVpnEndpointOptions
addFlowLog 
public addFlowLog(id: string, options?: FlowLogOptions): FlowLog

Adds a new flow log to this VPC.

idRequired
  • Type: string
optionsOptional
  • Type: aws-cdk-lib.aws_ec2.FlowLogOptions
addGatewayEndpoint 
public addGatewayEndpoint(id: string, options: GatewayVpcEndpointOptions): GatewayVpcEndpoint

Adds a new gateway endpoint to this VPC.

idRequired
  • Type: string
optionsRequired
  • Type: aws-cdk-lib.aws_ec2.GatewayVpcEndpointOptions
addInterfaceEndpoint 
public addInterfaceEndpoint(id: string, options: InterfaceVpcEndpointOptions): InterfaceVpcEndpoint

Adds a new interface endpoint to this VPC.

idRequired
  • Type: string
optionsRequired
  • Type: aws-cdk-lib.aws_ec2.InterfaceVpcEndpointOptions
addVpnConnection 
public addVpnConnection(id: string, options: VpnConnectionOptions): VpnConnection

Adds a new VPN connection to this VPC.

idRequired
  • Type: string
optionsRequired
  • Type: aws-cdk-lib.aws_ec2.VpnConnectionOptions
enableVpnGateway 
public enableVpnGateway(options: EnableVpnGatewayOptions): void

Adds a VPN Gateway to this VPC.

optionsRequired
  • Type: aws-cdk-lib.aws_ec2.EnableVpnGatewayOptions
selectSubnets 
public selectSubnets(selection?: SubnetSelection): SelectedSubnets

Returns IDs of selected subnets.

selectionOptional
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection

Static Functions

Name Description
isConstruct Checks if x is a construct.
isResource Check whether the given construct is a Resource.
fromLookup Import an existing VPC from by querying the AWS environment this stack is deployed to.
fromVpcAttributes Import a VPC by supplying all attributes directly.
isConstruct 
import { CheapVpc } from '@pepperize/cdk-vpc'

CheapVpc.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

isResource 
import { CheapVpc } from '@pepperize/cdk-vpc'

CheapVpc.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
fromLookup 
import { CheapVpc } from '@pepperize/cdk-vpc'

CheapVpc.fromLookup(scope: Construct, id: string, options: VpcLookupOptions)

Import an existing VPC from by querying the AWS environment this stack is deployed to.

This function only needs to be used to use VPCs not defined in your CDK application. If you are looking to share a VPC between stacks, you can pass the Vpc object between stacks and use it as normal.

Calling this method will lead to a lookup when the CDK CLI is executed. You can therefore not use any values that will only be available at CloudFormation execution time (i.e., Tokens).

The VPC information will be cached in cdk.context.json and the same VPC will be used on future runs. To refresh the lookup, you will have to evict the value from the cache using the cdk context command. See https://docs.aws.amazon.com/cdk/latest/guide/context.html for more information.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
optionsRequired
  • Type: aws-cdk-lib.aws_ec2.VpcLookupOptions
fromVpcAttributes 
import { CheapVpc } from '@pepperize/cdk-vpc'

CheapVpc.fromVpcAttributes(scope: Construct, id: string, attrs: VpcAttributes)

Import a VPC by supplying all attributes directly.

NOTE: using fromVpcAttributes() with deploy-time parameters (like a Fn.importValue() or CfnParameter to represent a list of subnet IDs) sometimes accidentally works. It happens to work for constructs that need a list of subnets (like AutoScalingGroup and eks.Cluster) but it does not work for constructs that need individual subnets (like Instance). See aws/aws-cdk#4118 for more information.

Prefer to use Vpc.fromLookup() instead.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
attrsRequired
  • Type: aws-cdk-lib.aws_ec2.VpcAttributes

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
availabilityZones string[] AZs for this VPC.
dnsHostnamesEnabled boolean Indicates if instances launched in this VPC will have public DNS hostnames.
dnsSupportEnabled boolean Indicates if DNS support is enabled for this VPC.
internetConnectivityEstablished constructs.IDependable Dependencies for internet connectivity.
internetGatewayId string Internet Gateway for the VPC.
isolatedSubnets aws-cdk-lib.aws_ec2.ISubnet[] List of isolated subnets in this VPC.
privateSubnets aws-cdk-lib.aws_ec2.ISubnet[] List of private subnets in this VPC.
publicSubnets aws-cdk-lib.aws_ec2.ISubnet[] List of public subnets in this VPC.
vpcArn string Arn of this VPC.
vpcCidrBlock string CIDR range for this VPC.
vpcCidrBlockAssociations string[] No description.
vpcDefaultNetworkAcl string No description.
vpcDefaultSecurityGroup string No description.
vpcId string Identifier for this VPC.
vpcIpv6CidrBlocks string[] No description.
vpnGatewayId string Returns the id of the VPN Gateway (if enabled).
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

availabilityZonesRequired 
public readonly availabilityZones: string[];
  • Type: string[]

AZs for this VPC.

dnsHostnamesEnabledRequired 
public readonly dnsHostnamesEnabled: boolean;
  • Type: boolean

Indicates if instances launched in this VPC will have public DNS hostnames.

dnsSupportEnabledRequired 
public readonly dnsSupportEnabled: boolean;
  • Type: boolean

Indicates if DNS support is enabled for this VPC.

internetConnectivityEstablishedRequired 
public readonly internetConnectivityEstablished: IDependable;
  • Type: constructs.IDependable

Dependencies for internet connectivity.

internetGatewayIdOptional 
public readonly internetGatewayId: string;
  • Type: string

Internet Gateway for the VPC.

Note that in case the VPC is configured only with ISOLATED subnets, this attribute will be undefined.

isolatedSubnetsRequired 
public readonly isolatedSubnets: ISubnet[];
  • Type: aws-cdk-lib.aws_ec2.ISubnet[]

List of isolated subnets in this VPC.

privateSubnetsRequired 
public readonly privateSubnets: ISubnet[];
  • Type: aws-cdk-lib.aws_ec2.ISubnet[]

List of private subnets in this VPC.

publicSubnetsRequired 
public readonly publicSubnets: ISubnet[];
  • Type: aws-cdk-lib.aws_ec2.ISubnet[]

List of public subnets in this VPC.

vpcArnRequired 
public readonly vpcArn: string;
  • Type: string

Arn of this VPC.

vpcCidrBlockRequired 
public readonly vpcCidrBlock: string;
  • Type: string

CIDR range for this VPC.

vpcCidrBlockAssociationsRequired 
public readonly vpcCidrBlockAssociations: string[];
  • Type: string[]
vpcDefaultNetworkAclRequired 
public readonly vpcDefaultNetworkAcl: string;
  • Type: string
vpcDefaultSecurityGroupRequired 
public readonly vpcDefaultSecurityGroup: string;
  • Type: string
vpcIdRequired 
public readonly vpcId: string;
  • Type: string

Identifier for this VPC.

vpcIpv6CidrBlocksRequired 
public readonly vpcIpv6CidrBlocks: string[];
  • Type: string[]
vpnGatewayIdOptional 
public readonly vpnGatewayId: string;
  • Type: string

Returns the id of the VPN Gateway (if enabled).

Constants

Name Type Description
DEFAULT_CIDR_RANGE string The default CIDR range used when creating VPCs.
DEFAULT_SUBNETS aws-cdk-lib.aws_ec2.SubnetConfiguration[] The default subnet configuration.
DEFAULT_SUBNETS_NO_NAT aws-cdk-lib.aws_ec2.SubnetConfiguration[] The default subnet configuration if natGateways specified to be 0.
DEFAULT_CIDR_RANGERequired 
public readonly DEFAULT_CIDR_RANGE: string;
  • Type: string

The default CIDR range used when creating VPCs.

This can be overridden using VpcProps when creating a VPCNetwork resource. e.g. new VpcResource(this, { cidr: '192.168.0.0./16' })

DEFAULT_SUBNETSRequired 
public readonly DEFAULT_SUBNETS: SubnetConfiguration[];
  • Type: aws-cdk-lib.aws_ec2.SubnetConfiguration[]

The default subnet configuration.

1 Public and 1 Private subnet per AZ evenly split

DEFAULT_SUBNETS_NO_NATRequired 
public readonly DEFAULT_SUBNETS_NO_NAT: SubnetConfiguration[];
  • Type: aws-cdk-lib.aws_ec2.SubnetConfiguration[]

The default subnet configuration if natGateways specified to be 0.

1 Public and 1 Isolated Subnet per AZ evenly split

CreateTags

Initializers 

import { CreateTags } from '@pepperize/cdk-vpc'

new CreateTags(scope: Construct, id: string, props: CreateTagsProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props CreateTagsProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { CreateTags } from '@pepperize/cdk-vpc'

CreateTags.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

Structs

CreateTagsProps

Adds or overwrites only the specified tags for the specified Amazon EC2 resource or resources.

When you specify an existing tag key, the value is overwritten with the new value. Each resource can have a maximum of 50 tags. Each tag consists of a key and optional value. Tag keys must be unique per resource.

https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateTags.html

Initializer 

import { CreateTagsProps } from '@pepperize/cdk-vpc'

const createTagsProps: CreateTagsProps = { ... }

Properties

Name Type Description
resourceIds string[] The IDs of the ec2 resources, separated by spaces.
tags Tag[] The tags.
removalPolicy aws-cdk-lib.RemovalPolicy No description.
resourceIdsRequired 
public readonly resourceIds: string[];
  • Type: string[]

The IDs of the ec2 resources, separated by spaces.

Constraints: Up to 1000 resource IDs. We recommend breaking up this request into smaller batches.

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-resources

tagsRequired 
public readonly tags: Tag[];

The tags.

The value parameter is required, but if you don't want the tag to have a value, specify the parameter with no value, and we set the value to an empty string.

removalPolicyOptional 
public readonly removalPolicy: RemovalPolicy;
  • Type: aws-cdk-lib.RemovalPolicy

Tag

Initializer 

import { Tag } from '@pepperize/cdk-vpc'

const tag: Tag = { ... }

Properties

Name Type Description
key string The key of the tag.
value string The value of the tag.
keyRequired 
public readonly key: string;
  • Type: string

The key of the tag.

Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.

valueRequired 
public readonly value: string;
  • Type: string

The value of the tag.

Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.