Amazon EKS 0.72.3Last updated in version 0.72.1

EKS Cluster Managed Workers Module

This module provisions EKS Managed Node Groups, as opposed to self managed ASGs. See the eks-cluster-workers module for a module to provision self managed worker groups.

This Terraform module launches worker nodes using EKS Managed Node Groups that you can use to run Kubernetes Pods and Deployments.

This module is responsible for the EKS Worker Nodes in the EKS cluster topology. You must launch a control plane in order for the worker nodes to function. See the eks-cluster-control-plane module for managing an EKS control plane.

Differences with self managed workers

Managed Node Groups is a feature of EKS where you rely on EKS to manage the lifecycle of your worker nodes. This includes:

Automatic IAM role registration
Upgrades to platform versions and AMIs
Scaling up and down
Security Groups

Instead of manually managing Auto Scaling Groups and AMIs, you rely on EKS to manage those for you. This allows you to offload concerns such as upgrading and graceful scale out of your worker pools to AWS so that you don't have to manage them using tools like kubergrunt.

Which flavor of worker pools to use depends on your infrastructure needs. Note that you can have both managed and self managed worker pools on a single EKS cluster, should you find the need for additional customizations.

Here is a list of additional tradeoffs to consider between the two flavors:

	Managed Node Groups	Self Managed Node Groups
Graceful Scale in and Scale out	Supported automatically without needing additional tooling.	Requires specialized tooling (e.g `kubergrunt`) to implement.
Boot scripts	Not supported.	Supported via user-data scripts in the ASG configuration.
OS	Only supports Amazon Linux.	Supports any arbitrary AMI, including Windows.
SSH access	Only supports EC2 key pair, and restrictions by Security Group ID.	Supports any PAM customized either in the AMI or boot scripts. Also supports any arbitrary security group configuration.
EBS Volumes	Only supports adjusting the root EBS volume.	Supports any EBS volume configuration, including attaching additional block devices.
ELB	Supports automatic configuration via Kubernetes mechanisms. There is no way to manually register target groups to the ASG.	Supports both automatic configuration by Kubernetes, and manual configuration with target group registration.
GPU support	Supported via the GPU compatible EKS Optimized AMI.	Supported via a GPU compatible AMI.

How do I enable cluster auto-scaling?

This module will not automatically scale in response to resource usage by default, the autoscaling_group_configurations.*.max_size option is only used to give room for new instances during rolling updates. To enable auto-scaling in response to resource utilization, deploy the Kubernetes Cluster Autoscaler module.

Note that the cluster autoscaler supports ASGs that manage nodes in a single availability zone or ASGs that manage nodes in multiple availability zones. However, there is a caveat:

If you intend to use EBS volumes, you need to make sure that the autoscaler scales the correct ASG for pods that are localized to the availability zone. This is because EBS volumes are local to the availability zone. You need to carefully provision the managed node groups such that you have one group per AZ if you wish to use the cluster autoscaler in this case, which you can do by ensuring that the subnet_ids in each autoscaling_group_configurations input map entry come from the same AZ.
You can certainly use a single ASG that spans multiple AZs if you don't intend to use EBS volumes.
AWS now supports EFS as a persistent storage solution with EKS. This can be used with ASGs that span a single or multiple AZs.

Refer to the Kubernetes Autoscaler documentation for more details.

How do I roll out an update to the instances?

