README.md

This component deploys Karpenter NodePools to an EKS cluster.

Karpenter is still rapidly evolving. At this time, this component only supports a subset of the features available in Karpenter. Support could be added for additional features as needed.

Not supported:

• Elements of NodePool:
  • template.spec.kubelet
• Elements of NodeClass:
  • subnetSelectorTerms. This component only supports selecting all public or all private subnets of the referenced EKS cluster.
  • securityGroupSelectorTerms. This component only supports selecting the security group of the referenced EKS cluster.
  • amiSelectorTerms. Such terms override the amiFamily setting, which is the only AMI selection supported by this component.
  • instanceStorePolicy
  • associatePublicIPAddress

Tip

👽 Use Atmos with Terraform

Cloud Posse uses atmos to easily orchestrate multiple environments using Terraform.
Works with Github Actions, Atlantis, or Spacelift.

Watch demo of using Atmos with Terraform

Example of running atmos to manage infrastructure from our Quick Start tutorial.

Usage

Stack Level: Regional

If provisioning more than one NodePool, it is best practice to create NodePools that are mutually exclusive or weighted.

Configuration Approaches

This component supports three configuration approaches controlled by the account_map_enabled variable.

Option 1: Direct Input Variables (account_map_enabled: false)

Set account_map_enabled: false and provide the required values via the eks and vpc object variables. This approach is simpler and avoids cross-component dependencies.

Example using direct inputs:

components:
  terraform:
    eks/karpenter-node-pool:
      vars:
        enabled: true
        account_map_enabled: false
        name: "karpenter-node-pool"
        eks:
          eks_cluster_id: "my-cluster"
          eks_cluster_endpoint: "https://XXXXXXXX.gr7.us-west-2.eks.amazonaws.com"
          eks_cluster_certificate_authority_data: "LS0tLS1CRUdJTi..."
          karpenter_iam_role_name: "my-cluster-karpenter"
        vpc:
          private_subnet_ids:
            - "subnet-xxxxxxxxx"
            - "subnet-yyyyyyyyy"
        # ... node_pools configuration

Option 2: Using Atmos !terraform.state (Recommended)

For Atmos users, the recommended approach is to use !terraform.state to dynamically fetch values from other component outputs and pass them as direct input variables. This keeps dependencies explicit in your stack configuration without using internal remote-state modules.

Example using Atmos !terraform.state:

components:
  terraform:
    eks/karpenter-node-pool:
      vars:
        enabled: true
        account_map_enabled: false
        name: "karpenter-node-pool"
        eks:
          eks_cluster_id: !terraform.state eks/cluster eks_cluster_id
          eks_cluster_endpoint: !terraform.state eks/cluster eks_cluster_endpoint
          eks_cluster_certificate_authority_data: !terraform.state eks/cluster eks_cluster_certificate_authority_data
          karpenter_iam_role_name: !terraform.state eks/cluster karpenter_iam_role_name
        vpc:
          private_subnet_ids: !terraform.state vpc private_subnet_ids
        node_pools:
          default:
            name: default
            private_subnets_enabled: true
            # ... rest of node pool configuration

This approach:

• Uses native Atmos functionality for cross-component references
• Makes dependencies explicit and visible in stack configuration
• Does not use internal remote-state modules (cleaner component code)
• Supports referencing components in different stacks with extended syntax

For referencing components in different stacks:

eks:
  eks_cluster_id: !terraform.state eks/cluster <stack> eks_cluster_id

Option 3: Internal Remote State Modules (account_map_enabled: true, default, deprecated)

Warning: The account_map_enabled: true setting and eks_component_name/vpc_component_name variables are deprecated and will be removed in a future version. Please migrate to using !terraform.state (Option 2) or direct input variables (Option 1).

When account_map_enabled is true (the default), the component uses internal CloudPosse remote-state modules to fetch EKS cluster and VPC information. This approach is being phased out in favor of explicit variable passing via !terraform.state which provides better visibility into component dependencies.

