Skip to content

Latest commit

 

History

History
894 lines (534 loc) · 28.2 KB

API.md

File metadata and controls

894 lines (534 loc) · 28.2 KB
Raw

API Reference

Constructs

Karpenter

This construct adds Karpenter to an existing EKS cluster following the guide located at: https://karpenter.sh/docs/getting-started/. It creates two IAM roles and then adds and installes Karpenter on the EKS cluster. Additionally, it tags subnets with custom tags that are used for instructing Karpenter where to place the nodes.

Initializers 

import { Karpenter } from 'cdk-karpenter'

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

Methods

Name Description
toString Returns a string representation of this construct.
addProvisioner addProvisioner adds a provisioner manifest to the cluster.
toString 
public toString(): string

Returns a string representation of this construct.

addProvisioner 
public addProvisioner(id: string, provisionerSpecs?: ProvisionerSpecs): void

addProvisioner adds a provisioner manifest to the cluster.

idRequired
  • Type: string

must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character.

provisionerSpecsOptional

spec for the Karpenter Provisioner.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { Karpenter } from 'cdk-karpenter'

Karpenter.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

BlockDeviceMappingsProps

Initializer 

import { BlockDeviceMappingsProps } from 'cdk-karpenter'

const blockDeviceMappingsProps: BlockDeviceMappingsProps = { ... }

Properties

Name Type Description
deviceName string The device name (for example, /dev/sdh or xvdh).
ebs EbsProps No description.
deviceNameRequired 
public readonly deviceName: string;
  • Type: string

The device name (for example, /dev/sdh or xvdh).

ebsOptional 
public readonly ebs: EbsProps;

EbsProps

Parameters used to automatically set up EBS volumes when the instance is launched.

Initializer 

import { EbsProps } from 'cdk-karpenter'

const ebsProps: EbsProps = { ... }

Properties

Name Type Description
deleteOnTermination boolean Indicates whether the EBS volume is deleted on instance termination.
encrypted boolean Indicates whether the volume should be encrypted.
iops number The number of I/O operations per second (IOPS).
kmsKeyId string The identifier of the AWS KMS key to use for Amazon EBS encryption.
snapshotId string The snapshot ID of the volume to use.
throughput number Throughput to provision for a gp3 volume, with a maximum of 1,000 MiB/s.
volumeSize string The size of the volume, in GiBs.
volumeType aws-cdk-lib.aws_ec2.EbsDeviceVolumeType The volume type.
deleteOnTerminationOptional 
public readonly deleteOnTermination: boolean;
  • Type: boolean

Indicates whether the EBS volume is deleted on instance termination.

encryptedOptional 
public readonly encrypted: boolean;
  • Type: boolean

Indicates whether the volume should be encrypted.

iopsOptional 
public readonly iops: number;
  • Type: number

The number of I/O operations per second (IOPS).

For gp3 , io1 , and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.

The following are the supported values for each volume type:

  • gp3 : 3,000-16,000 IOPS
  • io1 : 100-64,000 IOPS
  • io2 : 100-64,000 IOPS

For io1 and io2 volumes, we guarantee 64,000 IOPS only for Instances built on the Nitro System. Other instance families guarantee performance up to 32,000 IOPS.

This parameter is required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS. This parameter is not supported for gp2, st1, sc1, or standard volumes.

kmsKeyIdOptional 
public readonly kmsKeyId: string;
  • Type: string

The identifier of the AWS KMS key to use for Amazon EBS encryption.

If KmsKeyId is specified, the encrypted state must be true. If the encrypted state is true but you do not specify KmsKeyId, your KMS key for EBS is used.

You can specify the KMS key using key ARN. For example, arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab.

snapshotIdOptional 
public readonly snapshotId: string;
  • Type: string

The snapshot ID of the volume to use.

If you specify both SnapshotId and VolumeSize, VolumeSize must be equal or greater than the size of the snapshot.

throughputOptional 
public readonly throughput: number;
  • Type: number

Throughput to provision for a gp3 volume, with a maximum of 1,000 MiB/s.

Valid Range: Minimum value of 125. Maximum value of 1000.

volumeSizeOptional 
public readonly volumeSize: string;
  • Type: string

The size of the volume, in GiBs.

You must specify either a snapshot ID or a volume size. If you specify a snapshot, the default is the snapshot size. You can specify a volume size that is equal to or larger than the snapshot size.

