AWS EKS Terraform module

Terraform module which creates Kubernetes cluster resources on AWS EKS.

Features

Create an EKS cluster
All node types are supported:
Support AWS EKS Optimized or Custom AMI
Create or manage security groups that allow communication and coordination

Important note

Kubernetes is evolving a lot, and each minor version includes new features, fixes, or changes.

Always check Kubernetes Release Notes before updating the major version, and CHANGELOG.md for all changes in this EKS module.

You also need to ensure that your applications and add ons are updated, or workloads could fail after the upgrade is complete. For action, you may need to take before upgrading, see the steps in the EKS documentation.

Usage example

data "aws_eks_cluster" "eks" {
  name = module.eks.cluster_id
}

data "aws_eks_cluster_auth" "eks" {
  name = module.eks.cluster_id
}

provider "kubernetes" {
  host                   = data.aws_eks_cluster.eks.endpoint
  cluster_ca_certificate = base64decode(data.aws_eks_cluster.eks.certificate_authority[0].data)
  token                  = data.aws_eks_cluster_auth.eks.token
}

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

  cluster_version = "1.21"
  cluster_name    = "my-cluster"
  vpc_id          = "vpc-1234556abcdef"
  subnets         = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]

  worker_groups = [
    {
      instance_type = "m4.large"
      asg_max_size  = 5
    }
  ]
}

There is also a complete example which shows large set of features available in the module.

Submodules

Root module calls these modules which can also be used separately to create independent resources:

fargate - creates Fargate profiles, see examples/fargate for detailed examples.

Notes

By default, this module manages the aws-auth configmap for you (manage_aws_auth=true). To avoid the following issue where the EKS creation is ACTIVE but not ready. We implemented a "retry" logic with a fork of the http provider. This fork adds the support of a self-signed CA certificate. The original PR can be found here.
Setting instance_refresh_enabled = true will recreate your worker nodes without draining them first. It is recommended to install aws-node-termination-handler for proper node draining. Find the complete example here instance_refresh.

Documentation

Official docs

Amazon Elastic Kubernetes Service (Amazon EKS).

Module docs

Autoscaling: How to enable worker node autoscaling.
Enable Docker Bridge Network: How to enable the docker bridge network when using the EKS-optimized AMI, which disables it by default.
Spot instances: How to use spot instances with this module.
IAM Permissions: Minimum IAM permissions needed to setup EKS Cluster.
FAQ: Frequently Asked Questions

Examples

There are detailed examples available for you to see how certain features of this module can be used in a straightforward way. Make sure to check them and run them before opening an issue. Here you can find the list of the minimum IAM Permissions required to create EKS cluster.

Complete - Create EKS Cluster with all available workers types in various combinations with many of supported features.
Bottlerocket - Create EKS cluster using Bottlerocket AMI.
Fargate - Create EKS cluster with Fargate profiles and attach Fargate profiles to an existing EKS cluster.

Contributing

Report issues/questions/feature requests on in the issues section.

Full contributing guidelines are covered here.

Authors

This module has been originally created by Brandon O'Connor, and was maintained by Max Williams, Thierno IB. BARRY and many more contributors listed here!

License

Apache 2 Licensed. See LICENSE for full details.

Requirements

Name	Version
terraform	>= 0.13.1
aws	>= 3.56.0
cloudinit	>= 2.0
http	>= 2.4.1
kubernetes	>= 1.11.1
local	>= 1.4

Providers

Name	Version
aws	>= 3.56.0
http	>= 2.4.1
kubernetes	>= 1.11.1
local	>= 1.4

Modules

Name	Source	Version
fargate	./modules/fargate
node_groups	./modules/node_groups

Resources