Example using CloudPosse remote state:

components:
  terraform:
    eks/karpenter-node-pool:
      settings:
        spacelift:
          workspace_enabled: true
      vars:
        enabled: true
        account_map_enabled: true  # default, can be omitted
        eks_component_name: eks/cluster
        vpc_component_name: vpc
        name: "karpenter-node-pool"
        # https://karpenter.sh/v0.36.0/docs/concepts/nodepools/
        node_pools:
          default:
            name: default
            # Whether to place EC2 instances launched by Karpenter into VPC private subnets. Set it to `false` to use public subnets
            private_subnets_enabled: true
            disruption:
              consolidation_policy: WhenUnderutilized
              consolidate_after: 1h
              max_instance_lifetime: 336h
              budgets:
                # This budget allows 0 disruptions during business hours (from 9am to 5pm) on weekdays
                - schedule: "0 9 * * mon-fri"
                  duration: 8h
                  nodes: "0"
            # The total cpu of the cluster. Maps to spec.limits.cpu in the Karpenter NodeClass
            total_cpu_limit: "100"
            # The total memory of the cluster. Maps to spec.limits.memory in the Karpenter NodeClass
            total_memory_limit: "1000Gi"
            # The total GPU of the cluster. Maps to spec.limits for GPU in the Karpenter NodeClass
            gpu_total_limits:
              "nvidia.com/gpu" = "1"
            # The weight of the node pool. See https://karpenter.sh/docs/concepts/scheduling/#weighted-nodepools
            weight: 50
            # Taints to apply to the nodes in the node pool. See https://karpenter.sh/docs/concepts/nodeclasses/#spectaints
            taints:
              - key: "node.kubernetes.io/unreachable"
                effect: "NoExecute"
                value: "true"
            # Taints to apply to the nodes in the node pool at startup. See https://karpenter.sh/docs/concepts/nodeclasses/#specstartuptaints
            startup_taints:
              - key: "node.kubernetes.io/unreachable"
                effect: "NoExecute"
                value: "true"
            # Metadata options for the node pool. See https://karpenter.sh/docs/concepts/nodeclasses/#specmetadataoptions
            metadata_options:
              httpEndpoint: "enabled" # allows the node to call the AWS metadata service
              httpProtocolIPv6: "disabled"
              httpPutResponseHopLimit: 2
              httpTokens: "required"
            # The AMI used by Karpenter provisioner 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)
            # Bottlerocket, AL2, Ubuntu
            # https://karpenter.sh/v0.18.0/aws/provisioning/#amazon-machine-image-ami-family
            ami_family: AL2
            # Karpenter provisioner block device mappings.
            block_device_mappings:
              - deviceName: /dev/xvda
                ebs:
                  volumeSize: 200Gi
                  volumeType: gp3
                  encrypted: true
                  deleteOnTermination: true
            # Set acceptable (In) and unacceptable (Out) Kubernetes and Karpenter values for node provisioning based on
            # Well-Known Labels and cloud-specific settings. These can include instance types, zones, computer architecture,
            # and capacity type (such as AWS spot or on-demand).
            # See https://karpenter.sh/v0.18.0/provisioner/#specrequirements for more details
            requirements:
              - key: "karpenter.sh/capacity-type"
                operator: "In"
                values:
                  - "on-demand"
                  - "spot"
              - key: "node.kubernetes.io/instance-type"
                operator: "In"
                # See https://aws.amazon.com/ec2/instance-explorer/ and https://aws.amazon.com/ec2/instance-types/
                # Values limited by DenyEC2InstancesWithoutEncryptionInTransit service control policy
                # See https://github.com/cloudposse/terraform-aws-service-control-policies/blob/master/catalog/ec2-policies.yaml
                # Karpenter recommends allowing at least 20 instance types to ensure availability.
                values:
                  - "c5n.2xlarge"
                  - "c5n.xlarge"
                  - "c5n.large"
                  - "c6i.2xlarge"
                  - "c6i.xlarge"
                  - "c6i.large"
                  - "m5n.2xlarge"
                  - "m5n.xlarge"
                  - "m5n.large"
                  - "m5zn.2xlarge"
                  - "m5zn.xlarge"
                  - "m5zn.large"
                  - "m6i.2xlarge"
                  - "m6i.xlarge"
                  - "m6i.large"
                  - "r5n.2xlarge"
                  - "r5n.xlarge"
                  - "r5n.large"
                  - "r6i.2xlarge"
                  - "r6i.xlarge"
                  - "r6i.large"
              - key: "kubernetes.io/arch"
                operator: "In"
                values:
                  - "amd64"

