Provision an EKS Cluster (AWS)

AWS's Elastic Kubernetes Service (EKS) is a managed service that lets you deploy, manage, and scale containerized applications on Kubernetes.

In this tutorial, you will deploy an EKS cluster using Terraform. Then, you will configure kubectl using Terraform output and verify that your cluster is ready to use.

Why deploy with Terraform?

While you could use the built-in AWS provisioning processes (UI, CLI, CloudFormation) for EKS clusters, Terraform provides you with several benefits:

• Unified Workflow - If you are already deploying infrastructure to AWS with Terraform, your EKS cluster can fit into that workflow. You can also deploy applications into your EKS cluster using Terraform.

• Full Lifecycle Management - Terraform doesn't only create resources, it updates, and deletes tracked resources without requiring you to inspect the API to identify those resources.

• Graph of Relationships - Terraform understands dependency relationships between resources. For example, if an AWS Kubernetes cluster needs a specific VPC and subnet configurations, Terraform won't attempt to create the cluster if the VPC and subnets failed to create with the proper configuration.

Prerequisites

The tutorial assumes some basic familiarity with Kubernetes and kubectl but does not assume any pre-existing deployment.

It also assumes that you are familiar with the usual Terraform plan/apply workflow. If you're new to Terraform itself, refer first to the Getting Started tutorial.

For this tutorial, you will need:

• an AWS account
• the AWS CLI, installed and configured
• AWS IAM Authenticator
• the Kubernetes CLI, also known as kubectl

Set up and initialize your Terraform workspace

In your terminal, clone the following repository. It contains the example configuration used in this tutorial.

$ git clone https://github.com/hashicorp/learn-terraform-provision-eks-cluster

$ git clone https://github.com/hashicorp/learn-terraform-provision-eks-cluster

Change into the repository directory.

$ cd learn-terraform-provision-eks-cluster

$ cd learn-terraform-provision-eks-cluster

This example repository contains configuration to provision a VPC, security groups, and an EKS cluster. The diagram below shows the architecture this configuration defines:

The configuration is organized across multiple files:

1. versions.tf sets the Terraform version to at least 1.2. It also sets versions for the providers used by the configuration.

2. variables.tf contains a region variable that controls where to create the EKS cluster

3. vpc.tf provisions a VPC, subnets, and availability zones using the AWS VPC Module. The module creates a new VPC for this tutorial so it doesn't impact your existing cloud environment and resources.

4. security-groups.tf provisions the security groups the EKS cluster will use

5. eks-cluster.tf uses the AWS EKS Module to provision an EKS Cluster and other required resources, including Auto Scaling Groups, Security Groups, IAM Roles, and IAM Policies.

   Open the eks-cluster.tf file to review the configuration. The eks_managed_node_groups parameter will create three nodes across two node groups.

   eks_managed_node_groups = {
    one = {
      name = "node-group-1"
   
      instance_types = ["t3.small"]
   
      min_size     = 1
      max_size     = 3
      desired_size = 2
   
      pre_bootstrap_user_data = <<-EOT
      echo 'foo bar'
      EOT
   
      vpc_security_group_ids = [
        aws_security_group.node_group_one.id
      ]
    }
   
    two = {
      name = "node-group-2"
   
      instance_types = ["t3.medium"]
   
      min_size     = 1
      max_size     = 2
      desired_size = 1
   
      pre_bootstrap_user_data = <<-EOT
      echo 'foo bar'
      EOT
   
      vpc_security_group_ids = [
        aws_security_group.node_group_two.id
      ]
    }
   }
   
   

   eks-cluster.tf

   eks_managed_node_groups = {
    one = {
      name = "node-group-1"
   
      instance_types = ["t3.small"]
   
      min_size     = 1
      max_size     = 3
      desired_size = 2
   
      pre_bootstrap_user_data = <<-EOT
      echo 'foo bar'
      EOT
   
      vpc_security_group_ids = [
        aws_security_group.node_group_one.id
      ]
    }
   
    two = {
      name = "node-group-2"
   
      instance_types = ["t3.medium"]
   
      min_size     = 1
      max_size     = 2
      desired_size = 1
   
      pre_bootstrap_user_data = <<-EOT
      echo 'foo bar'
      EOT
   
      vpc_security_group_ids = [
        aws_security_group.node_group_two.id
      ]
    }
   }
   
   

