Introduction

Welcome to the Terraform EKS Module!

Terraform module which creates AWS EKS (Kubernetes) resources. This module makes it easy to create and manage an EKS cluster on AWS, with an example terraform configuration for all necessary resources such as VPC, subnets,etc. This module in the current state only focus on Managed node groups concept of worker nodes. The example directory shows how to use the module in a real-world scenario. This module is versioned following semantic versioning. I would love to hear your feedback and see how you're using the module. Please feel free to open an issue on this repository if you have any questions or suggestions.

⭐ This module is motivated from terraform-aws-eks ⭐

Background Knowledge or External Documentation

• AWS EKS Documentation
• Kubernetes Documentation

Available Features

• AWS EKS Cluster Addons
• AWS EKS Identity Provider Configuration
• Support for Eks Node groups with Launch Templates
• Global KMS Key Creation for cluster secrets and Node groups EBS volumes.
• VPC Endpoints Creation in case of Private clusters.

Usage

module "eks" {
  source  = "ishuar/eks/aws"
  version = "~> 1.0"

  name                                  = "my-cluster"
  cluster_version                       = "1.24"
  create_eks_cluster                    = true
  create_cluster_iam_role               = true
  attach_cluster_encryption_policy      = true
  create_cloudwatch_log_group           = true
  cluster_iam_role_name                 = "my-cluster-role"
  subnet_ids                            = ["subnet-abcde012", "subnet-bcde012a"]
  vpc_id                                = "vpc-1234556abcdef"
  cluster_additional_security_group_ids = ["sg-123456abcdefg"]

  ## Create Global KMS key for node and EKS cluster encryption.
  create_encryption_kms_key = true

  ## Encryption Config to encrpt secrets for Cluster using Global KMS key created within the module.
  cluster_encryption_config = [
    {
      resources = ["secrets"]
    }
  ]

  # Node groups Config.
  create_node_group          = true
  create_node_group_iam_role = true
  use_launch_template        = true
  node_group_iam_role_name   = "my-nodegroup-role"
  ebs_optimized              = true
  enable_monitoring          = false

