A terraform module to create a managed Kubernetes cluster on AWS EKS. Available through the Terraform registry. Inspired by and adapted from this doc and its source code. Read the AWS docs on EKS to get connected to the k8s dashboard.

• You want to create an EKS cluster and an autoscaling group of workers for the cluster.
• You want these resources to exist within security groups that allow communication and coordination. These can be user provided or created within the module.
• You've created a Virtual Private Cloud (VPC) and subnets where you intend to put the EKS resources. The VPC satisfies EKS requirements.
• If manage_aws_auth = true, it's required that both kubectl (>=1.10) and aws-iam-authenticator are installed and on your shell's PATH.

A full example leveraging other community modules is contained in the examples/basic directory.

data "aws_eks_cluster" "cluster" {
  name = module.my-cluster.cluster_id
}

data "aws_eks_cluster_auth" "cluster" {
  name = module.my-cluster.cluster_id
}

provider "kubernetes" {
  host                   = data.aws_eks_cluster.cluster.endpoint
  cluster_ca_certificate = base64decode(data.aws_eks_cluster.cluster.certificate_authority.0.data)
  token                  = data.aws_eks_cluster_auth.cluster.token
  load_config_file       = false
  version                = "~> 1.9"
}

module "my-cluster" {
  source          = "terraform-aws-modules/eks/aws"
  cluster_name    = "my-cluster"
  cluster_version = "1.14"
  subnets         = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]
  vpc_id          = "vpc-1234556abcdef"

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

Sometimes you need to have a way to create EKS resources conditionally but Terraform does not allow to use count inside module block, so the solution is to specify argument create_eks.

Using this feature and having manage_aws_auth=true (the default) requires to set up the kubernetes provider in a way that allows the data sources to not exist.

data "aws_eks_cluster" "cluster" {
  count = var.create_eks ? 1 : 0
  name  = module.eks.cluster_id
}

data "aws_eks_cluster_auth" "cluster" {
  count = var.create_eks ? 1 : 0
  name  = module.eks.cluster_id
}

# In case of not creating the cluster, this will be an incompletely configured, unused provider, which poses no problem.
provider "kubernetes" {
  host                   = element(concat(data.aws_eks_cluster.cluster[*].endpoint, list("")), 0)
  cluster_ca_certificate = base64decode(element(concat(data.aws_eks_cluster.cluster[*].certificate_authority.0.data, list("")), 0))
  token                  = element(concat(data.aws_eks_cluster_auth.cluster[*].token, list("")), 0)
  load_config_file       = false
  version                = "~> 1.10"
}

# This cluster will not be created
module "eks" {
  source = "terraform-aws-modules/eks/aws"

  create_eks = false
  # ... omitted
}

• 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

This module has been packaged with awspec tests through kitchen and kitchen-terraform. To run them:

1. Install rvm and the ruby version specified in the Gemfile.

2. Install bundler and the gems from our Gemfile:

   gem install bundler && bundle install

3. Ensure your AWS environment is configured (i.e. credentials and region) for test.

4. Test using bundle exec kitchen test from the root of the repo.

For now, connectivity to the kubernetes cluster is not tested but will be in the future. Once the test fixture has converged, you can query the test cluster from that terminal session with

kubectl get nodes --watch --kubeconfig kubeconfig

(using default settings config_output_path = "./" & write_kubeconfig = true)

Code formatting and documentation for variables and outputs is generated using pre-commit-terraform hooks which uses terraform-docs.

Follow these instructions to install pre-commit locally.

And install terraform-docs with go get github.com/segmentio/terraform-docs or brew install terraform-docs.

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

Full contributing guidelines are covered here.

The changelog captures all important release notes.

Created by Brandon O'Connor - [email protected]. Maintained by Max Williams and Thierno IB. BARRY. Many thanks to the contributors listed here!

MIT Licensed. See LICENSE for full details.