terraform-aws-eks/modules/karpenter/README.md

Karpenter Module

Configuration in this directory creates the AWS resources required by Karpenter

Usage

All Resources (Default)

In the following example, the Karpenter module will create:

• An IAM role for use with Pod Identity and a scoped IAM policy for the Karpenter controller
• A Pod Identity association to grant Karpenter controller access provided by the IAM Role
• A Node IAM role that Karpenter will use to create an Instance Profile for the nodes to receive IAM permissions
• An access entry for the Node IAM role to allow nodes to join the cluster
• SQS queue and EventBridge event rules for Karpenter to utilize for spot termination handling, capacity re-balancing, etc.

module "eks" {
  source = "terraform-aws-modules/eks/aws"

  ...
}

module "karpenter" {
  source = "terraform-aws-modules/eks/aws//modules/karpenter"

  cluster_name = module.eks.cluster_name

  # Attach additional IAM policies to the Karpenter node IAM role
  node_iam_role_additional_policies = {
    AmazonSSMManagedInstanceCore = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
  }

  tags = {
    Environment = "dev"
    Terraform   = "true"
  }
}

Re-Use Existing Node IAM Role

In the following example, the Karpenter module will create:

• An IAM role for use with Pod Identity and a scoped IAM policy for the Karpenter controller
• SQS queue and EventBridge event rules for Karpenter to utilize for spot termination handling, capacity re-balancing, etc.

In this scenario, Karpenter will re-use an existing Node IAM role from the EKS managed node group which already has the necessary access entry permissions:

module "eks" {
  source = "terraform-aws-modules/eks"

  # Shown just for connection between cluster and Karpenter sub-module below
  eks_managed_node_groups = {
    initial = {
      instance_types = ["t3.medium"]

      min_size     = 1
      max_size     = 3
      desired_size = 1
    }
  }
  ...
}

module "karpenter" {
  source = "terraform-aws-modules/eks/aws//modules/karpenter"

  cluster_name = module.eks.cluster_name

  create_node_iam_role = false
  node_iam_role_arn    = module.eks.eks_managed_node_groups["initial"].iam_role_arn

  # Since the node group role will already have an access entry
  create_access_entry = false

  tags = {
    Environment = "dev"
    Terraform   = "true"
  }
}

Requirements

Name	Version
terraform	>= 1.3.2
aws	>= 5.95

Providers