  block_device_mappings = {
    xvda = {
      device_name = "/dev/xvda"
      ebs = {
        encrypted             = true
        delete_on_termination = true
        volume_size           = 80
        volume_type           = "gp3"
      }
    }
  }
  node_groups = {
    node_group_001 = {
      min_size       = 0
      max_size       = 2
      desired_size   = 1
      ami_type       = "AL2_x86_64"
      instance_types = ["t3.medium"]
    }
  }

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

Examples

• Complete Private Cluster Cluster using private endpoint with private node groups , only accessible via private ec2 instance managed with SSM.
• AWS ALB Controller and External DNS with EKS Real world example for How to deploy AWS ALB controller and External DNS add ons in EKS with documentation.
• AWS EKS Cluster Autoscaler as Helm Add-on demonstrate How to deploy AWS EKS cluster Autoscaler as helm addon using ishuar/terraform-aws-eks helm-add-on and irsa submodules.

Submodules

• helm-add-on
• irsa

Requirements

Name	Version
terraform	>= 1.0
aws	~> 4.0
tls	~> 4.0

Providers

Name	Version
aws	~> 4.0
tls	~> 4.0

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_log_group.this	resource
aws_eks_addon.this	resource
aws_eks_cluster.this	resource
aws_eks_node_group.this	resource
aws_iam_openid_connect_provider.this	resource
aws_iam_policy.cluster_encryption	resource
aws_iam_role.node_group	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.cluster_encryption	resource
aws_iam_role_policy_attachment.node_group	resource
aws_iam_role_policy_attachment.this	resource
aws_iam_service_linked_role.autoscaling	resource
aws_kms_alias.this	resource
aws_kms_grant.autoscaling_role_for_kms	resource
aws_kms_key.this	resource
aws_launch_template.this	resource
aws_vpc_endpoint.ec2	resource
aws_vpc_endpoint.ecr_api	resource
aws_vpc_endpoint.ecr_dkr	resource
aws_vpc_endpoint.elasticloadbalancing	resource
aws_vpc_endpoint.logs	resource
aws_vpc_endpoint.s3	resource
aws_vpc_endpoint.sts	resource
aws_caller_identity.current	data source
aws_eks_cluster.this	data source
aws_iam_policy_document.assume_role_policy	data source
aws_iam_policy_document.autoscaling	data source
aws_iam_policy_document.node_group_assume_role_policy	data source
aws_iam_role.autoscaling	data source
aws_partition.current	data source
aws_region.current	data source
tls_certificate.this	data source

Inputs

Name	Description	Type	Default	Required
create_encryption_kms_key	(Required) Whether to create the encryption key or not ?	bool	n/a	yes
name	(Required) Name of the cluster. Must be between 1-100 characters in length. Must begin with an alphanumeric character, and must only contain alphanumeric characters, dashes and underscores.	string	n/a	yes
subnet_ids	(Required) List of subnet IDs. Must be in at least two different availability zones. Amazon EKS creates cross-account elastic network interfaces in these subnets to allow communication between your worker nodes and the Kubernetes control plane.	list(string)	n/a	yes
vpc_id	(Required) VPC ID where any of the required endpoints would be created( vpc id where EKS is deployed). Required if any of the required endpoints are missing	string	n/a	yes
ami_id	(optional) The AMI from which to launch the instance. If not supplied, EKS will use its own default image	string	""	no
attach_cluster_encryption_policy	(Optional) Indicates whether or not to attach an additional policy for the cluster IAM role to utilize the encryption key provided	bool	true	no
block_device_mappings	(optional) Specify volumes to attach to the instance besides the volumes specified by the AMI	any	{}	no
capacity_reservation_specification	Targeting for EC2 capacity reservations	any	{}	no
cloudwatch_log_group_kms_key_id	(Optional) The ARN of the KMS Key to use when encrypting log data. Please note, after the AWS KMS CMK is disassociated from the log group, AWS CloudWatch Logs stops encrypting newly ingested data for the log group. All previously ingested data remains encrypted, and AWS CloudWatch Logs requires permissions for the CMK whenever the encrypted data is requested.	string	null	no
cloudwatch_log_group_retention_in_days	(Optional) Specifies the number of days you want to retain log events in the specified log group. Possible values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653, and 0. If you select 0, the events in the log group are always retained and never expire.	number	30	no
cluster_additional_security_group_ids	(optional) Additional Security Group IDs attached with EKS cluster.	list(string)	[]	no
cluster_addons	(optional) Cluster AddOn Config	any	{}	no
cluster_encryption_config	(Optional) Configuration block with encryption configuration for the cluster	list(any)	[]	no
cluster_encryption_policy_description	(Optional) Description of the cluster encryption policy created	string	"Cluster encryption policy to allow cluster role to utilize CMK provided"	no
cluster_encryption_policy_name	(Optional) Name to use on cluster encryption policy created	string	null	no
cluster_encryption_policy_path	(Optional) Cluster encryption policy path	string	null	no
cluster_encryption_policy_tags	(Optional) A map of additional tags to add to the cluster encryption policy created	map(string)	{}	no
cluster_force_detach_policies	(Optional) Whether to force detaching any policies the role has before destroying it.	bool	true	no
cluster_iam_role_additional_policies	(optional) List of additional policies arns attached to EKS cluster iam role	list(string)	[]	no
cluster_iam_role_description	(Optional) Description of the EKS cluster role.	string	"IAM role for EKS cluster role with required and optional additional iam policies"	no
cluster_iam_role_name	(Optional, Forces new resource) Friendly name of the role for EKS cluster. If omitted, fallback to interpolated name of cluster name and cluster suffix.	string	null	no
cluster_iam_role_path	(Optional) Path to the EKS cluster role	string	null	no
cluster_iam_role_permissions_boundary	(Optional) ARN of the policy that is used to set the permissions boundary for the EKS cluster role	string	null	no
cluster_iam_role_tags	(optional) Tags attached to iam resources for EKS cluster.	map(string)	{}	no
cluster_tags	(optional) Key-value map of cluster tags	map(string)	null	no
cluster_version	(Optional) Desired Kubernetes master version. If you do not specify a value, the latest available version at resource creation is used and no upgrades will occur except those automatically triggered by EKS. The value must be configured and increased to upgrade the version when desired. Downgrades are not supported by EKS	string	null	no
cpu_options	The CPU options for the instance	map(string)	{}	no
create_autoscaling_service_role	(optional) Whehter the service link role for autoscaling service exists or not ?	bool	false	no
create_cloudwatch_log_group	(optional) Whether or not to create the cloudwatch log group for EKS cluster?	bool	true	no
create_cluster_iam_role	Determines whether a an IAM role is created or to use an existing IAM role for EKS cluster	bool	true	no
create_eks_cluster	(optional) Whether or not to create a new EKS cluster or to use the existing one	bool	true	no
create_launch_template	Determines whether to create a launch template or not. If set to false, EKS will use its own default launch template	bool	true	no
create_node_group	(optional) Whether or not to create additional node group within the module	bool	true	no
create_node_group_iam_role	(optional) Whether or not to create iam role for node group	bool	true	no
credit_specification	Customize the credit specification of the instance	map(string)	{}	no
customer_master_key_spec	(Optional) Specifies whether the key contains a symmetric key or an asymmetric key pair and the encryption algorithms or signing algorithms that the key supports. Valid values: SYMMETRIC_DEFAULT, RSA_2048, RSA_3072, RSA_4096, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, or ECC_SECG_P256K1. Defaults to SYMMETRIC_DEFAULT	string	"SYMMETRIC_DEFAULT"	no
deletion_window_in_days	(Optional) Duration in days after which the key is deleted after destruction of the resource, must be between 7 and 30 days. Defaults to 30 days.	number	30	no
disable_api_termination	(optional) If true, enables EC2 instance termination protection	bool	null	no
ebs_optimized	(optional) If true, the launched EC2 instance(s) will be EBS-optimized	bool	null	no
elastic_gpu_specifications	(optional) The elastic GPU to attach to the instance	any	{}	no
elastic_inference_accelerator	(optional) Configuration block containing an Elastic Inference Accelerator to attach to the instance	map(string)	{}	no
enable_ec2_vpc_endpoint	(optional) Whether to enable ec2 vpc endpoint or not? Required if cluster is private and there is no existing ec2 vpc endpoint in the respective VPC.	bool	false	no
enable_ecr_api_vpc_endpoint	(optional) Whether to enable 'ecr.api' vpc endpoint or not? Required if cluster is private and there is no existing 'ecr.api' vpc endpoint in the respective VPC.	bool	false	no
enable_ecr_dkr_vpc_endpoint	(optional) Whether to enable 'ecr.dkr' vpc endpoint or not? Required if cluster is private and there is no existing 'ecr.dkr' vpc endpoint in the respective VPC.	bool	false	no
enable_elasticloadbalancing_vpc_endpoint	(optional) Whether to enable elasticloadbalancing vpc endpoint or not? Required if cluster is private and there is no existing elasticloadbalancing vpc endpoint in the respective VPC.	bool	false	no
enable_logs_vpc_endpoint	(optional) Whether to enable logs vpc endpoint or not? Required if cluster is private and there is no existing logs vpc endpoint in the respective VPC.	bool	false	no
enable_monitoring	(optional) Enables/disables detailed monitoring	bool	false	no
enable_s3_vpc_endpoint	(optional) Whether to enable s3 vpc endpoint or not? Required if cluster is private and there is no existing s3 vpc endpoint in the respective VPC.	bool	false	no
enable_sts_vpc_endpoint	(optional) Whether to enable sts vpc endpoint or not? Required if cluster is private and there is no existing sts vpc endpoint in the respective VPC.	bool	false	no
enabled_cluster_log_types	(Optional) List of the desired control plane logging to enable. For more information, see Amazon EKS Control Plane Logging	list(string)	null	no
enclave_options	(optional) Enable Nitro Enclaves on launched instances	map(string)	{}	no
endpoint_private_access	(Optional) Whether the Amazon EKS private API server endpoint is enabled. Default is false.	bool	null	no
endpoint_private_dns_enabled	(Optional) AWS services and AWS Marketplace partner services only) Whether or not to associate a private hosted zone with the specified VPC.	bool	false	no
endpoint_public_access	(Optional) Whether the Amazon EKS public API server endpoint is enabled. Default is true.	bool	null	no
endpoint_route_table_ids	(optional) Route table IDs for the S3 Gateway vpc endpoint. Required if cluster is private and s3 gateway endpoint is missing	list(string)	[]	no
endpoint_security_group_ids	(optional) List of security group ids for interface type vpc endpoint. Required if cluster is private and if any of the required endpoints are missing. Security groups should allow atleast 443 traffic within the subnets where EKS cluster is deployed	list(string)	[]	no
instance_market_options	(optional) The market (purchasing) option for the instance	any	{}	no
ip_family	(Optional) The IP family used to assign Kubernetes pod and service addresses. Valid values are ipv4 (default) and ipv6. You can only specify an IP family when you create a cluster, changing this value will force a new cluster to be created	string	null	no
kernel_id	The kernel ID	string	null	no
key_name	(optional) The key name that should be used for the instance(s)	string	null	no
key_usage	(Optional) Specifies the intended use of the key. Valid values: ENCRYPT_DECRYPT or SIGN_VERIFY. Defaults to ENCRYPT_DECRYPT.	string	"ENCRYPT_DECRYPT"	no
launch_template_default_version	(optional) Default version of the launch template	string	null	no
launch_template_name	(optional) Name of launch template to be created	string	null	no
launch_template_tags	(optional) A map of additional tags to add to the tag_specifications of launch template created	map(string)	{}	no
license_specifications	(optional) A map of license specifications to associate with	any	{}	no
maintenance_options	(optional) The maintenance options for the instance	any	{}	no
metadata_options	Customize the metadata options for the instance	map(string)	{ "http_endpoint": "enabled", "http_put_response_hop_limit": 2, "http_tokens": "required" }	no
network_interfaces	(optional) Customize network interfaces to be attached at instance boot time	list(any)	[]	no
node_group_force_detach_policies	(Optional) Whether to force detaching any policies the role has before destroying it.	bool	true	no
node_group_iam_role_additional_policies	(optional) Additional policies to be added to the IAM role for Node Group	list(string)	[]	no
node_group_iam_role_attach_cni_policy	(optional) 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_group_iam_role_description	(Optional) Description of the role.	string	"IAM role with required and optional additional iam policies for node group role"	no
node_group_iam_role_name	(Optional, Forces new resource) Friendly name of the role for EKS node group. If omitted, fallback to interpolated name of cluster name and node group suffix.	string	null	no
node_group_iam_role_path	(optional) Optional) Path to the node group role	string	null	no
node_group_iam_role_permissions_boundary	(optional) (Optional) ARN of the policy that is used to set the permissions boundary for the node group role	string	null	no
node_group_iam_role_tags	(optional) Tags attached to iam resources for Node Group	map(string)	{}	no
node_group_timeouts	(optional) Timeout config for EKS node groups	map(string)	{ "create": "15m", "delete": "45m", "update": "15m" }	no
node_groups	(optional) Additional node groups configuration	any	{}	no
placement	(optional) The placement of the instance	map(string)	{}	no
private_dns_name_options	(optional) The options for the instance hostname. The default values are inherited from the subnet	map(string)	{}	no
public_access_cidrs	(Optional) List of CIDR blocks. Indicates which CIDR blocks can access the Amazon EKS public API server endpoint when enabled. EKS defaults this to a list with 0.0.0.0/0. Terraform will only perform drift detection of its value when present in a configuration.	list(string)	null	no
ram_disk_id	(optional) The ID of the ram disk	string	null	no
role_arn	(Optional) ARN of the IAM role that provides permissions for the Kubernetes control plane to make calls to AWS API operations on your behalf. Ensure the resource configuration includes explicit dependencies on the IAM Role permissions by adding depends_on if using the aws_iam_role_policy resource or aws_iam_role_policy_attachment resource, otherwise EKS cannot delete EKS managed EC2 infrastructure such as Security Groups on EKS Cluster deletion	string	null	no
service_ipv4_cidr	(Optional) The CIDR block to assign Kubernetes pod and service IP addresses from. If you don't specify a block, Kubernetes assigns addresses from either the 10.100.0.0/16 or 172.20.0.0/16 CIDR blocks.for more info. refer Terraform Documentation	string	null	no
tags	(Optional) Key-value map of resource tags. If configured with a provider default_tags configuration block present, tags with matching keys will overwrite those defined at the provider-level	map(string)	null	no
timeouts	(optional) Timeout config for EKS cluster	map(string)	{ "create": "25m", "delete": "45m", "update": "25m" }	no
update_launch_template_default_version	(optional) Whether to update the launch templates default version on each update. Conflicts with launch_template_default_version	bool	true	no
use_launch_template	(optional) Whether to use the launch template with node groups or not?	bool	false	no
user_data	(Optional) The base64-encoded user data to provide when launching the instance.	string	null	no
vpc_security_group_ids	(optional) A list of security group IDs to associate	list(string)	[]	no