Name	Type
aws_autoscaling_group.workers	resource
aws_autoscaling_group.workers_launch_template	resource
aws_cloudwatch_log_group.this	resource
aws_eks_cluster.this	resource
aws_iam_instance_profile.workers	resource
aws_iam_instance_profile.workers_launch_template	resource
aws_iam_openid_connect_provider.oidc_provider	resource
aws_iam_policy.cluster_deny_log_group	resource
aws_iam_policy.cluster_elb_sl_role_creation	resource
aws_iam_role.cluster	resource
aws_iam_role.workers	resource
aws_iam_role_policy_attachment.cluster_AmazonEKSClusterPolicy	resource
aws_iam_role_policy_attachment.cluster_AmazonEKSServicePolicy	resource
aws_iam_role_policy_attachment.cluster_AmazonEKSVPCResourceControllerPolicy	resource
aws_iam_role_policy_attachment.cluster_deny_log_group	resource
aws_iam_role_policy_attachment.cluster_elb_sl_role_creation	resource
aws_iam_role_policy_attachment.workers_AmazonEC2ContainerRegistryReadOnly	resource
aws_iam_role_policy_attachment.workers_AmazonEKSWorkerNodePolicy	resource
aws_iam_role_policy_attachment.workers_AmazonEKS_CNI_Policy	resource
aws_iam_role_policy_attachment.workers_additional_policies	resource
aws_launch_configuration.workers	resource
aws_launch_template.workers_launch_template	resource
aws_security_group.cluster	resource
aws_security_group.workers	resource
aws_security_group_rule.cluster_egress_internet	resource
aws_security_group_rule.cluster_https_worker_ingress	resource
aws_security_group_rule.cluster_primary_ingress_workers	resource
aws_security_group_rule.cluster_private_access_cidrs_source	resource
aws_security_group_rule.cluster_private_access_sg_source	resource
aws_security_group_rule.workers_egress_internet	resource
aws_security_group_rule.workers_ingress_cluster	resource
aws_security_group_rule.workers_ingress_cluster_https	resource
aws_security_group_rule.workers_ingress_cluster_kubelet	resource
aws_security_group_rule.workers_ingress_cluster_primary	resource
aws_security_group_rule.workers_ingress_self	resource
kubernetes_config_map.aws_auth	resource
local_file.kubeconfig	resource
aws_ami.eks_worker	data source
aws_ami.eks_worker_windows	data source
aws_caller_identity.current	data source
aws_iam_instance_profile.custom_worker_group_iam_instance_profile	data source
aws_iam_instance_profile.custom_worker_group_launch_template_iam_instance_profile	data source
aws_iam_policy_document.cluster_assume_role_policy	data source
aws_iam_policy_document.cluster_deny_log_group	data source
aws_iam_policy_document.cluster_elb_sl_role_creation	data source
aws_iam_policy_document.workers_assume_role_policy	data source
aws_iam_role.custom_cluster_iam_role	data source
aws_partition.current	data source
http_http.wait_for_cluster	data source

Inputs

