Orchestrating Amazon EKS Clusters with Terraform and eksctl: A Comprehensive Technical Guide

Managing Kubernetes infrastructure on Amazon Web Services presents a unique set of challenges for DevOps engineers and platform architects. While the native AWS Provider for Terraform offers granular control over every underlying AWS resource, the process of provisioning an EKS cluster, configuring VPCs, implementing node groups, and managing IAM permissions is notoriously verbose and error-prone. Conversely, eksctl, the open-source Kubernetes distribution by the eksctl authors, simplifies cluster creation with minimal configuration but historically lacked the robust state management, incremental updates, and infrastructure-as-code integration capabilities required for production-grade environments. The terraform-provider-eksctl bridges this gap effectively, allowing users to leverage the speed and simplicity of eksctl while retaining the rigor, auditability, and incremental update capabilities of Terraform. This integration eliminates the need for complex glue scripts that generate eksctl YAML files from Terraform templates, offering a seamless method to bring up entire infrastructures with a single terraform apply command.

Architecture and Core Philosophy

The fundamental design of terraform-provider-eksctl is rooted in wrapping the eksctl binary within a Terraform provider. This approach avoids the need for a separate "management" Kubernetes cluster, which is often required in other complex GitOps patterns. By storing state directly in the Terraform state file, the provider leverages existing automation pipelines such as Atlantis, Terraform Enterprise, CircleCI, or GitHub Actions. The provider essentially acts as a sophisticated interface that translates Terraform resource definitions into eksctl commands.

The primary benefit of this architecture is the decoupling of cluster management logic from the raw AWS API calls. When a user defines an eksctl_cluster resource, the provider does not interact directly with AWS APIs to create individual resources like subnets or security groups. Instead, it invokes eksctl to perform the creation. This ensures that the cluster configuration aligns exactly with what is declared in the Terraform file, while eksctl handles the complex orchestration of the numerous AWS resources involved. For operations such as deletion, the provider employs high-availability-safe practices, specifically using eksctl delete nodegroup --drain to ensure workloads are evicted before nodes are terminated, preventing service disruption during teardown.

Installation and Provider Configuration

Configuring the provider depends heavily on the version of Terraform being used. For modern environments running Terraform 0.13 and later, the provider is available on the Terraform Registry, simplifying the installation process significantly. Users no longer need to manually download binaries or manage plugin directories for standard installations. Instead, the configuration is handled directly within the Terraform module files.

To utilize the provider from the Registry, the following block must be added to the Terraform configuration:

hcl terraform { required_providers { eksctl = { source = "mumoshu/eksctl" version = "0.3.14" } } }

In this configuration, the version attribute must specify the provider version number without the v prefix. For example, if the target provider version is v0.3.14, the Terraform code must reference 0.3.14. Once the required provider is declared, the provider instance itself requires no specific configuration arguments. It is declared simply as:

hcl provider "eksctl" {}

This minimal configuration reflects the provider's design philosophy: it relies on external credentials (such as AWS credentials configured in the environment or profile) and does not require its own API keys or endpoints.

For users still operating on Terraform 0.12, or those who require specific build artifacts, manual installation is required. The terraform-provider-eksctl binary must be installed into the Terraform plugin directory. There are two primary locations for this installation:

1. Workspace-Specific Installation: Placing the binary in the local workspace's plugin directory ensures that the provider is available only for that specific Terraform project.
   . ${WORKSPACE}/.terraform/plugins/darwin_amd64/terraform-provider-eksctl

2. Global Installation: Placing the binary in the user's home directory makes the provider available to all Terraform workspaces on the system.
   ${HOME}/.terraform.d/plugins/${OS}_${ARCH}/terraform-provider-eksctl

Developers can also build the provider from source. The project includes a convenient Makefile target for this purpose. Running make install within the source directory will compile the provider and install the binary into the global Terraform plugins directory. This is particularly useful for contributors who are developing new features or debugging provider behavior. For Terraform versions 0.13 and above, if using a locally built binary, the version number in the required_providers block must match the dummy version assigned to the binary during the build or installation process to avoid checksum mismatch errors.