Name	Version
aws	>= 5.95

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_event_rule.this	resource
aws_cloudwatch_event_target.this	resource
aws_eks_access_entry.node	resource
aws_eks_pod_identity_association.karpenter	resource
aws_iam_instance_profile.this	resource
aws_iam_policy.controller	resource
aws_iam_role.controller	resource
aws_iam_role.node	resource
aws_iam_role_policy_attachment.controller	resource
aws_iam_role_policy_attachment.controller_additional	resource
aws_iam_role_policy_attachment.node	resource
aws_iam_role_policy_attachment.node_additional	resource
aws_sqs_queue.this	resource
aws_sqs_queue_policy.this	resource
aws_caller_identity.current	data source
aws_iam_policy_document.controller	data source
aws_iam_policy_document.controller_assume_role	data source
aws_iam_policy_document.node_assume_role	data source
aws_iam_policy_document.queue	data source
aws_iam_policy_document.v033	data source
aws_iam_policy_document.v1	data source
aws_partition.current	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
access_entry_type	Type of the access entry. EC2_LINUX, FARGATE_LINUX, or EC2_WINDOWS; defaults to EC2_LINUX	string	"EC2_LINUX"	no
ami_id_ssm_parameter_arns	List of SSM Parameter ARNs that Karpenter controller is allowed read access (for retrieving AMI IDs)	list(string)	[]	no
cluster_ip_family	The IP family used to assign Kubernetes pod and service addresses. Valid values are ipv4 (default) and ipv6. Note: If ipv6 is specified, the AmazonEKS_CNI_IPv6_Policy must exist in the account. This policy is created by the EKS module with create_cni_ipv6_iam_policy = true	string	"ipv4"	no
cluster_name	The name of the EKS cluster	string	""	no
create	Controls if resources should be created (affects nearly all resources)	bool	true	no
create_access_entry	Determines whether an access entry is created for the IAM role used by the node IAM role	bool	true	no
create_iam_role	Determines whether an IAM role is created	bool	true	no
create_instance_profile	Whether to create an IAM instance profile	bool	false	no
create_node_iam_role	Determines whether an IAM role is created or to use an existing IAM role	bool	true	no
create_pod_identity_association	Determines whether to create pod identity association	bool	false	no
enable_irsa	Determines whether to enable support for IAM role for service accounts	bool	false	no
enable_pod_identity	Determines whether to enable support for EKS pod identity	bool	true	no
enable_spot_termination	Determines whether to enable native spot termination handling	bool	true	no
enable_v1_permissions	Determines whether to enable permissions suitable for v1+ (true) or for v0.33.x-v0.37.x (false)	bool	false	no
iam_policy_description	IAM policy description	string	"Karpenter controller IAM policy"	no
iam_policy_name	Name of the IAM policy	string	"KarpenterController"	no
iam_policy_path	Path of the IAM policy	string	"/"	no
iam_policy_statements	A list of IAM policy statements - used for adding specific IAM permissions as needed	any	[]	no
iam_policy_use_name_prefix	Determines whether the name of the IAM policy (iam_policy_name) is used as a prefix	bool	true	no
iam_role_description	IAM role description	string	"Karpenter controller IAM role"	no
iam_role_max_session_duration	Maximum API session duration in seconds between 3600 and 43200	number	null	no
iam_role_name	Name of the IAM role	string	"KarpenterController"	no
iam_role_path	Path of the IAM role	string	"/"	no
iam_role_permissions_boundary_arn	Permissions boundary ARN to use for the IAM role	string	null	no
iam_role_policies	Policies to attach to the IAM role in {'static_name' = 'policy_arn'} format	map(string)	{}	no
iam_role_tags	A map of additional tags to add the the IAM role	map(any)	{}	no
iam_role_use_name_prefix	Determines whether the name of the IAM role (iam_role_name) is used as a prefix	bool	true	no
irsa_assume_role_condition_test	Name of the IAM condition operator to evaluate when assuming the role	string	"StringEquals"	no
irsa_namespace_service_accounts	List of namespace:serviceaccountpairs to use in trust policy for IAM role for service accounts	list(string)	[ "karpenter:karpenter" ]	no
irsa_oidc_provider_arn	OIDC provider arn used in trust policy for IAM role for service accounts	string	""	no
namespace	Namespace to associate with the Karpenter Pod Identity	string	"kube-system"	no
node_iam_role_additional_policies	Additional policies to be added to the IAM role	map(string)	{}	no
node_iam_role_arn	Existing IAM role ARN for the IAM instance profile. Required if create_iam_role is set to false	string	null	no
node_iam_role_attach_cni_policy	Whether to attach the AmazonEKS_CNI_Policy/AmazonEKS_CNI_IPv6_Policy IAM policy to the IAM IAM role. WARNING: If set false the permissions must be assigned to the aws-node DaemonSet pods via another method or nodes will not be able to join the cluster	bool	true	no
node_iam_role_description	Description of the role	string	null	no
node_iam_role_max_session_duration	Maximum API session duration in seconds between 3600 and 43200	number	null	no
node_iam_role_name	Name to use on IAM role created	string	null	no
node_iam_role_path	IAM role path	string	"/"	no
node_iam_role_permissions_boundary	ARN of the policy that is used to set the permissions boundary for the IAM role	string	null	no
node_iam_role_tags	A map of additional tags to add to the IAM role created	map(string)	{}	no
node_iam_role_use_name_prefix	Determines whether the Node IAM role name (node_iam_role_name) is used as a prefix	bool	true	no
queue_kms_data_key_reuse_period_seconds	The length of time, in seconds, for which Amazon SQS can reuse a data key to encrypt or decrypt messages before calling AWS KMS again	number	null	no
queue_kms_master_key_id	The ID of an AWS-managed customer master key (CMK) for Amazon SQS or a custom CMK	string	null	no
queue_managed_sse_enabled	Boolean to enable server-side encryption (SSE) of message content with SQS-owned encryption keys	bool	true	no
queue_name	Name of the SQS queue	string	null	no
rule_name_prefix	Prefix used for all event bridge rules	string	"Karpenter"	no
service_account	Service account to associate with the Karpenter Pod Identity	string	"karpenter"	no
tags	A map of tags to add to all resources	map(string)	{}	no

Outputs

Name	Description
event_rules	Map of the event rules created and their attributes
iam_role_arn	The Amazon Resource Name (ARN) specifying the controller IAM role
iam_role_name	The name of the controller IAM role
iam_role_unique_id	Stable and unique string identifying the controller IAM role
instance_profile_arn	ARN assigned by AWS to the instance profile
instance_profile_id	Instance profile's ID
instance_profile_name	Name of the instance profile
instance_profile_unique	Stable and unique string identifying the IAM instance profile
namespace	Namespace associated with the Karpenter Pod Identity
node_access_entry_arn	Amazon Resource Name (ARN) of the node Access Entry
node_iam_role_arn	The Amazon Resource Name (ARN) specifying the node IAM role
node_iam_role_name	The name of the node IAM role
node_iam_role_unique_id	Stable and unique string identifying the node IAM role
queue_arn	The ARN of the SQS queue
queue_name	The name of the created Amazon SQS queue
queue_url	The URL for the created Amazon SQS queue
service_account	Service Account associated with the Karpenter Pod Identity