Due to the way managed node groups work in Terraform, currently there is no way to rotate the instances without downtime when using terraform. Changes to the AMI or instance type will automatically cause the node group to be replaced. Additionally, the current resource does not support a mechanism to create the new group before destroying (the resource does not support name_prefix, and you can't create a new node group with the same name). As such, a naive update to the properties of the node group will likely lead to a period of reduced capacity as terraform replaces the groups.

To avoid downtime when updating your node groups, use a blue-green deployment:

Provision a new node group with the updated, desired properties. You can do this by adding a new entry into the input map var.node_group_configurations.
Apply the updated config using terraform apply to create the replacement node group.
Once the new node group scales up, remove the old node group configuration from the input map.
Apply the updated config using terraform apply to remove the old node group. The managed node group will gracefully scale down the nodes in Kubernetes (honoring PodDisruptionBudgets) before terminating them. During this process, the workloads will reschedule to the new nodes.

How do I perform a blue green release to roll out new versions of the module?

Gruntwork tries to provide migration paths that avoid downtime when rolling out new versions of the module. These are usually implemented as feature flags, or a list of state migration calls that allow you to avoid a resource recreation. However, it is not always possible to avoid a resource recreation with Managed Node Groups.

When it is not possible to avoid resource recreation, you can perform a blue-green release of the entire worker pool. In this deployment model, you can deploy a new worker pool using the updated module version, and migrate the Kubernetes workload to the new cluster prior to spinning down the old one.

The following are the steps you can take to perform a blue-green release for this module:

Add a new module block that calls the eks-cluster-managed-workers module using the new version, leaving the old module block with the old version untouched. E.g.,

# old version
module "workers" {
  source = "git::git@github.com:gruntwork-io/terraform-aws-eks.git//modules/eks-cluster-managed-workers?ref=v0.37.2"
  # other args omitted for brevity
}

# new version
module "workers_next_version" {
  source = "git::git@github.com:gruntwork-io/terraform-aws-eks.git//modules/eks-cluster-managed-workers?ref=v0.38.0"
  # other args omitted for brevity
}

This will spin up the new worker pool on the updated version in parallel with the old workers, without touching the old ones.

Make sure to add the IAM role for the new worker set to the aws-auth ConfigMap so that the workers can authenticate to the Kubernetes API. This can be done by adding the eks_worker_iam_role_arn output of the new module block to the eks_worker_iam_role_arns input list for the module call to eks-k8s-role-mapping.
Verify that the new workers are registered to the Kubernetes cluster by checking the output of kubectl get nodes. If the nodes are not in the list, or don't reach the Ready state, you will want to troubleshoot by introspecting the system logs.
Once the new workers are up and registered to the Kubernetes Control Plane, you can run kubectl cordon and kubectl drain on each instance in the old ASG to transition the workload over to the new worker pool. kubergrunt provides a helper command to make it easier to run this:
```
kubergrunt eks drain --asg-name my-asg-a --asg-name my-asg-b --asg-name my-asg-c --region us-east-2
```
This command will cordon and drain all the nodes associated with the given ASGs.
Once the workload is transitioned, you can tear down the old worker pool by dropping the old module block and running terraform apply.

Sample Usage

Terraform
Terragrunt

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S EKS-CLUSTER-MANAGED-WORKERS MODULE
# ------------------------------------------------------------------------------------------------------

module "eks_cluster_managed_workers" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-eks.git//modules/eks-cluster-managed-workers?ref=v0.72.3"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The name of the EKS cluster (e.g. eks-prod). This is used to namespace all
  # the resources created by these templates.
  cluster_name = <string>

  # Configure one or more Node Groups to manage the EC2 instances in this
  # cluster.
  node_group_configurations = <any>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # List of Security Group IDs to allow SSH access from. Only used if
  # var.cluster_instance_keypair_name is set. Set to null to allow access from
  # all locations.
  allow_ssh_from_security_groups = []

  # Where to get the AMI from. Can be 'auto', 'launch_template', or
  # 'eks_nodegroup'. WARNING there are limitation on what the value is, check
  # the documentation for more information
  # https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#mng-ami-id-conditions
  ami_source = "auto"

  # The AWS partition used for default AWS Resources.
  aws_partition = "aws"

  # The EC2 Keypair name used to SSH into the EKS Cluster's EC2 Instances. To
  # disable keypairs, pass in blank.
  cluster_instance_keypair_name = null

  # A map of key-value pairs of Kubernetes labels to apply to all EC2 instances,
  # across all Node Groups.
  common_labels = {}

  # A map of key-value pairs of AWS tags to apply to all EC2 instances, across
  # all Node Groups.
  common_tags = {}

  # If you set this variable to false, this module will not create any
  # resources. This is used as a workaround because Terraform does not allow you
  # to use the 'count' parameter on modules. By using this parameter, you can
  # optionally create or not create the resources within this module.
  create_resources = true

  # A map of default tags to apply to all supported resources in this module.
  # These tags will be merged with any other resource specific tags. The key is
  # the tag name and the value is the tag value.
  default_tags = {}

  # A map of custom tags to apply to the EKS Worker IAM Role. The key is the tag
  # name and the value is the tag value.
  eks_worker_iam_role_tags = {}

  # Whether or not the IAM role used for the workers already exists. When false,
  # this module will create a new IAM role.
  iam_role_already_exists = false

  # ARN of the IAM role to use if iam_role_already_exists = true. When null,
  # uses iam_role_name to lookup the ARN. One of iam_role_name and iam_role_arn
  # is required (must be non-null) if iam_role_already_exists is true.
  iam_role_arn = null

  # Custom name for the IAM role. When null, a default name based on
  # cluster_name will be used. One of iam_role_name and iam_role_arn is required
  # (must be non-null) if iam_role_already_exists is true.
  iam_role_name = null

  # The version of Kubernetes to use for the AMI. Defaults to the Kubernetes
  # version of the EKS cluster.
  kubernetes_version = null

  # Tags assigned to a node group are mirrored to the underlaying autoscaling
  # group by default. If you want to disable this behaviour, set this flag to
  # false. Note that this assumes that there is a one-to-one mappping between
  # ASGs and Node Groups. If there is more than one ASG mapped to the Node
  # Group, then this will only apply the tags on the first one. Due to a
  # limitation in Terraform for_each where it can not depend on dynamic data, it
  # is currently not possible in the module to map the tags to all ASGs. If you
  # wish to apply the tags to all underlying ASGs, then it is recommended to
  # call the aws_autoscaling_group_tag resource in a separate terraform state
  # file outside of this module, or use a two-stage apply process.
  mirror_node_group_tags_to_asg = true

  # Prefix resource names with this string. When you have multiple worker groups
  # for the cluster, you can use this to namespace the resources.
  name_prefix = ""

  # Suffix resource names with this string. When you have multiple worker groups
  # for the cluster, you can use this to namespace the resources.
  name_suffix = ""

  # Default value for ami_type field of node_group_configurations.
  node_group_default_ami_type = "AL2_x86_64"

  # Default value for ami_version field of node_group_configurations.
  node_group_default_ami_version = null

  # Default value for capacity_type field of node_group_configurations.
  node_group_default_capacity_type = "ON_DEMAND"

  # Default value for desired_size field of node_group_configurations.
  node_group_default_desired_size = 1

  # Default value for disk_size field of node_group_configurations.
  node_group_default_disk_size = 30

  # Whether to force the roll out of release versions to the EKS workers. When
  # true, this will forcefully delete any pods after 15 minutes if it is not
  # able to safely drain the nodes. When null (default), this setting is false.
  node_group_default_force_update_version = null

  # Default value for instance_types field of node_group_configurations.
  node_group_default_instance_types = ["t3.medium"]

  # Default value for labels field of node_group_configurations. Unlike
  # common_labels which will always be merged in, these labels are only used if
  # the labels field is omitted from the configuration.
  node_group_default_labels = {}

  # Default value for launch_template field of node_group_configurations.
  node_group_default_launch_template = null

  # Default value for max_size field of node_group_configurations.
  node_group_default_max_size = 1

  # Default value for min_size field of node_group_configurations.
  node_group_default_min_size = 1

  # Default value for subnet_ids field of node_group_configurations.
  node_group_default_subnet_ids = null

  # Default value for tags field of node_group_configurations. Unlike
  # common_tags which will always be merged in, these tags are only used if the
  # tags field is omitted from the configuration.
  node_group_default_tags = {}

  # Default value for taint field of node_group_configurations. These taints are
  # only used if the taint field is omitted from the configuration.
  node_group_default_taints = []

  # The names of the node groups. When null, this value is automatically
  # calculated from the node_group_configurations map. This variable must be set
  # if any of the values of the node_group_configurations map depends on a
  # resource that is not available at plan time to work around terraform
  # limitations with for_each.
  node_group_names = null

  # ARN of permissions boundary to apply to the worker IAM role - the IAM role
  # created for the EKS worker nodes.
  worker_iam_role_permissions_boundary = null

}

