EC2NodeClass is the Schema for the EC2NodeClass API
Last changed in Karpenter v1.15.0
APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
EC2NodeClassSpec is the top level specification for the AWS Karpenter Provider. This will contain configuration necessary to launch instances in AWS.
AMIFamily dictates the UserData format and default BlockDeviceMappings used when generating launch templates. This field is optional when using an alias amiSelectorTerm, and the value will be inferred from the alias' family. When an alias is specified, this field may only be set to its corresponding family or 'Custom'. If no alias is specified, this field is required. NOTE: We ignore the AMIFamily for hashing here because we hash the AMIFamily dynamically by using the alias using the AMIFamily() helper function
AMISelectorTerms is a list of or ami selector terms. The terms are ORed.
Alias specifies which EKS optimized AMI to select. Each alias consists of a family and an AMI version, specified as "family@version". Valid families include: al2, al2023, bottlerocket, windows2019, windows2022, windows2025. The version can either be pinned to a specific AMI release, with that AMIs version format (ex: "al2023@v20240625" or "bottlerocket@v1.10.0"). The version can also be set to "latest" for any family. Setting the version to latest will result in drift when a new AMI is released. This is **not** recommended for production environments. Note: The Windows families do **not** support version pinning, and only latest may be used.
ID is the ami id in EC2
Name is the ami name in EC2. This value is the name field, which is different from the name tag.
Owner is the owner for the ami. You can specify a combination of AWS account IDs, "self", "amazon", and "aws-marketplace"
SSMParameter is the name (or ARN) of the SSM parameter containing the Image ID.
Tags is a map of key/value tags used to select amis. Specifying '*' for a value selects all values for a given tag key.
AssociatePublicIPAddress controls if public IP addresses are assigned to instances that are launched with the nodeclass.
BlockDeviceMappings to be applied to provisioned nodes.
The device name (for example, /dev/sdh or xvdh).
EBS contains parameters used to automatically set up EBS volumes when an instance is launched.
DeleteOnTermination indicates whether the EBS volume is deleted on instance termination.
Encrypted indicates whether the EBS volume is encrypted. Encrypted volumes can only be attached to instances that support Amazon EBS encryption. If you are creating a volume from a snapshot, you can't specify an encryption value.
IOPS is 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 (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances). Other instance families guarantee performance up to 32,000 IOPS. This parameter is supported for io1, io2, and gp3 volumes only. This parameter is not supported for gp2, st1, sc1, or standard volumes.
Identifier (key ID, key alias, key ARN, or alias ARN) of the customer managed KMS key to use for EBS encryption.
SnapshotID is the ID of an EBS snapshot
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.
VolumeInitializationRate specifies the Amazon EBS Provisioned Rate for Volume Initialization, in MiB/s, at which to download the snapshot blocks from Amazon S3 to the volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation. Only allowed if SnapshotID is set. Valid Range: Minimum value of 100. Maximum value of 300.
VolumeSize in `Gi`, `G`, `Ti`, or `T`. You must specify either a snapshot ID or a volume 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
VolumeType of the block device. For more information, see Amazon EBS volume types (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html) in the Amazon Elastic Compute Cloud User Guide.
RootVolume is a flag indicating if this device is mounted as kubelet root dir. You can configure at most one root volume in BlockDeviceMappings.
CapacityReservationSelectorTerms is a list of capacity reservation selector terms. Each term is ORed together to determine the set of eligible capacity reservations.
ID is the capacity reservation id in EC2
InstanceMatchCriteria specifies how instances are matched to capacity reservations.
Owner is the owner id for the ami.
Tags is a map of key/value tags used to select capacity reservations. Specifying '*' for a value selects all values for a given tag key.
ConnectionTracking configures idle connection tracking timeouts for ENIs Karpenter provisions in the launch template. EFA-only interfaces are excluded. See ConnectionTracking.
TCPEstablishedTimeout is the timeout (in seconds) for idle TCP connections in an established state. Value must be between 60 and 432,000 (5 days). If unset, EC2 applies its default which is 350 seconds for Nitro v6 instance types (excluding P6e-GB200) and 432,000 seconds for other instance types.
UDPStreamTimeout is the timeout (in seconds) for idle UDP "stream" flows that have seen more than one request-response transaction. Value must be between 60 and 180. If unset, EC2 applies its default of 180 seconds.
UDPTimeout is the timeout (in seconds) for idle UDP flows that have seen traffic only in a single direction or a single request-response transaction. Value must be between 30 and 60. If unset, EC2 applies its default of 30 seconds.
Context is a Reserved field in EC2 APIs https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateFleet.html
CPUOptions defines the CPU options for the instance.
NestedVirtualization enables or disables nested virtualization on the instance. When enabled, Karpenter filters instance types to only those reporting "nested-virtualization" in ProcessorInfo.SupportedFeatures from DescribeInstanceTypes.
DetailedMonitoring controls if detailed monitoring is enabled for instances that are launched
EnclaveOptions specifies whether the instance is enabled for Amazon Web Services Nitro Enclaves. When enabled, instance types are restricted to those that support Nitro Enclaves. When enclaveOptions is omitted or enabled is false, Nitro Enclaves are disabled. When enclaveOptions is specified, enabled is required.
Enabled indicates whether the instance is enabled for Amazon Web Services Nitro Enclaves.
InstanceProfile is the AWS entity that instances use. This field is mutually exclusive from role. The instance profile should already have a role assigned to it that Karpenter has PassRole permission on for instance launch using this instanceProfile to succeed.
InstanceStorePolicy specifies how to handle instance-store disks.
IPPrefixCount sets the number of IPv4 prefixes to be automatically assigned to the network interface.
Kubelet configures the kubelet on provisioned nodes. Any field of the upstream KubeletConfiguration for the Kubernetes version Karpenter was built against may be set; see the k8s.io/kubelet version in go.mod for the exact set. Karpenter reads the fields relevant to scheduling (maxPods, podsPerCore, kubeReserved, systemReserved, evictionHard) and passes all others through to UserData unchanged. Field names and types are validated by Karpenter, which reports a rejected configuration on status.conditions as ValidationSucceeded=False rather than failing the apply.
MetadataOptions for the generated launch template of provisioned nodes. This specifies the exposure of the Instance Metadata Service to provisioned EC2 nodes. For more information, see Instance Metadata and User Data (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) in the Amazon Elastic Compute Cloud User Guide. Refer to recommended, security best practices (https://aws.github.io/aws-eks-best-practices/security/docs/iam/#restrict-access-to-the-instance-profile-assigned-to-the-worker-node) for limiting exposure of Instance Metadata and User Data to pods. If omitted, defaults to httpEndpoint enabled, with httpProtocolIPv6 disabled, with httpPutResponseLimit of 1, and with httpTokens required.
HTTPEndpoint enables or disables the HTTP metadata endpoint on provisioned nodes. If metadata options is non-nil, but this parameter is not specified, the default state is "enabled". If you specify a value of "disabled", instance metadata will not be accessible on the node.
HTTPProtocolIPv6 enables or disables the IPv6 endpoint for the instance metadata service on provisioned nodes. If metadata options is non-nil, but this parameter is not specified, the default state is "disabled".
HTTPPutResponseHopLimit is the desired HTTP PUT response hop limit for instance metadata requests. The larger the number, the further instance metadata requests can travel. Possible values are integers from 1 to 64. If metadata options is non-nil, but this parameter is not specified, the default value is 1.
HTTPTokens determines the state of token usage for instance metadata requests. If metadata options is non-nil, but this parameter is not specified, the default state is "required". If the state is optional, one can choose to retrieve instance metadata with or without a signed token header on the request. If one retrieves the IAM role credentials without a token, the version 1.0 role credentials are returned. If one retrieves the IAM role credentials using a valid signed token, the version 2.0 role credentials are returned. If the state is "required", one must send a signed token header with any instance metadata retrieval requests. In this state, retrieving the IAM role credentials always returns the version 2.0 credentials; the version 1.0 credentials are not available.
NetworkInterfaces specifies the network interface configurations to be attached to provisioned instances.
DeviceIndex is the device index for the network interface attachment.
InterfaceType is the type of network interface. Valid values are "interface" and "efa-only".
NetworkCardIndex is the index of the network card to attach the interface to.
PlacementGroupSelector defines the name or the id of the placement to resolve with the nodeclass.
ID is the placement group id in EC2
Name is the placement group name in EC2
Role is the AWS identity that nodes use. This field is mutually exclusive from instanceProfile.
SecurityGroupSelectorTerms is a list of security group selector terms. The terms are ORed.
ID is the security group id in EC2
Name is the security group name in EC2. This value is the name field, which is different from the name tag.
Tags is a map of key/value tags used to select security groups. Specifying '*' for a value selects all values for a given tag key.
SubnetSelectorTerms is a list of subnet selector terms. The terms are ORed.
ID is the subnet id in EC2
Tags is a map of key/value tags used to select subnets Specifying '*' for a value selects all values for a given tag key.
Tags to be applied on ec2 resources like instances and launch templates.
UserData to be applied to the provisioned nodes. It must be in the appropriate format based on the AMIFamily in use. Karpenter will merge certain fields into this UserData to ensure nodes are being provisioned with the correct configuration.
EC2NodeClassStatus contains the resolved state of the EC2NodeClass
AMI contains the current AMI values that are available to the cluster under the AMI selectors.
Deprecation status of the AMI
ID of the AMI
Name of the AMI
Requirements of the AMI to be utilized on an instance type
The label key that the selector applies to.
Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch.
CapacityReservations contains the current capacity reservation values that are available to this NodeClass under the CapacityReservation selectors.
The availability zone the capacity reservation is available in.
The time at which the capacity reservation expires. Once expired, the reserved capacity is released and Karpenter will no longer be able to launch instances into that reservation.
The id for the capacity reservation.
Indicates the type of instance launches the capacity reservation accepts.
The instance type for the capacity reservation.
Indicates whether this capacity reservation is interruptible
The ID of the AWS account that owns the capacity reservation.
The type of capacity reservation.
The state of the capacity reservation. A capacity reservation is considered to be expiring if it is within the EC2 reclaimation window. Only capacity-block reservations may be in this state.
Conditions contains signals for health and readiness
lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
message is a human readable message indicating details about the transition. This may be an empty string.
observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
status of the condition, one of True, False, Unknown.
type of condition in CamelCase or in foo.example.com/CamelCase.
InstanceProfile contains the resolved instance profile for the role
SecurityGroups contains the current security group values that are available to the cluster under the SecurityGroups selectors.
ID of the security group
Name of the security group
Subnets contains the current subnet values that are available to the cluster under the subnet selectors.
ID of the subnet
The associated availability zone
The associated availability zone ID
Source: karpenter.k8s.aws_ec2nodeclasses.yaml
Changes to EC2NodeClass (karpenter.k8s.aws/v1) in each Karpenter version, compared to the version before it.
1 property has been added
12 properties have been removed
1 property has changed type
1 property has changed the description
Released · View EC2NodeClass in v1.15.0
2 properties have been added
Released · View EC2NodeClass in v1.13.0
2 properties have been added
Released · View EC2NodeClass in v1.11.0
1 property has been added
Released · View EC2NodeClass in v1.10.0
1 property has changed the description
Released · View EC2NodeClass in v1.9.0
2 properties have been added
Released · View EC2NodeClass in v1.8.0
1 property has changed the description
Released · View EC2NodeClass in v1.7.0
2 properties have been added
Released · View EC2NodeClass in v1.6.0
1 property has been added
Released · View EC2NodeClass in v1.5.0
1 property has been added
1 property has changed the description
Released · View EC2NodeClass in v1.4.0
2 properties have been added
2 properties have changed the description
Released · View EC2NodeClass in v1.3.0
1 property has been added
4 properties have changed the description
Released · View EC2NodeClass in v1.1.1
6 properties have changed the description
Released · View EC2NodeClass in v1.0.2
6 properties have changed the description
Released · View EC2NodeClass in v1.0.0
6 properties have changed the description
Released · View EC2NodeClass in v0.37.3
6 properties have changed the description
Released · View EC2NodeClass in v0.36.6
6 properties have changed the description
Released · View EC2NodeClass in v0.35.9
6 properties have changed the description
Released · View EC2NodeClass in v0.34.10
6 properties have changed the description
Released · View EC2NodeClass in v0.33.9
EC2NodeClass was first seen on this version of Karpenter
Released · View EC2NodeClass in v0.33.6
A ready-to-use manifest of EC2NodeClass to start from.
apiVersion: karpenter.k8s.aws/v1 kind: EC2NodeClass metadata: name: private spec: metadataOptions: # Set the hop limit to 2 to allow containers to contact the Instance Metadata # Service (IMDS) https://github.com/kubernetes-sigs/karpenter/issues/1769 httpPutResponseHopLimit: 2 blockDeviceMappings: # Use encrypted, gp3, 50Gi root volumes - deviceName: /dev/xvda ebs: volumeSize: 50Gi volumeType: gp3 encrypted: true # Required: Use an specific Amazon Linux 2023 AMI release compatible with the instance type # https://github.com/awslabs/amazon-eks-ami/releases amiFamily: AL2023 amiSelectorTerms: - alias: al2023@v20250317 # IAM role name to use as the node role role: KarpenterNode # Don't associate a public IP address with the node, even if the subnet defaults to doing so associatePublicIPAddress: false subnetSelectorTerms: # Required: Launch nodes in subnets with the following tags - tags: karpenter.sh/discovery: cluster-private karpenter.sh/discovery/private: "true" securityGroupSelectorTerms: # Required: Launch nodes in security groups with the following tags - tags: karpenter.sh/discovery: cluster-worke tags: # Propagate AWS tags to the EC2 instances launched using this class karpenter.sh/discovery: cluster-private
kubespec.dev