6. outputs.tf defines the output values for this configuration.

Initialize Terraform workspace

Initialize your configuration.

$ terraform init
Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/eks/aws 18.26.6 for eks...
- eks in .terraform/modules/eks
- eks.eks_managed_node_group in .terraform/modules/eks/modules/eks-managed-node-group
- eks.eks_managed_node_group.user_data in .terraform/modules/eks/modules/_user_data
- eks.fargate_profile in .terraform/modules/eks/modules/fargate-profile
Downloading registry.terraform.io/terraform-aws-modules/kms/aws 1.0.2 for eks.kms...
- eks.kms in .terraform/modules/eks.kms
- eks.self_managed_node_group in .terraform/modules/eks/modules/self-managed-node-group
- eks.self_managed_node_group.user_data in .terraform/modules/eks/modules/_user_data
Downloading registry.terraform.io/terraform-aws-modules/vpc/aws 3.14.2 for vpc...
- vpc in .terraform/modules/vpc

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/cloudinit versions matching ">= 2.0.0"...
- Finding hashicorp/aws versions matching ">= 3.63.0, >= 3.72.0, ~> 4.15.0"...
- Finding hashicorp/random versions matching "3.1.0"...
- Finding hashicorp/kubernetes versions matching ">= 2.10.0"...
- Finding hashicorp/tls versions matching "~> 3.0"...
- Installing hashicorp/cloudinit v2.2.0...
- Installed hashicorp/cloudinit v2.2.0 (signed by HashiCorp)
- Installing hashicorp/aws v4.15.1...
- Installed hashicorp/aws v4.15.1 (signed by HashiCorp)
- Installing hashicorp/random v3.1.0...
- Installed hashicorp/random v3.1.0 (signed by HashiCorp)
- Installing hashicorp/kubernetes v2.12.1...
- Installed hashicorp/kubernetes v2.12.1 (signed by HashiCorp)
- Installing hashicorp/tls v3.4.0...
- Installed hashicorp/tls v3.4.0 (signed by HashiCorp)

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

$ terraform init
Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/eks/aws 18.26.6 for eks...
- eks in .terraform/modules/eks
- eks.eks_managed_node_group in .terraform/modules/eks/modules/eks-managed-node-group
- eks.eks_managed_node_group.user_data in .terraform/modules/eks/modules/_user_data
- eks.fargate_profile in .terraform/modules/eks/modules/fargate-profile
Downloading registry.terraform.io/terraform-aws-modules/kms/aws 1.0.2 for eks.kms...
- eks.kms in .terraform/modules/eks.kms
- eks.self_managed_node_group in .terraform/modules/eks/modules/self-managed-node-group
- eks.self_managed_node_group.user_data in .terraform/modules/eks/modules/_user_data
Downloading registry.terraform.io/terraform-aws-modules/vpc/aws 3.14.2 for vpc...
- vpc in .terraform/modules/vpc

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/cloudinit versions matching ">= 2.0.0"...
- Finding hashicorp/aws versions matching ">= 3.63.0, >= 3.72.0, ~> 4.15.0"...
- Finding hashicorp/random versions matching "3.1.0"...
- Finding hashicorp/kubernetes versions matching ">= 2.10.0"...
- Finding hashicorp/tls versions matching "~> 3.0"...
- Installing hashicorp/cloudinit v2.2.0...
- Installed hashicorp/cloudinit v2.2.0 (signed by HashiCorp)
- Installing hashicorp/aws v4.15.1...
- Installed hashicorp/aws v4.15.1 (signed by HashiCorp)
- Installing hashicorp/random v3.1.0...
- Installed hashicorp/random v3.1.0 (signed by HashiCorp)
- Installing hashicorp/kubernetes v2.12.1...
- Installed hashicorp/kubernetes v2.12.1 (signed by HashiCorp)
- Installing hashicorp/tls v3.4.0...
- Installed hashicorp/tls v3.4.0 (signed by HashiCorp)

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Provision the EKS cluster