Version Management with Shoal

One of the most significant challenges in managing infrastructure with external binaries is version drift. If a team has a local version of eksctl that differs from the version specified in their infrastructure code, it can lead to unpredictable behavior. To solve this, terraform-provider-eksctl includes a built-in package manager called shoal. This component allows the provider to install specific versions of the eksctl executable on demand, ensuring that the exact version of the tool used to manage the cluster matches the definition in the Terraform code.

The eksctl_cluster resource exposes an attribute called eksctl_version. When this attribute is specified, the provider uses the Go runtime and go-git to download and install the required eksctl version. This mechanism operates without requiring additional system dependencies, as it relies on the Go environment bundled with the provider binary.

Consider the following example, where the provider automatically installs eksctl version 0.27.0 before executing any cluster operations:

hcl resource "eksctl_cluster" "mystack" { eksctl_version = "0.27.0" # Additional cluster configuration follows... }

This feature is particularly critical for environments such as Terraform Cloud (now HCP Terraform), where the runtime environment is immutable and cannot be customized by the user to pre-install specific CLI tools. By handling the binary installation internally, the provider ensures consistency and repeatability across different execution environments, whether local, on-premises, or in the cloud.

Resource Definitions: eksctlcluster vs. eksctlcluster_deployment

The provider offers two distinct resource types for managing clusters: eksctl_cluster and eksctl_cluster_deployment. Understanding the distinction between these two resources is essential for selecting the appropriate abstraction level for your use case.

The eksctl_cluster resource is the standard choice for most use cases. It provides direct CRUD (Create, Read, Update, Delete) operations on a single EKS cluster. When a terraform apply is executed, the provider runs a series of eksctl update [RESOURCE] commands to ensure the cluster matches the declared state. For deletion, it uses eksctl delete nodegroup --drain to manage node groups safely. This resource is ideal for teams that want to declare their entire cluster configuration in a single, declarative block.

In contrast, the eksctl_cluster_deployment resource is designed for managing a set of eksctl clusters in an opinionated way. It is specifically tailored for scenarios involving blue-green or canary deployments. During a terraform apply, the provider runs eksctl create and a series of eksctl update [RESOURCE] commands, and may execute eksctl delete depending on the deployment strategy. This resource type enables complex workflows, such as swapping the ArgoCD target cluster without modifying the underlying target clusters, by treating the cluster lifecycle as a deployment process rather than a single static object.

Configuring Cluster Resources and VPC Integration

When defining an eksctl_cluster resource, the configuration is structured around the spec attribute, which accepts a multi-line string containing YAML content. This is conceptually similar to writing an eksctl cluster.yaml file and embedding it directly into the Terraform resource. However, key attributes such as name and region are promoted to dedicated HCL attributes for better Terraform compatibility and type checking.

There are four primary patterns for declaring an eksctl_cluster resource, determined by the level of AWS resource reuse:

1. Ephemeral Cluster: No reuse of VPC, subnets, or other resources. eksctl manages all AWS resources.
2. VPC Reuse: The cluster uses an existing VPC but manages its own subnets and other resources.
3. VPC and Subnet Reuse: The cluster uses an existing VPC and pre-defined subnets.
4. Full Reuse (VPC, Subnets, and ALBs): Used primarily for blue-green cluster deployments where Load Balancers are shared or swapped.

For ephemeral clusters, the configuration is minimal. The provider and cluster resource can be defined as follows:

```hcl
provider "eksctl" {}

resource "eksctlcluster" "primary" {
eksctlbin = "eksctl-0.20.0"
name = "primary1"
region = "us-east-2"

spec = <<-EOS
nodeGroups:
- name: ng1
instanceType: m5.large
desiredCapacity: 1
EOS
}
```

In this example, eksctl will create the VPC, subnets, security groups, and the EKS cluster itself.

For scenarios where a VPC already exists, such as when using a Terraform module like terraform-aws-vpc, the configuration becomes more complex. The vpc_id attribute is set to the existing VPC ID. Additionally, the spec block must include detailed information about the subnets and CIDR blocks to ensure eksctl does not attempt to create conflicting resources.

Consider a scenario where a VPC with ID vpc-09c6c9f579baef3ea already exists. The resource definition adjusts accordingly:

```hcl
resource "eksctlcluster" "vpcreuse1" {
eksctlbin = "eksctl-0.20.0"
name = "vpcreuse1"
region = "us-east-2"
vpc_id = "vpc-09c6c9f579baef3ea"

spec = <<-EOS
nodeGroups:
- name: ng1
instanceType: m5.large
desiredCapacity: 1
EOS
}
```

When reusing VPCs and subnets, particularly in multi-AZ configurations, the spec block must explicitly map the subnets to their respective Availability Zones (AZs). This is crucial for eksctl to correctly associate the cluster with the existing network topology. The following example demonstrates a detailed configuration using variables from a VPC module:

```hcl
resource "eksctlcluster" "primary" {
eksctlbin = "eksctl-dev"
name = "existingvpc2"
region = "us-east-2"
apiversion = "eksctl.io/v1alpha5"
version = "1.16"
vpcid = module.vpc.vpc_id
revision = 1

spec = <<-EOS
nodeGroups:
- name: ng2
instanceType: m5.large
desiredCapacity: 1
securityGroups:
attachIDs:
- ${awssecuritygroup.publicalbprivatebackend.id}
iam:
withOIDC: true
serviceAccounts: []
vpc:
cidr: "${module.vpc.vpccidrblock}"
subnets:
private:
${module.vpc.azs[0]}:
id: "${module.vpc.privatesubnets[0]}"
cidr: "${module.vpc.privatesubnetscidrblocks[0]}"
${module.vpc.azs[1]}:
id: "${module.vpc.privatesubnets[1]}"
cidr: "${module.vpc.privatesubnetscidrblocks[1]}"
${module.vpc.azs[2]}:
id: "${module.vpc.privatesubnets[2]}"
cidr: "${module.vpc.privatesubnetscidrblocks[2]}"
public:
${module.vpc.azs[0]}:
id: "${module.vpc.publicsubnets[0]}"
cidr: "${module.vpc.publicsubnetscidrblocks[0]}"
${module.vpc.azs[1]}:
id: "${module.vpc.publicsubnets[1]}"
cidr: "${module.vpc.publicsubnetscidr_blocks[1]}"
EOS
}
```

This configuration illustrates the power of Terraform interpolation within the spec block. Attributes like security group IDs and VPC CIDRs can be dynamically injected, allowing for tight integration with other Terraform modules. The api_version and version attributes ensure that the cluster is created with the correct Kubernetes version and API schema, which is critical for compatibility with specific eksctl features.

Managing Node Groups and Scaling

In addition to declaring node groups within the main eksctl_cluster spec, the provider supports the eksctl_nodegroup resource. This allows for the dynamic addition or removal of node groups without requiring a full cluster redefinition. This is particularly useful for scaling operations, where you might want to add a new pool of nodes for specific workloads, such as GPU-accelerated instances for machine learning training.

The eksctl_nodegroup resource supports the assume_role block, which enables cross-account usage and role assumption. This is vital for organizations with multi-account AWS strategies where the infrastructure-as-code pipeline runs in one account but the clusters reside in another.

The following example demonstrates how to define a cluster with one node group in the spec and add a second node group using the eksctl_nodegroup resource:

```hcl
resource "eksctlcluster" "red" {
name = "red1"
region = "us-east-2"
apiversion = "eksctl.io/v1alpha5"
version = "1.16"
vpcid = module.vpc.vpcid

spec = <<-EOS
nodeGroups:
- name: ng1
instanceType: m5.large
desiredCapacity: 1
targetGroupARNs:
- ${awslbtarget_group.green.arn}
EOS
}

resource "eksctlnodegroup" "ng2" {
assumerole {
rolearn = var.rolearn
}

name = "ng1"
region = eksctlcluster.red.region
cluster = eksctlcluster.red.name

nodes_min = 1
nodes = 1

# All eksctl-create-nodegroup flags are available in snake_case
}
```

In this example, the eksctl_nodegroup resource allows for fine-grained control over node group parameters. All flags available in the eksctl create nodegroup command are exposed as snake_case attributes in Terraform. This provides a direct mapping between the CLI interface and the infrastructure-as-code model, reducing the learning curve for engineers familiar with eksctl.

Comparison: Native AWS Provider vs. eksctl Provider

When deciding between the native AWS Terraform Provider and the eksctl provider, it is essential to understand the trade-offs. The following table summarizes the key differences:

For small experiments or proof-of-concept clusters, the native eksctl CLI (without Terraform) is often sufficient. However, for production infrastructure where incremental updates are required, such as adding GPU nodes for machine learning workloads, the Terraform integration provides significant advantages. The ability to dry-run changes with terraform plan before applying them to a production cluster is a critical safety net.

For example, adding a new GPU node group to an existing cluster can be achieved by modifying the Terraform configuration to include the new node group parameters. The terraform plan command will then display the exact changes to be made, such as:

text Plan: 8 to add, 0 to change, 1 to destroy.

This output provides visibility into the scope of the change before it is applied. Once verified, terraform apply executes the changes, leveraging the eksctl binary to perform the actual AWS operations.

Advanced Features: Canary and Blue-Green Deployments

One of the more advanced capabilities of terraform-provider-eksctl is support for canary and blue-green deployments. These patterns are essential for zero-downtime upgrades of the Kubernetes cluster itself. The provider supports these strategies using either Application Load Balancers (ALB) or Route 53 combined with Network Load Balancers (NLB).

In a blue-green deployment scenario, the provider can manage two clusters simultaneously. Traffic is routed to the "blue" cluster (the stable version) while the "green" cluster (the new version) is being prepared. Once the green cluster is healthy, traffic is switched over. The eksctl_cluster_deployment resource is particularly useful here, as it can orchestrate the creation of the new cluster, the update of target groups or DNS records, and the eventual decommissioning of the old cluster.

This functionality eliminates the need for a separate management Kubernetes cluster, which is a common requirement in some GitOps patterns. By integrating this logic into Terraform, the state of the deployment is tracked in the Terraform state, and the automation is handled by standard CI/CD pipelines. While the API for these features is largely in place, some functionalities may still be under active development, so users should verify the specific capabilities in the latest version of the provider.

Conclusion

The terraform-provider-eksctl represents a mature solution for teams that desire the simplicity of eksctl without sacrificing the rigor of Terraform. By wrapping the eksctl binary and managing its version through the shoal package manager, the provider eliminates environment inconsistency issues. The dual-resource model, featuring both eksctl_cluster for standard operations and eksctl_cluster_deployment for advanced deployment patterns, provides flexibility for various operational strategies.

The ability to reuse existing VPCs and subnets, combined with dynamic node group management via eksctl_nodegroup, allows for complex infrastructure topologies to be managed declaratively. The support for cross-account usage and role assumption further enhances its applicability in large-scale, multi-account AWS environments. For organizations looking to streamline their EKS management while retaining the benefits of Infrastructure-as-Code, this provider offers a streamlined, opinionated, and powerful pathway. By leveraging the provider's integration with the Terraform Registry and its robust handling of underlying eksctl commands, teams can achieve faster provisioning cycles, better auditability, and more reliable cluster operations.

Sources

1. github.com/mumoshu/terraform-provider-eksctl
2. pkg.go.dev/github.com/mumoshu/terraform-provider-eksctl
3. learnkube.com/terraform-eks