Requirements

Providers

Modules

Resources

Inputs

{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}

object({
    eks_cluster_id                         = optional(string, "")
    eks_cluster_arn                        = optional(string, "")
    eks_cluster_endpoint                   = optional(string, "")
    eks_cluster_certificate_authority_data = optional(string, "")
    eks_cluster_identity_oidc_issuer       = optional(string, "")
    karpenter_iam_role_name                = optional(string, "")
    karpenter_node_role_arn                = optional(string, "")
  })

{
  "eks_cluster_arn": "",
  "eks_cluster_certificate_authority_data": "",
  "eks_cluster_endpoint": "",
  "eks_cluster_id": "",
  "eks_cluster_identity_oidc_issuer": "",
  "karpenter_iam_role_name": "",
  "karpenter_node_role_arn": ""
}

[
  "default"
]

map(object({
    # The name of the Karpenter provisioner. The map key is used if this is not set.
    name = optional(string)
    # Whether to place EC2 instances launched by Karpenter into VPC private subnets. Set it to false to use public subnets.
    private_subnets_enabled = bool
    # The Disruption spec controls how Karpenter scales down the node group.
    # See the example (sadly not the specific spec.disruption documentation) at https://karpenter.sh/docs/concepts/nodepools/ for details
    disruption = optional(object({
      # Describes which types of Nodes Karpenter should consider for consolidation.
      # If using 'WhenUnderutilized', Karpenter will consider all nodes for consolidation and attempt to remove or
      # replace Nodes when it discovers that the Node is underutilized and could be changed to reduce cost.
      # If using WhenEmpty, Karpenter will only consider nodes for consolidation that contain no workload pods.
      consolidation_policy = optional(string, "WhenUnderutilized")

      # The amount of time Karpenter should wait after discovering a consolidation decision (go duration string, s, m, or h).
      # This value can currently (v0.36.0) only be set when the consolidationPolicy is 'WhenEmpty'.
      # You can choose to disable consolidation entirely by setting the string value 'Never' here.
      # Earlier versions of Karpenter called this field ttl_seconds_after_empty.
      consolidate_after = optional(string)

      # The amount of time a Node can live on the cluster before being removed (go duration string, s, m, or h).
      # You can choose to disable expiration entirely by setting the string value 'Never' here.
      # This module sets a default of 336 hours (14 days), while the Karpenter default is 720 hours (30 days).
      # Note that Karpenter calls this field "expiresAfter", and earlier versions called it ttl_seconds_until_expired,
      # but we call it "max_instance_lifetime" to match the corresponding field in EC2 Auto Scaling Groups.
      max_instance_lifetime = optional(string, "336h")

      # Budgets control the the maximum number of NodeClaims owned by this NodePool that can be terminating at once.
      # See https://karpenter.sh/docs/concepts/disruption/#disruption-budgets for details.
      # A percentage is the percentage of the total number of active, ready nodes not being deleted, rounded up.
      # If there are multiple active budgets, Karpenter uses the most restrictive value.
      # If left undefined, this will default to one budget with a value of nodes: 10%.
      # Note that budgets do not prevent or limit involuntary terminations.
      # Example:
      #   On Weekdays during business hours, don't do any deprovisioning.
      #     budgets = {
      #       schedule = "0 9 * * mon-fri"
      #       duration = 8h
      #       nodes    = "0"
      #     }
      budgets = optional(list(object({
        # The schedule specifies when a budget begins being active, using extended cronjob syntax.
        # See https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#schedule-syntax for syntax details.
        # Timezones are not supported. This field is required if Duration is set.
        schedule = optional(string)
        # Duration determines how long a Budget is active after each Scheduled start.
        # If omitted, the budget is always active. This is required if Schedule is set.
        # Must be a whole number of minutes and hours, as cron does not work in seconds,
        # but since Go's duration.String() always adds a "0s" at the end, that is allowed.
        duration = optional(string)
        # The percentage or number of nodes that Karpenter can scale down during the budget.
        nodes = string
        # Reasons can be one of Drifted, Underutilized, or Empty
        # If omitted, it’s assumed that the budget applies to all reasons.
        # See https://karpenter.sh/v1.1/concepts/disruption/#reasons
        reasons = optional(list(string))
      })), [])
    }), {})
    # Karpenter provisioner total CPU limit for all pods running on the EC2 instances launched by Karpenter
    total_cpu_limit = string
    # Karpenter provisioner total memory limit for all pods running on the EC2 instances launched by Karpenter
    total_memory_limit = string
    # Additional resource limits (e.g., GPU, custom resources) to merge into spec.limits. Example: {"nvidia.com/gpu" = "1"}
    gpu_total_limits = optional(map(string), {})
    # Set a weight for this node pool.
    # See https://karpenter.sh/docs/concepts/scheduling/#weighted-nodepools
    weight      = optional(number, 50)
    labels      = optional(map(string))
    annotations = optional(map(string))
    # Karpenter provisioner taints configuration. See https://aws.github.io/aws-eks-best-practices/karpenter/#create-provisioners-that-are-mutually-exclusive for more details
    taints = optional(list(object({
      key    = string
      effect = string
      value  = optional(string)
    })))
    startup_taints = optional(list(object({
      key    = string
      effect = string
      value  = optional(string)
    })))
    # Karpenter node metadata options. See https://karpenter.sh/docs/concepts/nodeclasses/#specmetadataoptions for more details
    metadata_options = optional(object({
      httpEndpoint            = optional(string, "enabled")
      httpProtocolIPv6        = optional(string, "disabled")
      httpPutResponseHopLimit = optional(number, 2)
      # httpTokens can be either "required" or "optional"
      httpTokens = optional(string, "required")
    }), {})
    # Enable detailed monitoring for EC2 instances. See https://karpenter.sh/docs/concepts/nodeclasses/#specdetailedmonitoring
    detailed_monitoring = optional(bool, false)
    # User data script to pass to EC2 instances. See https://karpenter.sh/docs/concepts/nodeclasses/#specuserdata
    user_data = optional(string, null)
    # ami_family dictates the default bootstrapping logic.
    # It is only required if you do not specify amiSelectorTerms.alias
    ami_family = optional(string, null)
    # Selectors for the AMI used by Karpenter provisioner when provisioning nodes.
    # Usually use { alias = "@latest" } but version can be pinned instead of "latest".
    # Based on the ami_selector_terms, Karpenter will automatically query for the appropriate EKS optimized AMI via AWS Systems Manager (SSM)
    ami_selector_terms = list(any)
    # Karpenter nodes block device mappings. Controls the Elastic Block Storage volumes that Karpenter attaches to provisioned nodes.
    # Karpenter uses default block device mappings for the AMI Family specified.
    # For example, the Bottlerocket AMI Family defaults with two block device mappings,
    # and normally you only want to scale /dev/xvdb where Containers and there storage are stored.
    # Most other AMIs only have one device mapping at /dev/xvda.
    # See https://karpenter.sh/docs/concepts/nodeclasses/#specblockdevicemappings for more details
    block_device_mappings = list(object({
      deviceName = string
      ebs = optional(object({
        volumeSize          = string
        volumeType          = string
        deleteOnTermination = optional(bool, true)
        encrypted           = optional(bool, true)
        iops                = optional(number)
        kmsKeyID            = optional(string, "alias/aws/ebs")
        snapshotID          = optional(string)
        throughput          = optional(number)
      }))
    }))
    # Set acceptable (In) and unacceptable (Out) Kubernetes and Karpenter values for node provisioning based on Well-Known Labels and cloud-specific settings. These can include instance types, zones, computer architecture, and capacity type (such as AWS spot or on-demand). See https://karpenter.sh/v0.18.0/provisioner/#specrequirements for more details
    requirements = list(object({
      key      = string
      operator = string
      # Operators like "Exists" and "DoesNotExist" do not require a value
      values = optional(list(string))
    }))
    # Any values for spec.template.spec.kubelet allowed by Karpenter.
    # Not fully specified, because they are subject to change.
    # See:
    #   https://karpenter.sh/docs/concepts/nodepools/#spectemplatespeckubelet
    #   https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/
    kubelet = optional(any, {})
  }))