The following are the supported volumes sizes for each volume type:

  • gp2 and gp3 :1-16,384
  • io1 and io2 : 4-16,384
  • st1 and sc1 : 125-16,384
  • standard : 1-1,024
volumeTypeOptional 
public readonly volumeType: EbsDeviceVolumeType;
  • Type: aws-cdk-lib.aws_ec2.EbsDeviceVolumeType

The volume type.

For more information, see Amazon EBS volume types in the Amazon EC2 User Guide. If the volume type is io1 or io2, you must specify the IOPS that the volume supports.

KarpenterProps

Initializer 

import { KarpenterProps } from 'cdk-karpenter'

const karpenterProps: KarpenterProps = { ... }

Properties

Name Type Description
cluster aws-cdk-lib.aws_eks.Cluster The EKS cluster on which Karpenter is going to be installed on.
vpc aws-cdk-lib.aws_ec2.IVpc VPC.
subnets aws-cdk-lib.aws_ec2.ISubnet[] VPC subnets which need to be tagged for Karpenter to find them.
clusterRequired 
public readonly cluster: Cluster;
  • Type: aws-cdk-lib.aws_eks.Cluster

The EKS cluster on which Karpenter is going to be installed on.

vpcRequired 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

VPC.

subnetsOptional 
public readonly subnets: ISubnet[];
  • Type: aws-cdk-lib.aws_ec2.ISubnet[]

VPC subnets which need to be tagged for Karpenter to find them.

If left blank, private VPC subnets will be used and tagged by default.

Limits

Initializer 

import { Limits } from 'cdk-karpenter'

const limits: Limits = { ... }

Properties

Name Type Description
cpu string CPU limits (i.e. 256).
mem string Memory limits (i.e. 1000Gi).
cpuOptional 
public readonly cpu: string;
  • Type: string

CPU limits (i.e. 256).

memOptional 
public readonly mem: string;
  • Type: string

Memory limits (i.e. 1000Gi).

ProviderProps

Initializer 

import { ProviderProps } from 'cdk-karpenter'

const providerProps: ProviderProps = { ... }

Properties

Name Type Description
amiFamily AMIFamily The AMI used when provisioning nodes.
amiSelector {[ key: string ]: string} AMISelector is used to configure custom AMIs for Karpenter to use, where the AMIs are discovered through AWS tags, similar to subnetSelector.
blockDeviceMappings BlockDeviceMappingsProps[] EBS mapping configuration.
tags {[ key: string ]: string} Provisioner level tags.
amiFamilyOptional 
public readonly amiFamily: AMIFamily;

The AMI used when provisioning nodes.

Based on the value set for amiFamily,Karpenter will automatically query for the appropriate EKS optimized AMI via AWS Systems Manager (SSM).

amiSelectorOptional 
public readonly amiSelector: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

AMISelector is used to configure custom AMIs for Karpenter to use, where the AMIs are discovered through AWS tags, similar to subnetSelector.

This field is optional, and Karpenter will use the latest EKS-optimized AMIs if an amiSelector is not specified.

blockDeviceMappingsOptional 
public readonly blockDeviceMappings: BlockDeviceMappingsProps[];

EBS mapping configuration.

tagsOptional 
public readonly tags: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

Provisioner level tags.

Tags will be added to every EC2 instance launched by the provisioner. Provisioner level tags override global Karpenter tags.

ProvisionerReqs

Initializer 

import { ProvisionerReqs } from 'cdk-karpenter'

const provisionerReqs: ProvisionerReqs = { ... }

Properties

Name Type Description
archTypes ArchType[] Architecture type of the node instances.
capacityTypes CapacityType[] Capacity type of the node instances.
instanceTypes aws-cdk-lib.aws_ec2.InstanceType[] Instance types to be used by the Karpenter Provider.
restrictInstanceTypes aws-cdk-lib.aws_ec2.InstanceType[] Instance types to be excluded by the Karpenter Provider.
archTypesRequired 
public readonly archTypes: ArchType[];

Architecture type of the node instances.

capacityTypesOptional 
public readonly capacityTypes: CapacityType[];

Capacity type of the node instances.

instanceTypesOptional 
public readonly instanceTypes: InstanceType[];
  • Type: aws-cdk-lib.aws_ec2.InstanceType[]

Instance types to be used by the Karpenter Provider.

restrictInstanceTypesOptional 
public readonly restrictInstanceTypes: InstanceType[];
  • Type: aws-cdk-lib.aws_ec2.InstanceType[]