terragrunt.hcl

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S EKS-CLUSTER-MANAGED-WORKERS MODULE
# ------------------------------------------------------------------------------------------------------

terraform {
  source = "git::git@github.com:gruntwork-io/terraform-aws-eks.git//modules/eks-cluster-managed-workers?ref=v0.72.3"
}

inputs = {

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The name of the EKS cluster (e.g. eks-prod). This is used to namespace all
  # the resources created by these templates.
  cluster_name = <string>

  # Configure one or more Node Groups to manage the EC2 instances in this
  # cluster.
  node_group_configurations = <any>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # List of Security Group IDs to allow SSH access from. Only used if
  # var.cluster_instance_keypair_name is set. Set to null to allow access from
  # all locations.
  allow_ssh_from_security_groups = []

  # Where to get the AMI from. Can be 'auto', 'launch_template', or
  # 'eks_nodegroup'. WARNING there are limitation on what the value is, check
  # the documentation for more information
  # https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#mng-ami-id-conditions
  ami_source = "auto"

  # The AWS partition used for default AWS Resources.
  aws_partition = "aws"

  # The EC2 Keypair name used to SSH into the EKS Cluster's EC2 Instances. To
  # disable keypairs, pass in blank.
  cluster_instance_keypair_name = null

  # A map of key-value pairs of Kubernetes labels to apply to all EC2 instances,
  # across all Node Groups.
  common_labels = {}

  # A map of key-value pairs of AWS tags to apply to all EC2 instances, across
  # all Node Groups.
  common_tags = {}

  # If you set this variable to false, this module will not create any
  # resources. This is used as a workaround because Terraform does not allow you
  # to use the 'count' parameter on modules. By using this parameter, you can
  # optionally create or not create the resources within this module.
  create_resources = true

  # A map of default tags to apply to all supported resources in this module.
  # These tags will be merged with any other resource specific tags. The key is
  # the tag name and the value is the tag value.
  default_tags = {}

  # A map of custom tags to apply to the EKS Worker IAM Role. The key is the tag
  # name and the value is the tag value.
  eks_worker_iam_role_tags = {}

  # Whether or not the IAM role used for the workers already exists. When false,
  # this module will create a new IAM role.
  iam_role_already_exists = false

  # ARN of the IAM role to use if iam_role_already_exists = true. When null,
  # uses iam_role_name to lookup the ARN. One of iam_role_name and iam_role_arn
  # is required (must be non-null) if iam_role_already_exists is true.
  iam_role_arn = null

  # Custom name for the IAM role. When null, a default name based on
  # cluster_name will be used. One of iam_role_name and iam_role_arn is required
  # (must be non-null) if iam_role_already_exists is true.
  iam_role_name = null

  # The version of Kubernetes to use for the AMI. Defaults to the Kubernetes
  # version of the EKS cluster.
  kubernetes_version = null

  # Tags assigned to a node group are mirrored to the underlaying autoscaling
  # group by default. If you want to disable this behaviour, set this flag to
  # false. Note that this assumes that there is a one-to-one mappping between
  # ASGs and Node Groups. If there is more than one ASG mapped to the Node
  # Group, then this will only apply the tags on the first one. Due to a
  # limitation in Terraform for_each where it can not depend on dynamic data, it
  # is currently not possible in the module to map the tags to all ASGs. If you
  # wish to apply the tags to all underlying ASGs, then it is recommended to
  # call the aws_autoscaling_group_tag resource in a separate terraform state
  # file outside of this module, or use a two-stage apply process.
  mirror_node_group_tags_to_asg = true

  # Prefix resource names with this string. When you have multiple worker groups
  # for the cluster, you can use this to namespace the resources.
  name_prefix = ""

  # Suffix resource names with this string. When you have multiple worker groups
  # for the cluster, you can use this to namespace the resources.
  name_suffix = ""

  # Default value for ami_type field of node_group_configurations.
  node_group_default_ami_type = "AL2_x86_64"

  # Default value for ami_version field of node_group_configurations.
  node_group_default_ami_version = null

  # Default value for capacity_type field of node_group_configurations.
  node_group_default_capacity_type = "ON_DEMAND"

  # Default value for desired_size field of node_group_configurations.
  node_group_default_desired_size = 1

  # Default value for disk_size field of node_group_configurations.
  node_group_default_disk_size = 30

  # Whether to force the roll out of release versions to the EKS workers. When
  # true, this will forcefully delete any pods after 15 minutes if it is not
  # able to safely drain the nodes. When null (default), this setting is false.
  node_group_default_force_update_version = null

  # Default value for instance_types field of node_group_configurations.
  node_group_default_instance_types = ["t3.medium"]

  # Default value for labels field of node_group_configurations. Unlike
  # common_labels which will always be merged in, these labels are only used if
  # the labels field is omitted from the configuration.
  node_group_default_labels = {}

  # Default value for launch_template field of node_group_configurations.
  node_group_default_launch_template = null

  # Default value for max_size field of node_group_configurations.
  node_group_default_max_size = 1

  # Default value for min_size field of node_group_configurations.
  node_group_default_min_size = 1

  # Default value for subnet_ids field of node_group_configurations.
  node_group_default_subnet_ids = null

  # Default value for tags field of node_group_configurations. Unlike
  # common_tags which will always be merged in, these tags are only used if the
  # tags field is omitted from the configuration.
  node_group_default_tags = {}

  # Default value for taint field of node_group_configurations. These taints are
  # only used if the taint field is omitted from the configuration.
  node_group_default_taints = []

  # The names of the node groups. When null, this value is automatically
  # calculated from the node_group_configurations map. This variable must be set
  # if any of the values of the node_group_configurations map depends on a
  # resource that is not available at plan time to work around terraform
  # limitations with for_each.
  node_group_names = null

  # ARN of permissions boundary to apply to the worker IAM role - the IAM role
  # created for the EKS worker nodes.
  worker_iam_role_permissions_boundary = null

}

