Example: EKS Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the architecture and components of a typical "EKS Getting Started" example for the Terraform AWS Provider. The primary goal of this example is to provision a foundational Amazon EKS (Elastic Kubernetes Service) cluster, including the control plane, worker nodes, and the necessary networking and security infrastructure. It serves as a template for deploying containerized applications on AWS using Kubernetes managed by Terraform.
As the specific files for the EKS example were not fully available, this analysis draws heavily from analogous patterns found in the ecs-alb example, which shares fundamental AWS components like VPC, EC2, Auto Scaling, and IAM. This is supplemented with information from the provider's internal documentation for the EKS, EC2, and KMS services.
Sources: examples/ecs-alb/main.tf, internal/service/eks/README.md, internal/service/ec2/README.md
High-Level Architecture
The EKS example provisions several core AWS resources that work together to form a complete Kubernetes cluster. The main components are the EKS Control Plane, the Worker Nodes (managed by an Auto Scaling Group), and the underlying VPC network that facilitates communication.
The following diagram illustrates the relationship between these major components.
This diagram shows the EKS Control Plane managing the Worker Node Auto Scaling Group within a VPC, with both components relying on specific IAM roles for permissions.
Sources: examples/ecs-alb/main.tf:15-50, examples/ecs-alb/main.tf:205-270, internal/service/eks/README.md
Core Components
Networking (vpc.tf)
A dedicated Virtual Private Cloud (VPC) is the foundation of the EKS cluster, providing a logically isolated network environment. This setup typically includes:
- VPC: The main network space, defined by a CIDR block (e.g.,
10.10.0.0/16). - Subnets: The VPC is divided into smaller subnets across multiple Availability Zones for high availability. Both public and private subnets are usually created.
- Internet Gateway: Attached to the VPC to allow communication between resources in the VPC and the internet.
- Route Tables: Control the flow of traffic, with routes directing internet-bound traffic through the Internet Gateway.
The following resources are analogous to what would be found in an EKS networking configuration:
| Resource | Purpose |
|---|---|
aws_vpc | Creates the virtual private cloud. |
aws_subnet | Creates subnets within the VPC. |
aws_internet_gateway | Provides internet access to the VPC. |
aws_route_table | Defines routing rules for traffic. |
aws_route_table_association | Associates subnets with a route table. |
Sources: examples/ecs-alb/main.tf:15-39
EKS Control Plane (eks-cluster.tf)
This part of the configuration defines the managed Kubernetes control plane using the aws_eks_cluster resource. The control plane is responsible for managing the state of the cluster, scheduling pods, and storing cluster data.
Key configuration elements include:
- IAM Role: An
aws_iam_roleis required for the EKS service to manage AWS resources on your behalf, such as EC2 instances and Elastic Load Balancers. - VPC Configuration: The
vpc_configblock links the cluster to the pre-defined VPC and subnets. - Kubernetes Version: Specifies the desired version of Kubernetes.
- Encryption: Optionally, an
aws_kms_keycan be provided to enable envelope encryption for Kubernetes secrets, adding a layer of security.
Sources: internal/service/eks/README.md, internal/service/kms/README.md, examples/ecs-alb/main.tf:205-222
EKS Worker Nodes (eks-worker-nodes.tf)
Worker nodes are the EC2 instances where your containerized applications run. These are typically managed as a group using either the aws_eks_node_group resource or a combination of aws_autoscaling_group and aws_launch_configuration/aws_launch_template. The ecs-alb example uses the latter pattern, which is detailed below.
The following diagram shows the components involved in creating worker nodes.
This diagram shows how an Auto Scaling Group uses a Launch Configuration to define the properties of the EC2 instances it manages, including their IAM profile, security group, and AMI.
Sources: examples/ecs-alb/main.tf:43-50, examples/ecs-alb/main.tf:97-113, internal/service/ec2/README.md
Key Worker Node Resources
aws_launch_configuration: Defines the template for the worker node instances. This includes:image_id: The AMI ID for the EKS-optimized Amazon Linux 2 OS.instance_type: The EC2 instance size (e.g.,t3.medium).iam_instance_profile: The IAM profile that grants the node permissions to communicate with the EKS control plane.user_data: A script that runs on instance launch to register the node with the EKS cluster.security_groups: Associates security groups to control network traffic.
aws_autoscaling_group: Manages the lifecycle of the worker nodes. It ensures the desired number of instances are running, distributes them across Availability Zones, and handles scaling and replacement of unhealthy nodes.aws_iam_role(for Nodes): A dedicated IAM role for the worker nodes. The policies attached to this role grant permissions required by thekubeletto interact with AWS APIs (e.g., ECR for pulling images).
Sources: examples/ecs-alb/main.tf:43-113, examples/ecs-alb/main.tf:252-270
IAM Roles and Policies
Proper IAM configuration is critical for EKS. The example requires at least two primary roles.
| Role | Purpose | Analogous Example |
|---|---|---|
| EKS Cluster Role | Allows the EKS service (eks.amazonaws.com) to manage AWS resources like networking interfaces on behalf of the cluster. | aws_iam_role.ecs_service |
| EKS Node Role | Assumed by the EC2 worker nodes (ec2.amazonaws.com) to allow them to connect to the control plane and perform actions like pulling container images from ECR. | aws_iam_role.app_instance |
Below is a sample structure for an IAM role, based on the ecs-alb example, which would be adapted for EKS by changing the service principal.
# This is an example for an ECS service, but the structure is the same for EKS.
# The principal "Service" would be "eks.amazonaws.com" for an EKS cluster role.
resource "aws_iam_role" "ecs_service" {
name = "tf_example_ecs_role"
assume_role_policy = <<EOF
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "ecs.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
}
Sources: examples/ecs-alb/main.tf:205-222
Conclusion
The "EKS Getting Started" example demonstrates the power of Terraform for declaratively provisioning a complete, production-ready Kubernetes cluster on AWS. By defining networking, control plane, and worker node resources as code, it provides a repeatable and version-controlled foundation for running containerized workloads. The use of distinct modules for networking, cluster, and workers promotes reusability and separation of concerns, which are best practices for managing infrastructure as code. The provider's roadmap also indicates ongoing enhancements to related services, ensuring continued support for modern cloud-native architectures.
Sources: README.md, ROADMAP.md