Instance types to be excluded by the Karpenter Provider.

ProvisionerSpecs

Initializer 

import { ProvisionerSpecs } from 'cdk-karpenter'

const provisionerSpecs: ProvisionerSpecs = { ... }

Properties

Name Type Description
requirements ProvisionerReqs Requirements that constrain the parameters of provisioned nodes.
consolidation boolean Enables consolidation which attempts to reduce cluster cost by both removing un-needed nodes and down-sizing those that can't be removed.
labels {[ key: string ]: string} Labels are arbitrary key-values that are applied to all nodes.
limits Limits CPU and Memory Limits.
provider ProviderProps AWS cloud provider configuration.
startupTaints Taints[] Provisioned nodes will have these taints, but pods do not need to tolerate these taints to be provisioned by this provisioner.
taints Taints[] Provisioned nodes will have these taints.
ttlSecondsAfterEmpty aws-cdk-lib.Duration Time in seconds in which nodes will scale down due to low utilization.
ttlSecondsUntilExpired aws-cdk-lib.Duration Time in seconds in which nodes will expire and get replaced.
requirementsRequired 
public readonly requirements: ProvisionerReqs;

Requirements that constrain the parameters of provisioned nodes.

These requirements are combined with pod.spec.affinity.nodeAffinity rules.

consolidationOptional 
public readonly consolidation: boolean;
  • Type: boolean

Enables consolidation which attempts to reduce cluster cost by both removing un-needed nodes and down-sizing those that can't be removed.

Mutually exclusive with the ttlSecondsAfterEmpty parameter.

labelsOptional 
public readonly labels: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

Labels are arbitrary key-values that are applied to all nodes.

limitsOptional 
public readonly limits: Limits;

CPU and Memory Limits.

Resource limits constrain the total size of the cluster. Limits prevent Karpenter from creating new instances once the limit is exceeded.

providerOptional 
public readonly provider: ProviderProps;

AWS cloud provider configuration.

startupTaintsOptional 
public readonly startupTaints: Taints[];

Provisioned nodes will have these taints, but pods do not need to tolerate these taints to be provisioned by this provisioner.

These taints are expected to be temporary and some other entity (e.g. a DaemonSet) is responsible for removing the taint after it has finished initializing the node.

taintsOptional 
public readonly taints: Taints[];

Provisioned nodes will have these taints.

Taints may prevent pods from scheduling if they are not tolerated.

ttlSecondsAfterEmptyOptional 
public readonly ttlSecondsAfterEmpty: Duration;
  • Type: aws-cdk-lib.Duration

Time in seconds in which nodes will scale down due to low utilization.

If omitted, the feature is disabled, nodes will never scale down due to low utilization. Mutually exclusive with the consolidation parameter.

ttlSecondsUntilExpiredOptional 
public readonly ttlSecondsUntilExpired: Duration;
  • Type: aws-cdk-lib.Duration

Time in seconds in which nodes will expire and get replaced.

If omitted, the feature is disabled and nodes will never expire. i.e. Duration.days(7)

Taints

Initializer 

import { Taints } from 'cdk-karpenter'

const taints: Taints = { ... }

Properties

Name Type Description
effect string Effect.
key string Key.
operator string Operator.
value string Value.
effectRequired 
public readonly effect: string;
  • Type: string

Effect.

keyRequired 
public readonly key: string;
  • Type: string

Key.

operatorOptional 
public readonly operator: string;
  • Type: string

Operator.

valueOptional 
public readonly value: string;
  • Type: string

Value.

Enums

AMIFamily

Members

Name Description
AL2 Amazon Linux 2 AMI family Note: If a custom launch template is specified, then the AMI value in the launch template is used rather than the amiFamily value.
BOTTLEROCKET Bottlerocket AMI family.
UBUNTU Ubuntu AMI family.
CUSTOM Custom AMI family.
AL2

Amazon Linux 2 AMI family Note: If a custom launch template is specified, then the AMI value in the launch template is used rather than the amiFamily value.

BOTTLEROCKET

Bottlerocket AMI family.

UBUNTU

Ubuntu AMI family.

CUSTOM

Custom AMI family.

ArchType

Members

Name Description
ARM64 ARM based instances.
AMD64 x86 based instances.
ARM64

ARM based instances.

AMD64

x86 based instances.

CapacityType

Members

Name Description
SPOT Spot capacity.
ON_DEMAND On demand capacity.
SPOT

Spot capacity.

ON_DEMAND

On demand capacity.