Reference

Inputs
Outputs

Required

cluster_namestringrequired

The name of the EKS cluster (e.g. eks-prod). This is used to namespace all the resources created by these templates.

node_group_configurationsanyrequired

Configure one or more Node Groups to manage the EC2 instances in this cluster.

Type Details

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.

More Details

Details

   Each configuration must be keyed by a unique string that will be used as a suffix for the node group name. The
   values support the following attributes:
  
  
   OPTIONAL (defaults to value of corresponding module input):
   - subnet_ids          list(string)       : (Defaults to value from var.node_group_default_subnet_ids) A list of the
                                              subnets into which the EKS Cluster's managed nodes will be launched.
                                              These should usually be all private subnets and include one in each AWS
                                              Availability Zone. NOTE: If using a cluster autoscaler with EBS volumes,
                                              each ASG may only belong to a single availability zone.
   - min_size            number             : (Defaults to value from var.node_group_default_min_size) The minimum
                                              number of EC2 Instances representing workers launchable for this EKS
                                              Cluster. Useful for auto-scaling limits.
   - max_size            number             : (Defaults to value from var.node_group_default_max_size) The maximum
                                              number of EC2 Instances representing workers that must be running for
                                              this EKS Cluster. We recommend making this at least twice the min_size,
                                              even if you don't plan on scaling the cluster up and down, as the extra
                                              capacity will be used to deploy updates to the cluster.
   - desired_size        number             : (Defaults to value from var.node_group_default_desired_size) The current
                                              desired number of EC2 Instances representing workers that must be running
                                              for this EKS Cluster.
   - instance_types      list(string)       : (Defaults to value from var.node_group_default_instance_types) A list of
                                              instance types (e.g., t3.medium) to use for the EKS Cluster's worker
                                              nodes. EKS will choose from this list of instance types when launching
                                              new instances. When using launch templates, this setting will override
                                              the configured instance type of the launch template.
   - capacity_type       string             : (Defaults to value from var.node_group_default_capacity_type) Type of capacity
                                              associated with the EKS Node Group. Valid values: ON_DEMAND, SPOT.
   - force_update_version bool              : (Defaults to value from var.node_group_default_force_update_version)
                                              Whether to force the roll out of release versions to the EKS workers.
                                              When true, this will forcefully delete any pods after 15 minutes if it is
                                              not able to safely drain the nodes.
   - launch_template     LaunchTemplate     : (Defaults to value from var.node_group_default_launch_template)
                                              Launch template to use for the node. Specify either Name or ID of launch
                                              template. Must include version. Although the API supports using the
                                              values "$Latest" and "$Default" to configure the version, this can lead
                                              to a perpetual diff. Use the `latest_version` or `default_version` output
                                              of the aws_launch_template data source or resource instead. See
                                              https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/eks_node_grouplaunch_template-configuration-block
                                              for more information.
   - disk_size           number             : (Defaults to value from var.node_group_default_disk_size) Root disk size
                                              in GiB for the worker nodes.
                                              Ignored if launch_template is configured.
   - ami_type            string             : (Defaults to value from var.node_group_default_ami_type) Type of Amazon
                                              Machine Image (e.g. AL2_x86_64, AL2_x86_64_GPU) associated with the EKS
                                              Node Group.
                                              Ignored if launch_template is configured.
   - ami_version         string             : (Defaults to value from var.node_group_default_ami_version) Version of
                                              the AMI to use for the EKS node groups. If null, the latest version for
                                              the given Kubernetes version will be used.
                                              Ignored if launch_template is configured.
   - tags                map(string)        : (Defaults to value from var.node_group_default_tags) Custom tags to apply
                                              to the EC2 Instances in this node group. This should be a key value pair,
                                              where the keys are tag keys and values are the tag values. Merged with
                                              var.common_tags.
   - labels              map(string)        : (Defaults to value from var.node_group_default_labels) Custom Kubernetes
                                              Labels to apply to the EC2 Instances in this node group. This should be a
                                              key value pair, where the keys are label keys and values are the label
                                              values. Merged with var.common_labels.
   - taints              list(map(string))  : (Defaults to value from var.node_group_default_taints) Custom Kubernetes
                                              taint to apply to the EC2 Instances in this node group. See below for
                                              structure of taints.
  
   Structure of LaunchTemplate object:
   - name     string  : The Name of the Launch Template to use. One of ID or Name should be provided.
   - id       string  : The ID of the Launch Template to use. One of ID or Name should be provided.
   - version  string  : The version of the Launch Template to use.
  
   Structure of Taints Object: [{},{}]
   - key     string  : The key of the taint. Maximum length of 63.
   - value   string  : The value of the taint. Maximum length of 63.
   - effect  string  : The effect of the taint. Valid values: NO_SCHEDULE, NO_EXECUTE, PREFER_NO_SCHEDULE.
  
   Example:
   node_group_configurations = {
     ngroup1 = {
       desired_size = 1
       min_size     = 1
       max_size     = 3
       subnet_ids  = [data.terraform_remote_state.vpc.outputs.private_app_subnet_ids[0]]
     }
     asg2 = {
       desired_size   = 1
       min_size       = 1
       max_size       = 3
       subnet_ids     = [data.terraform_remote_state.vpc.outputs.private_app_subnet_ids[0]]
       disk_size      = 50
     }
     ngroup2 = {}   Only defaults
   }