Run terraform apply to create your cluster and other necessary resources. Confirm the operation with a yes.

This process should take approximately 10 minutes. Upon completion, Terraform will print your configuration's outputs.

$ terraform apply

## ...

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create
 <= read (data resources)

Terraform will perform the following actions:

## ...

Plan: 56 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + cluster_endpoint          = (known after apply)
  + cluster_id                = (known after apply)
  + cluster_name              = (known after apply)
  + cluster_security_group_id = (known after apply)
  + region                    = "us-east-2"

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes
  
## ...

Apply complete! Resources: 56 added, 0 changed, 0 destroyed.

Outputs:

cluster_endpoint = "https://128CA2A0D737317D36E31D0D3A0C366B.gr7.us-east-2.eks.amazonaws.com"
cluster_id = "education-eks-IKQYD53K"
cluster_name = "education-eks-IKQYD53K"
cluster_security_group_id = "sg-0f836e078948afb70"
region = "us-east-2"

$ terraform apply

## ...

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create
 <= read (data resources)

Terraform will perform the following actions:

## ...

Plan: 56 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + cluster_endpoint          = (known after apply)
  + cluster_id                = (known after apply)
  + cluster_name              = (known after apply)
  + cluster_security_group_id = (known after apply)
  + region                    = "us-east-2"

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes
  
## ...

Apply complete! Resources: 56 added, 0 changed, 0 destroyed.

Outputs:

cluster_endpoint = "https://128CA2A0D737317D36E31D0D3A0C366B.gr7.us-east-2.eks.amazonaws.com"
cluster_id = "education-eks-IKQYD53K"
cluster_name = "education-eks-IKQYD53K"
cluster_security_group_id = "sg-0f836e078948afb70"
region = "us-east-2"

Configure kubectl

Now that you've provisioned your EKS cluster, you need to configure kubectl.

First, open the outputs.tf file to review the output values. You will use the region and cluster_name outputs to configure kubectl.

output "cluster_id" {
  description = "EKS cluster ID"
  value       = module.eks.cluster_id
}

output "cluster_endpoint" {
  description = "Endpoint for EKS control plane"
  value       = module.eks.cluster_endpoint
}

output "cluster_security_group_id" {
  description = "Security group ids attached to the cluster control plane"
  value       = module.eks.cluster_security_group_id
}

output "region" {
  description = "AWS region"
  value       = var.region
}

output "cluster_name" {
  description = "Kubernetes Cluster Name"
  value       = local.cluster_name
}

output "cluster_id" {
  description = "EKS cluster ID"
  value       = module.eks.cluster_id
}

output "cluster_endpoint" {
  description = "Endpoint for EKS control plane"
  value       = module.eks.cluster_endpoint
}

output "cluster_security_group_id" {
  description = "Security group ids attached to the cluster control plane"
  value       = module.eks.cluster_security_group_id
}

output "region" {
  description = "AWS region"
  value       = var.region
}

output "cluster_name" {
  description = "Kubernetes Cluster Name"
  value       = local.cluster_name
}

Run the following command to retrieve the access credentials for your cluster and configure kubectl.

$ aws eks --region $(terraform output -raw region) update-kubeconfig \
    --name $(terraform output -raw cluster_name)

$ aws eks --region $(terraform output -raw region) update-kubeconfig \
    --name $(terraform output -raw cluster_name)