object({
    private_subnet_ids = optional(list(string), [])
    public_subnet_ids  = optional(list(string), [])
  })

{
  "private_subnet_ids": [],
  "public_subnet_ids": []
}

Outputs

Related Projects

Check out these related projects.

• Cloud Posse Terraform Modules - Our collection of reusable Terraform modules used by our reference architectures.
• Atmos - Atmos is like docker-compose but for your infrastructure

References

For additional context, refer to some of these links.

• https://karpenter.sh -
• https://aws.github.io/aws-eks-best-practices/karpenter -
• https://karpenter.sh/docs/concepts/nodepools -
• https://aws.amazon.com/blogs/aws/introducing-karpenter-an-open-source-high-performance-kubernetes-cluster-autoscaler -
• https://github.com/aws/karpenter -
• https://ec2spotworkshops.com/karpenter.html -
• https://www.eksworkshop.com/docs/autoscaling/compute/karpenter/ -

✨ Contributing

This project is under active development, and we encourage contributions from our community.

Many thanks to our outstanding contributors:

For 🐛 bug reports & feature requests, please use the issue tracker.

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

1. Review our Code of Conduct and Contributor Guidelines.
2. Fork the repo on GitHub
3. Clone the project to your own machine
4. Commit changes to your own branch
5. Push your work back up to your fork
6. Submit a Pull Request so that we can review your changes