Outputs

Name	Description
cloudwatch_log_group_arn	The Amazon Resource Name (ARN) specifying the log group. Any :* suffix added by the API, denoting all CloudWatch Log Streams under the CloudWatch Log Group, is removed for greater compatibility with other AWS services that do not accept the suffix.
eks_cluster_arn	ARN of the cluster.
eks_cluster_certificate_authority	Attribute block containing certificate-authority-data for your cluster. Detailed below.
eks_cluster_created_at	Unix epoch timestamp in seconds for when the cluster was created.
eks_cluster_endpoint	Endpoint for your Kubernetes API server.
eks_cluster_id	Name of the cluster.
eks_cluster_identity	Attribute block containing identity provider information for your cluster. Only available on Kubernetes version 1.13 and 1.14 clusters created or upgraded on or after September 3, 2019. Detailed below.
eks_cluster_name	Name of the eks cluster
eks_cluster_oidc_issuer	Issuer URL for the OpenID Connect identity provider.
eks_cluster_open_id_provider_arn	ARN of the Open-ID provider configurred for the cluster
eks_cluster_platform_version	Platform version for the cluster.
eks_cluster_primary_security_group_id	Primary security group id of the EKS cluster
eks_cluster_status	Status of the EKS cluster. One of CREATING, ACTIVE, DELETING, FAILED.
eks_cluster_tags_all	Map of tags assigned to the resource, including those inherited from the provider default_tags configuration block.
eks_cluster_vpc_config	Configuration block argument that also includes attributes for the VPC associated with your cluster. Detailed below.
global_encryption_kms_key_arn	KMS Key arn used by node groups and the the eks cluster for encryption.
node_group_arn	Amazon Resource Name (ARN) of the EKS Node Group.
node_group_id	EKS Cluster name and EKS Node Group name separated by a colon (:).
node_group_resources	List of objects containing information about underlying resources.
node_group_role_arn	IAM Role Arn used by node groups in the eks cluster
node_group_status	Status of the EKS Node Group.
node_group_tags_all	A map of tags assigned to the resource, including those inherited from the provider default_tags configuration block.

License

MIT License. See LICENSE for full details.