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.
Warning! AWS charges $0.10 per hour for each EKS cluster, so you may be charged to run this tutorial. The cost should be a few dollars at most, but be sure to delete your infrastructure promptly to avoid incurring additional charges. We are not responsible for any charges you may incur.
»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.
Change into the repository directory.
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:
versions.tfsets the Terraform version to at least 1.2. It also sets versions for the providers used by the configuration.variables.tfcontains aregionvariable that controls where to create the EKS clustervpc.tfprovisions 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.security-groups.tfprovisions the security groups the EKS cluster will useeks-cluster.tfuses 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.tffile to review the configuration. Theeks_managed_node_groupsparameter will create three nodes across two node groups.eks-cluster.tfoutputs.tfdefines the output values for this configuration.
»Initialize Terraform workspace
Initialize your configuration.
»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.
»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.
Run the following command to retrieve the access credentials for your cluster
and configure kubectl.
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.
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.
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 Learn tutorial.
Note: The repository you used in this tutorial only contains Terraform configuration concerned with creating an EKS cluster. You can also use Terraform to manage the Kubernetes objects deployed to a cluster, such as Deployments and Services. We recommend that you keep the Terraform configuration for each of those concerns separate, since their workflows and owners often differ.
Destroy any resources you create when you are done with this
tutorial. Run terraform destroy and confirm with yes in your terminal.
»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 Learn 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).