Optional

allow_ssh_from_security_groupslist(string)optional

List of Security Group IDs to allow SSH access from. Only used if cluster_instance_keypair_name is set. Set to null to allow access from all locations.

Default:[]

ami_sourcestringoptional

Where to get the AMI from. Can be 'auto', 'launch_template', or 'eks_nodegroup'. WARNING there are limitation on what the value is, check the documentation for more information https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#mng-ami-id-conditions

Default:"auto"

aws_partitionstringoptional

The AWS partition used for default AWS Resources.

Default:"aws"

cluster_instance_keypair_namestringoptional

The EC2 Keypair name used to SSH into the EKS Cluster's EC2 Instances. To disable keypairs, pass in blank.

Default:null

common_labelsmap(string)optional

A map of key-value pairs of Kubernetes labels to apply to all EC2 instances, across all Node Groups.

Default:{}

common_tagsmap(string)optional

A map of key-value pairs of AWS tags to apply to all EC2 instances, across all Node Groups.

Default:{}

create_resourcesbooloptional

If you set this variable to false, this module will not create any resources. This is used as a workaround because Terraform does not allow you to use the 'count' parameter on modules. By using this parameter, you can optionally create or not create the resources within this module.

Default:true

default_tagsmap(string)optional

A map of default tags to apply to all supported resources in this module. These tags will be merged with any other resource specific tags. The key is the tag name and the value is the tag value.

