terraform-aws-eks/modules/karpenter

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 service accounts (IRSA) with a narrowly scoped IAM policy for the Karpenter controller to utilize
• An IAM role and instance profile for the nodes created by Karpenter to utilize
  • Note: This IAM role ARN will need to be added to the aws-auth configmap for nodes to join the cluster successfully
• An SQS queue and Eventbridge event rules for Karpenter to utilize for spot termination handling, capacity rebalancing, etc.

This setup is great for running Karpenter on EKS Fargate:

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

  # Shown just for connection between cluster and Karpenter sub-module below
  manage_aws_auth_configmap = true
  aws_auth_roles = [
    # We need to add in the Karpenter node IAM role for nodes launched by Karpenter
    {
      rolearn  = module.karpenter.role_arn
      username = "system:node:{{EC2PrivateDNSName}}"
      groups = [
        "system:bootstrappers",
        "system:nodes",
      ]
    },
  ]
  ...
}

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

  cluster_name = module.eks.cluster_name

  irsa_oidc_provider_arn          = module.eks.oidc_provider_arn
  irsa_namespace_service_accounts = ["karpenter:karpenter"]

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

External Node IAM Role (Default)

In the following example, the Karpenter module will create:

• An IAM role for service accounts (IRSA) with a narrowly scoped IAM policy for the Karpenter controller to utilize
• An IAM instance profile for the nodes created by Karpenter to utilize
  • Note: This setup will utilize the existing IAM role created by the EKS Managed Node group which means the role is already populated in the aws-auth configmap and no further updates are required.
• An SQS queue and Eventbridge event rules for Karpenter to utilize for spot termination handling, capacity rebalancing, etc.

In this scenario, Karpenter would run atop the EKS Managed Node group and scale out nodes as needed from there:

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

  irsa_oidc_provider_arn          = module.eks.oidc_provider_arn
  irsa_namespace_service_accounts = ["karpenter:karpenter"]

  create_iam_role = false
  iam_role_arn    = module.eks.eks_managed_node_groups["initial"].iam_role_arn

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

Requirements

Name	Version
terraform	>= 1.0
aws	>= 4.47

Providers

Name	Version
aws	>= 4.47

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_event_rule.this	resource
aws_cloudwatch_event_target.this	resource
aws_iam_instance_profile.this	resource
aws_iam_policy.irsa	resource
aws_iam_role.irsa	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.additional	resource
aws_iam_role_policy_attachment.irsa	resource
aws_iam_role_policy_attachment.irsa_additional	resource
aws_iam_role_policy_attachment.this	resource
aws_sqs_queue.this	resource
aws_sqs_queue_policy.this	resource
aws_caller_identity.current	data source
aws_iam_policy_document.assume_role	data source
aws_iam_policy_document.irsa	data source
aws_iam_policy_document.irsa_assume_role	data source
aws_iam_policy_document.queue	data source
aws_partition.current	data source

Inputs

Name	Description	Type	Default	Required
cluster_ip_family	The IP family used to assign Kubernetes pod and service addresses. Valid values are ipv4 (default) and ipv6	string	null	no
cluster_name	The name of the EKS cluster	string	""	no
create	Determines whether to create EKS managed node group or not	bool	true	no
create_iam_role	Determines whether an IAM role is created or to use an existing IAM role	bool	true	no
create_instance_profile	Whether to create an IAM instance profile	bool	true	no
create_irsa	Determines whether an IAM role for service accounts is created	bool	true	no
enable_spot_termination	Determines whether to enable native spot termination handling	bool	true	no
iam_role_additional_policies	Additional policies to be added to the IAM role	list(string)	[]	no
iam_role_arn	Existing IAM role ARN for the IAM instance profile. Required if create_iam_role is set to false	string	null	no
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
iam_role_description	Description of the role	string	null	no
iam_role_max_session_duration	Maximum API session duration in seconds between 3600 and 43200	number	null	no
iam_role_name	Name to use on IAM role created	string	null	no
iam_role_path	IAM role path	string	"/"	no
iam_role_permissions_boundary	ARN of the policy that is used to set the permissions boundary for the IAM role	string	null	no
iam_role_tags	A map of additional tags to add to the IAM role created	map(string)	{}	no
iam_role_use_name_prefix	Determines whether the IAM role name (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_description	IAM role for service accounts description	string	"Karpenter IAM role for service account"	no
irsa_max_session_duration	Maximum API session duration in seconds between 3600 and 43200	number	null	no
irsa_name	Name of IAM role for service accounts	string	null	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
irsa_path	Path of IAM role for service accounts	string	"/"	no
irsa_permissions_boundary_arn	Permissions boundary ARN to use for IAM role for service accounts	string	null	no
irsa_policy_name	Name of IAM policy for service accounts	string	null	no
irsa_ssm_parameter_arns	List of SSM Parameter ARNs that contain AMI IDs launched by Karpenter	list(string)	[ "arn:aws:ssm:::parameter/aws/service/*" ]	no
irsa_subnet_account_id	Account ID of where the subnets Karpenter will utilize resides. Used when subnets are shared from another account	string	""	no
irsa_tag_key	Tag key ({key = value}) applied to resources launched by Karpenter through the Karpenter provisioner	string	"karpenter.sh/discovery"	no
irsa_tag_values	Tag values ({key = value}) applied to resources launched by Karpenter through the Karpenter provisioner. Defaults to cluster name when not set.	list(string)	null	no
irsa_tags	A map of additional tags to add the the IAM role for service accounts	map(any)	{}	no
irsa_use_name_prefix	Determines whether the IAM role for service accounts name (irsa_name) is used as a prefix	bool	true	no
policies	Policies to attach to the IAM role in {'static_name' = 'policy_arn'} format	map(string)	{}	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
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
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
irsa_arn	The Amazon Resource Name (ARN) specifying the IAM role for service accounts
irsa_name	The name of the IAM role for service accounts
irsa_unique_id	Stable and unique string identifying the IAM role for service accounts
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
role_arn	The Amazon Resource Name (ARN) specifying the IAM role
role_name	The name of the IAM role
role_unique_id	Stable and unique string identifying the IAM role