NOTE: Be sure to merge the latest changes from "upstream" before making a pull request!

Running Terraform Tests

We use Atmos to streamline how Terraform tests are run. It centralizes configuration and wraps common test workflows with easy-to-use commands.

All tests are located in the test/ folder.

Under the hood, tests are powered by Terratest together with our internal Test Helpers library, providing robust infrastructure validation.

Setup dependencies:

• Install Atmos (installation guide)
• Install Go 1.24+ or newer
• Install Terraform or OpenTofu

To run tests:

• Run all tests:

  atmos test run
  

• Clean up test artifacts:

  atmos test clean
  

• Explore additional test options:

  atmos test --help
  

The configuration for test commands is centrally managed. To review what's being imported, see the atmos.yaml file.

Learn more about our automated testing in our documentation or implementing custom commands with atmos.

🌎 Slack Community

Join our Open Source Community on Slack. It's FREE for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totally sweet infrastructure.

📰 Newsletter

Sign up for our newsletter and join 3,000+ DevOps engineers, CTOs, and founders who get insider access to the latest DevOps trends, so you can always stay in the know. Dropped straight into your Inbox every week — and usually a 5-minute read.

📆 Office Hours

Join us every Wednesday via Zoom for your weekly dose of insider DevOps trends, AWS news and Terraform insights, all sourced from our SweetOps community, plus a live Q&A that you can’t find anywhere else. It's FREE for everyone!

License

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

Trademarks

All other trademarks referenced herein are the property of their respective owners.

Copyright © 2017-2026 Cloud Posse, LLC