Name	Description	Type	Default	Required
attach_worker_cni_policy	Whether to attach the Amazon managed `AmazonEKS_CNI_Policy` IAM policy to the default worker 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
aws_auth_additional_labels	Additional kubernetes labels applied on aws-auth ConfigMap	`map(string)`	`{}`	no
cluster_create_endpoint_private_access_sg_rule	Whether to create security group rules for the access to the Amazon EKS private API server endpoint. When is `true`, `cluster_endpoint_private_access_cidrs` must be setted.	`bool`	`false`	no
cluster_create_security_group	Whether to create a security group for the cluster or attach the cluster to `cluster_security_group_id`.	`bool`	`true`	no
cluster_create_timeout	Timeout value when creating the EKS cluster.	`string`	`"30m"`	no
cluster_delete_timeout	Timeout value when deleting the EKS cluster.	`string`	`"15m"`	no
cluster_egress_cidrs	List of CIDR blocks that are permitted for cluster egress traffic.	`list(string)`	[ "0.0.0.0/0" ]	no
cluster_enabled_log_types	A list of the desired control plane logging to enable. For more information, see Amazon EKS Control Plane Logging documentation (https://docs.aws.amazon.com/eks/latest/userguide/control-plane-logs.html)	`list(string)`	`[]`	no
cluster_encryption_config	Configuration block with encryption configuration for the cluster. See examples/secrets_encryption/main.tf for example format	list(object({ provider_key_arn = string resources = list(string) }))	`[]`	no
cluster_endpoint_private_access	Indicates whether or not the Amazon EKS private API server endpoint is enabled.	`bool`	`false`	no
cluster_endpoint_private_access_cidrs	List of CIDR blocks which can access the Amazon EKS private API server endpoint. To use this `cluster_endpoint_private_access` and `cluster_create_endpoint_private_access_sg_rule` must be set to `true`.	`list(string)`	`null`	no
cluster_endpoint_private_access_sg	List of security group IDs which can access the Amazon EKS private API server endpoint. To use this `cluster_endpoint_private_access` and `cluster_create_endpoint_private_access_sg_rule` must be set to `true`.	`list(string)`	`null`	no
cluster_endpoint_public_access	Indicates whether or not the Amazon EKS public API server endpoint is enabled. When it's set to `false` ensure to have a proper private access with `cluster_endpoint_private_access = true`.	`bool`	`true`	no
cluster_endpoint_public_access_cidrs	List of CIDR blocks which can access the Amazon EKS public API server endpoint.	`list(string)`	[ "0.0.0.0/0" ]	no
cluster_iam_role_name	IAM role name for the cluster. If manage_cluster_iam_resources is set to false, set this to reuse an existing IAM role. If manage_cluster_iam_resources is set to true, set this to force the created role name.	`string`	`""`	no
cluster_log_kms_key_id	If a KMS Key ARN is set, this key will be used to encrypt the corresponding log group. Please be sure that the KMS Key has an appropriate key policy (https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html)	`string`	`""`	no
cluster_log_retention_in_days	Number of days to retain log events. Default retention - 90 days.	`number`	`90`	no
cluster_name	Name of the EKS cluster. Also used as a prefix in names of related resources.	`string`	`""`	no
cluster_security_group_id	If provided, the EKS cluster will be attached to this security group. If not given, a security group will be created with necessary ingress/egress to work with the workers	`string`	`""`	no
cluster_service_ipv4_cidr	service ipv4 cidr for the kubernetes cluster	`string`	`null`	no
cluster_tags	A map of tags to add to just the eks resource.	`map(string)`	`{}`	no
cluster_update_timeout	Timeout value when updating the EKS cluster.	`string`	`"60m"`	no
cluster_version	Kubernetes minor version to use for the EKS cluster (for example 1.21).	`string`	`null`	no
create_eks	Controls if EKS resources should be created (it affects almost all resources)	`bool`	`true`	no
create_fargate_pod_execution_role	Controls if the EKS Fargate pod execution IAM role should be created.	`bool`	`true`	no
default_platform	Default platform name. Valid options are `linux` and `windows`.	`string`	`"linux"`	no
eks_oidc_root_ca_thumbprint	Thumbprint of Root CA for EKS OIDC, Valid until 2037	`string`	`"9e99a48a9960b14926bb7f3b02e22da2b0ab7280"`	no
enable_irsa	Whether to create OpenID Connect Provider for EKS to enable IRSA	`bool`	`false`	no
fargate_pod_execution_role_name	The IAM Role that provides permissions for the EKS Fargate Profile.	`string`	`null`	no
fargate_profiles	Fargate profiles to create. See `fargate_profile` keys section in fargate submodule's README.md for more details	`any`	`{}`	no
fargate_subnets	A list of subnets to place fargate workers within (if different from subnets).	`list(string)`	`[]`	no
iam_path	If provided, all IAM roles will be created on this path.	`string`	`"/"`	no
kubeconfig_api_version	KubeConfig API version. Defaults to client.authentication.k8s.io/v1alpha1	`string`	`"client.authentication.k8s.io/v1alpha1"`	no
kubeconfig_aws_authenticator_additional_args	Any additional arguments to pass to the authenticator such as the role to assume. e.g. ["-r", "MyEksRole"].	`list(string)`	`[]`	no
kubeconfig_aws_authenticator_command	Command to use to fetch AWS EKS credentials.	`string`	`"aws-iam-authenticator"`	no
kubeconfig_aws_authenticator_command_args	Default arguments passed to the authenticator command. Defaults to [token -i $cluster_name].	`list(string)`	`[]`	no
kubeconfig_aws_authenticator_env_variables	Environment variables that should be used when executing the authenticator. e.g. { AWS_PROFILE = "eks"}.	`map(string)`	`{}`	no
kubeconfig_file_permission	File permission of the Kubectl config file containing cluster configuration saved to `kubeconfig_output_path.`	`string`	`"0600"`	no
kubeconfig_name	Override the default name used for items kubeconfig.	`string`	`""`	no
kubeconfig_output_path	Where to save the Kubectl config file (if `write_kubeconfig = true`). Assumed to be a directory if the value ends with a forward slash `/`.	`string`	`"./"`	no
manage_aws_auth	Whether to apply the aws-auth configmap file.	`bool`	`true`	no
manage_cluster_iam_resources	Whether to let the module manage cluster IAM resources. If set to false, cluster_iam_role_name must be specified.	`bool`	`true`	no
manage_worker_iam_resources	Whether to let the module manage worker IAM resources. If set to false, iam_instance_profile_name must be specified for workers.	`bool`	`true`	no
map_accounts	Additional AWS account numbers to add to the aws-auth configmap.	`list(string)`	`[]`	no
map_roles	Additional IAM roles to add to the aws-auth configmap.	list(object({ rolearn = string username = string groups = list(string) }))	`[]`	no
map_users	Additional IAM users to add to the aws-auth configmap.	list(object({ userarn = string username = string groups = list(string) }))	`[]`	no
node_groups	Map of map of node groups to create. See `node_groups` module's documentation for more details	`any`	`{}`	no
node_groups_defaults	Map of values to be applied to all node groups. See `node_groups` module's documentation for more details	`any`	`{}`	no
openid_connect_audiences	List of OpenID Connect audience client IDs to add to the IRSA provider.	`list(string)`	`[]`	no
permissions_boundary	If provided, all IAM roles will be created with this permissions boundary attached.	`string`	`null`	no
subnets	A list of subnets to place the EKS cluster and workers within.	`list(string)`	`[]`	no
tags	A map of tags to add to all resources. Tags added to launch configuration or templates override these values for ASG Tags only.	`map(string)`	`{}`	no
vpc_id	VPC where the cluster and workers will be deployed.	`string`	`null`	no
wait_for_cluster_timeout	A timeout (in seconds) to wait for cluster to be available.	`number`	`300`	no
worker_additional_security_group_ids	A list of additional security group ids to attach to worker instances	`list(string)`	`[]`	no
worker_ami_name_filter	Name filter for AWS EKS worker AMI. If not provided, the latest official AMI for the specified 'cluster_version' is used.	`string`	`""`	no
worker_ami_name_filter_windows	Name filter for AWS EKS Windows worker AMI. If not provided, the latest official AMI for the specified 'cluster_version' is used.	`string`	`""`	no
worker_ami_owner_id	The ID of the owner for the AMI to use for the AWS EKS workers. Valid values are an AWS account ID, 'self' (the current account), or an AWS owner alias (e.g. 'amazon', 'aws-marketplace', 'microsoft').	`string`	`"amazon"`	no
worker_ami_owner_id_windows	The ID of the owner for the AMI to use for the AWS EKS Windows workers. Valid values are an AWS account ID, 'self' (the current account), or an AWS owner alias (e.g. 'amazon', 'aws-marketplace', 'microsoft').	`string`	`"amazon"`	no
worker_create_cluster_primary_security_group_rules	Whether to create security group rules to allow communication between pods on workers and pods using the primary cluster security group.	`bool`	`false`	no
worker_create_initial_lifecycle_hooks	Whether to create initial lifecycle hooks provided in worker groups.	`bool`	`false`	no
worker_create_security_group	Whether to create a security group for the workers or attach the workers to `worker_security_group_id`.	`bool`	`true`	no
worker_groups	A list of maps defining worker group configurations to be defined using AWS Launch Configurations. See workers_group_defaults for valid keys.	`any`	`[]`	no
worker_groups_launch_template	A list of maps defining worker group configurations to be defined using AWS Launch Templates. See workers_group_defaults for valid keys.	`any`	`[]`	no
worker_security_group_id	If provided, all workers will be attached to this security group. If not given, a security group will be created with necessary ingress/egress to work with the EKS cluster.	`string`	`""`	no
worker_sg_ingress_from_port	Minimum port number from which pods will accept communication. Must be changed to a lower value if some pods in your cluster will expose a port lower than 1025 (e.g. 22, 80, or 443).	`number`	`1025`	no
workers_additional_policies	Additional policies to be added to workers	`list(string)`	`[]`	no
workers_egress_cidrs	List of CIDR blocks that are permitted for workers egress traffic.	`list(string)`	[ "0.0.0.0/0" ]	no
workers_group_defaults	Override default values for target groups. See workers_group_defaults_defaults in local.tf for valid keys.	`any`	`{}`	no
workers_role_name	User defined workers role name.	`string`	`""`	no
write_kubeconfig	Whether to write a Kubectl config file containing the cluster configuration. Saved to `kubeconfig_output_path`.	`bool`	`true`	no

Outputs

Name	Description
cloudwatch_log_group_arn	Arn of cloudwatch log group created
cloudwatch_log_group_name	Name of cloudwatch log group created
cluster_arn	The Amazon Resource Name (ARN) of the cluster.
cluster_certificate_authority_data	Nested attribute containing certificate-authority-data for your cluster. This is the base64 encoded certificate data required to communicate with your cluster.
cluster_endpoint	The endpoint for your EKS Kubernetes API.
cluster_iam_role_arn	IAM role ARN of the EKS cluster.
cluster_iam_role_name	IAM role name of the EKS cluster.
cluster_id	The name/id of the EKS cluster. Will block on cluster creation until the cluster is really ready.
cluster_oidc_issuer_url	The URL on the EKS cluster OIDC Issuer
cluster_primary_security_group_id	The cluster primary security group ID created by the EKS cluster on 1.14 or later. Referred to as 'Cluster security group' in the EKS console.
cluster_security_group_id	Security group ID attached to the EKS cluster. On 1.14 or later, this is the 'Additional security groups' in the EKS console.
cluster_version	The Kubernetes server version for the EKS cluster.
config_map_aws_auth	A kubernetes configuration to authenticate to this EKS cluster.
fargate_iam_role_arn	IAM role ARN for EKS Fargate pods
fargate_iam_role_name	IAM role name for EKS Fargate pods
fargate_profile_arns	Amazon Resource Name (ARN) of the EKS Fargate Profiles.
fargate_profile_ids	EKS Cluster name and EKS Fargate Profile names separated by a colon (:).
kubeconfig	kubectl config file contents for this EKS cluster. Will block on cluster creation until the cluster is really ready.
kubeconfig_filename	The filename of the generated kubectl config. Will block on cluster creation until the cluster is really ready.
node_groups	Outputs from EKS node groups. Map of maps, keyed by var.node_groups keys
oidc_provider_arn	The ARN of the OIDC Provider if `enable_irsa = true`.
security_group_rule_cluster_https_worker_ingress	Security group rule responsible for allowing pods to communicate with the EKS cluster API.
worker_iam_instance_profile_arns	default IAM instance profile ARN for EKS worker groups
worker_iam_instance_profile_names	default IAM instance profile name for EKS worker groups
worker_iam_role_arn	default IAM role ARN for EKS worker groups
worker_iam_role_name	default IAM role name for EKS worker groups
worker_security_group_id	Security group ID attached to the EKS workers.
workers_asg_arns	IDs of the autoscaling groups containing workers.
workers_asg_names	Names of the autoscaling groups containing workers.
workers_default_ami_id	ID of the default worker group AMI
workers_default_ami_id_windows	ID of the default Windows worker group AMI
workers_launch_template_arns	ARNs of the worker launch templates.
workers_launch_template_ids	IDs of the worker launch templates.
workers_launch_template_latest_versions	Latest versions of the worker launch templates.
workers_user_data	User data of worker groups

ulm0/terraform-aws-eks