Default:{}

eks_worker_iam_role_tagsmap(string)optional

A map of custom tags to apply to the EKS Worker IAM Role. The key is the tag name and the value is the tag value.

Default:{}

iam_role_already_existsbooloptional

Whether or not the IAM role used for the workers already exists. When false, this module will create a new IAM role.

Default:false

iam_role_arnstringoptional

ARN of the IAM role to use if iam_role_already_exists = true. When null, uses iam_role_name to lookup the ARN. One of iam_role_name and iam_role_arn is required (must be non-null) if iam_role_already_exists is true.

Default:null

iam_role_namestringoptional

Custom name for the IAM role. When null, a default name based on cluster_name will be used. One of iam_role_name and iam_role_arn is required (must be non-null) if iam_role_already_exists is true.

Default:null

kubernetes_versionstringoptional

The version of Kubernetes to use for the AMI. Defaults to the Kubernetes version of the EKS cluster.

Default:null

mirror_node_group_tags_to_asgbooloptional

Tags assigned to a node group are mirrored to the underlaying autoscaling group by default. If you want to disable this behaviour, set this flag to false. Note that this assumes that there is a one-to-one mappping between ASGs and Node Groups. If there is more than one ASG mapped to the Node Group, then this will only apply the tags on the first one. Due to a limitation in Terraform for_each where it can not depend on dynamic data, it is currently not possible in the module to map the tags to all ASGs. If you wish to apply the tags to all underlying ASGs, then it is recommended to call the aws_autoscaling_group_tag resource in a separate terraform state file outside of this module, or use a two-stage apply process.

