AWS EKS Terraform module

Terraform module which creates AWS EKS (Kubernetes) resources

Documentation

• Frequently Asked Questions
• Compute Resources
• IRSA Integration
• User Data
• Network Connectivity
• Upgrade Guides
  • Upgrade to v17.x
  • Upgrade to v18.x
  • Upgrade to v19.x

External Documentation

Please note that we strive to provide a comprehensive suite of documentation for configuring and utilizing the module(s) defined here, and that documentation regarding EKS (including EKS managed node group, self managed node group, and Fargate profile) and/or Kubernetes features, usage, etc. are better left up to their respective sources:

• AWS EKS Documentation
• Kubernetes Documentation

Reference Architecture

The examples provided under examples/ provide a comprehensive suite of configurations that demonstrate nearly all of the possible different configurations and settings that can be used with this module. However, these examples are not representative of clusters that you would normally find in use for production workloads. For reference architectures that utilize this module, please see the following:

• EKS Reference Architecture

Available Features

• AWS EKS Cluster Addons
• AWS EKS Identity Provider Configuration
• AWS EKS on Outposts support
• All node types are supported:
  • EKS Managed Node Group
  • Self Managed Node Group
  • Fargate Profile
• Support for creating Karpenter related AWS infrastructure resources (e.g. IAM roles, SQS queue, EventBridge rules, etc.)
• Support for custom AMI, custom launch template, and custom user data including custom user data template
• Support for Amazon Linux 2 EKS Optimized AMI and Bottlerocket nodes
  • Windows based node support is limited to a default user data template that is provided due to the lack of Windows support and manual steps required to provision Windows based EKS nodes
• Support for module created security group, bring your own security groups, as well as adding additional security group rules to the module created security group(s)
• Support for creating node groups/profiles separate from the cluster through the use of sub-modules (same as what is used by root module)
• Support for node group/profile "default" settings - useful for when creating multiple node groups/Fargate profiles where you want to set a common set of configurations once, and then individually control only select features on certain node groups/profiles

IRSA Terraform Module

An IAM role for service accounts (IRSA) sub-module has been created to make deploying common addons/controllers easier. Instead of users having to create a custom IAM role with the necessary federated role assumption required for IRSA plus find and craft the associated policy required for the addon/controller, users can create the IRSA role and policy with a few lines of code. See the terraform-aws-iam/examples/iam-role-for-service-accounts directory for examples on how to use the IRSA sub-module in conjunction with this (terraform-aws-eks) module.

Some of the addon/controller policies that are currently supported include:

• Cert-Manager
• Cluster Autoscaler
• EBS CSI Driver
• EFS CSI Driver
• External DNS
• External Secrets
• FSx for Lustre CSI Driver
• Karpenter
• Load Balancer Controller
  • Load Balancer Controller Target Group Binding Only
• App Mesh Controller
  • App Mesh Envoy Proxy
• Managed Service for Prometheus
• Node Termination Handler
• Velero
• VPC CNI

See terraform-aws-iam/modules/iam-role-for-service-accounts for current list of supported addon/controller policies as more are added to the project.

Usage

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 19.0"

  cluster_name    = "my-cluster"
  cluster_version = "1.27"

  cluster_endpoint_public_access  = true

  cluster_addons = {
    coredns = {
      most_recent = true
    }
    kube-proxy = {
      most_recent = true
    }
    vpc-cni = {
      most_recent = true
    }
  }

  vpc_id                   = "vpc-1234556abcdef"
  subnet_ids               = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]
  control_plane_subnet_ids = ["subnet-xyzde987", "subnet-slkjf456", "subnet-qeiru789"]

  # Self Managed Node Group(s)
  self_managed_node_group_defaults = {
    instance_type                          = "m6i.large"
    update_launch_template_default_version = true
    iam_role_additional_policies = {
      AmazonSSMManagedInstanceCore = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
    }
  }

  self_managed_node_groups = {
    one = {
      name         = "mixed-1"
      max_size     = 5
      desired_size = 2

      use_mixed_instances_policy = true
      mixed_instances_policy = {
        instances_distribution = {
          on_demand_base_capacity                  = 0
          on_demand_percentage_above_base_capacity = 10
          spot_allocation_strategy                 = "capacity-optimized"
        }

        override = [
          {
            instance_type     = "m5.large"
            weighted_capacity = "1"
          },
          {
            instance_type     = "m6i.large"
            weighted_capacity = "2"
          },
        ]
      }
    }
  }

  # EKS Managed Node Group(s)
  eks_managed_node_group_defaults = {
    instance_types = ["m6i.large", "m5.large", "m5n.large", "m5zn.large"]
  }

  eks_managed_node_groups = {
    blue = {}
    green = {
      min_size     = 1
      max_size     = 10
      desired_size = 1

      instance_types = ["t3.large"]
      capacity_type  = "SPOT"
    }
  }

  # Fargate Profile(s)
  fargate_profiles = {
    default = {
      name = "default"
      selectors = [
        {
          namespace = "default"
        }
      ]
    }
  }

  # aws-auth configmap
  manage_aws_auth_configmap = true

  aws_auth_roles = [
    {
      rolearn  = "arn:aws:iam::66666666666:role/role1"
      username = "role1"
      groups   = ["system:masters"]
    },
  ]

  aws_auth_users = [
    {
      userarn  = "arn:aws:iam::66666666666:user/user1"
      username = "user1"
      groups   = ["system:masters"]
    },
    {
      userarn  = "arn:aws:iam::66666666666:user/user2"
      username = "user2"
      groups   = ["system:masters"]
    },
  ]

  aws_auth_accounts = [
    "777777777777",
    "888888888888",
  ]

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

Examples

• Complete: EKS Cluster using all available node group types in various combinations demonstrating many of the supported features and configurations
• EKS Managed Node Group: EKS Cluster using EKS managed node groups
• Fargate Profile: EKS cluster using Fargate Profiles
• Karpenter: EKS Cluster with Karpenter provisioned for intelligent data plane management
• Outposts: EKS local cluster provisioned on AWS Outposts
• Self Managed Node Group: EKS Cluster using self-managed node groups
• User Data: Various supported methods of providing necessary bootstrap scripts and configuration settings via user data

Contributing

We are grateful to the community for contributing bugfixes and improvements! Please see below to learn how you can take part.

• Code of Conduct
• Contributing Guide

Requirements

Providers

Modules

Resources

Inputs

[
  "audit",
  "api",
  "authenticator"
]

{
  "resources": [
    "secrets"
  ]
}

[
  "0.0.0.0/0"
]

Outputs

License

Apache 2 Licensed. See LICENSE for full details.

Additional information for users from Russia and Belarus

• Russia has illegally annexed Crimea in 2014 and brought the war in Donbas followed by full-scale invasion of Ukraine in 2022.
• Russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee.
• Putin khuylo!