You can now use kubectl to manage your cluster and deploy Kubernetes configurations to it.

Verify the Cluster

Use kubectl commands to verify your cluster configuration.

First, get information about the cluster.

$ kubectl cluster-info
Kubernetes control plane is running at https://128CA2A0D737317D36E31D0D3A0C366B.gr7.us-east-2.eks.amazonaws.com
CoreDNS is running at https://128CA2A0D737317D36E31D0D3A0C366B.gr7.us-east-2.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

$ kubectl cluster-info
Kubernetes control plane is running at https://128CA2A0D737317D36E31D0D3A0C366B.gr7.us-east-2.eks.amazonaws.com
CoreDNS is running at https://128CA2A0D737317D36E31D0D3A0C366B.gr7.us-east-2.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Notice that the Kubernetes control plane location matches the cluster_endpoint value from the terraform apply output above.

Now verify that all three worker nodes are part of the cluster.

$ kubectl get nodes
NAME                                       STATUS   ROLES    AGE   VERSION
ip-10-0-1-79.us-east-2.compute.internal    Ready    <none>   91m   v1.22.9-eks-810597c
ip-10-0-2-107.us-east-2.compute.internal   Ready    <none>   92m   v1.22.9-eks-810597c
ip-10-0-3-176.us-east-2.compute.internal   Ready    <none>   91m   v1.22.9-eks-810597c

$ kubectl get nodes
NAME                                       STATUS   ROLES    AGE   VERSION
ip-10-0-1-79.us-east-2.compute.internal    Ready    <none>   91m   v1.22.9-eks-810597c
ip-10-0-2-107.us-east-2.compute.internal   Ready    <none>   92m   v1.22.9-eks-810597c
ip-10-0-3-176.us-east-2.compute.internal   Ready    <none>   91m   v1.22.9-eks-810597c

You have verified that you can connect to your cluster using kubectl and that all three worker nodes are healthy. Your cluster is ready to use.

Clean up your workspace

You have now provisioned an EKS cluster, configured kubectl, and verified that your cluster is ready to use.

If you'd like to learn how to manage your EKS cluster using the Terraform Kubernetes Provider, leave your cluster running and continue to the Kubernetes provider tutorial.

Destroy any resources you create when you are done with this tutorial. Run terraform destroy and confirm with yes in your terminal.

$ terraform destroy

## ...

Plan: 0 to add, 0 to change, 56 to destroy.

Changes to Outputs:
  - cluster_endpoint          = "https://128CA2A0D737317D36E31D0D3A0C366B.gr7.us-east-2.eks.amazonaws.com" -> null
  - cluster_id                = "education-eks-IKQYD53K" -> null
  - cluster_name              = "education-eks-IKQYD53K" -> null
  - cluster_security_group_id = "sg-0f836e078948afb70" -> null
  - region                    = "us-east-2" -> null

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

## ...

Destroy complete! Resources: 56 destroyed.

$ terraform destroy

## ...

Plan: 0 to add, 0 to change, 56 to destroy.

Changes to Outputs:
  - cluster_endpoint          = "https://128CA2A0D737317D36E31D0D3A0C366B.gr7.us-east-2.eks.amazonaws.com" -> null
  - cluster_id                = "education-eks-IKQYD53K" -> null
  - cluster_name              = "education-eks-IKQYD53K" -> null
  - cluster_security_group_id = "sg-0f836e078948afb70" -> null
  - region                    = "us-east-2" -> null

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

## ...

Destroy complete! Resources: 56 destroyed.

Next steps

For more information on the EKS module, visit the EKS module page in the Terraform Registry.

To learn how to manage Kubernetes resources, your EKS cluster, or existing Kubernetes clusters, visit the Kubernetes provider tutorial.

For a more in-depth Kubernetes example, see Deploy Consul and Vault on a Kubernetes Cluster using Run Triggers (this tutorial is GKE based).