Default:true

name_prefixstringoptional

Prefix resource names with this string. When you have multiple worker groups for the cluster, you can use this to namespace the resources.

Default:""

name_suffixstringoptional

Suffix resource names with this string. When you have multiple worker groups for the cluster, you can use this to namespace the resources.

Default:""

node_group_default_ami_typestringoptional

Default value for ami_type field of node_group_configurations.

Default:"AL2_x86_64"

node_group_default_ami_versionstringoptional

Default value for ami_version field of node_group_configurations.

Default:null

node_group_default_capacity_typestringoptional

Default value for capacity_type field of node_group_configurations.

Default:"ON_DEMAND"

node_group_default_desired_sizenumberoptional

Default value for desired_size field of node_group_configurations.

Default:1

node_group_default_disk_sizenumberoptional

Default value for disk_size field of node_group_configurations.

Default:30

node_group_default_force_update_versionbooloptional

Whether to force the roll out of release versions to the EKS workers. When true, this will forcefully delete any pods after 15 minutes if it is not able to safely drain the nodes. When null (default), this setting is false.

Default:null

node_group_default_instance_typeslist(string)optional

Default value for instance_types field of node_group_configurations.

Default:

[
"t3.medium"
]

node_group_default_labelsmap(string)optional

Default value for labels field of node_group_configurations. Unlike common_labels which will always be merged in, these labels are only used if the labels field is omitted from the configuration.

Default:{}

node_group_default_launch_templateobject(…)optional

Default value for launch_template field of node_group_configurations.

Type Details

object({
    name    = string
    id      = string
    version = string
  })

Default:null

node_group_default_max_sizenumberoptional

Default value for max_size field of node_group_configurations.

Default:1

node_group_default_min_sizenumberoptional

Default value for min_size field of node_group_configurations.

Default:1

node_group_default_subnet_idslist(string)optional

Default value for subnet_ids field of node_group_configurations.

Default:null

node_group_default_tagsmap(string)optional

Default value for tags field of node_group_configurations. Unlike common_tags which will always be merged in, these tags are only used if the tags field is omitted from the configuration.

Default:{}

node_group_default_taintslist(map(…))optional

Default value for taint field of node_group_configurations. These taints are only used if the taint field is omitted from the configuration.

Type Details

list(map(string))

Default:[]

node_group_nameslist(string)optional

The names of the node groups. When null, this value is automatically calculated from the node_group_configurations map. This variable must be set if any of the values of the node_group_configurations map depends on a resource that is not available at plan time to work around terraform limitations with for_each.

Default:null

worker_iam_role_permissions_boundarystringoptional

ARN of permissions boundary to apply to the worker IAM role - the IAM role created for the EKS worker nodes.

Default:null

eks_worker_asg_names

Map of Node Group names to Auto Scaling Group names

eks_worker_asg_security_group_ids

Map of Node Group names to Auto Scaling Group security group IDs. Empty if cluster_instance_keypair_name is not set.

eks_worker_iam_role_arn

AWS ARN identifier of the IAM role created for the EKS worker nodes.

eks_worker_iam_role_name

Name of the IAM role created for the EKS worker nodes.