Orchestrating AWS EKS Infrastructure: A Deep Dive into Terraform and the eksctl Provider

Managing Amazon Elastic Kubernetes Service (EKS) clusters has historically presented a dichotomy in the infrastructure-as-code world. On one side stands Terraform, the dominant declarative tool for cloud resource provisioning, offering granular control over individual AWS components. On the other side sits eksctl, the dedicated command-line tool for EKS, which abstracts away the complexity of cluster creation but traditionally lacked a robust, stateful integration layer for continuous infrastructure management. This friction led to the development of the terraform-provider-eksctl, a specialized Terraform provider designed to bridge this gap. By leveraging this provider, engineers can execute terraform apply to bring up entire Kubernetes infrastructure stacks without resorting to fragile glue shell scripts or manually generating eksctl cluster.yaml files. This integration eliminates the need for a separate "management" Kubernetes cluster to store state, as the infrastructure state is inherently stored within the Terraform state file. Consequently, the automation can be fully managed through standard DevOps pipelines such as Atlantis, Terraform Enterprise, CircleCI, or GitHub Actions. This article explores the architectural mechanics, configuration patterns, deployment strategies, and operational benefits of using terraform-provider-eksctl for production-grade EKS management.

Architectural Philosophy and Operational Benefits

The primary motivation for adopting a dedicated provider rather than relying solely on raw Terraform AWS resources or standalone eksctl commands is the consolidation of state and the elimination of operational overhead. Traditional approaches often require a "management" Kubernetes cluster to run operators or controllers that manage other clusters. This introduces additional operational and maintenance costs, as the management cluster itself requires patching, monitoring, and security hardening. The terraform-provider-eksctl resolves this by embedding the necessary automation logic directly into the Terraform execution cycle.

For small experiments, the standalone eksctl binary remains superior. It allows for the rapid creation of a cluster with a single short command, making it ideal for ephemeral development environments. However, for production infrastructure, the requirement shifts toward granular control and incremental updates. In a production context, engineers often need to configure every single detail of the cluster, from specific security group attachments to OIDC configurations. Furthermore, the ability to perform incremental updates is critical. For instance, if a team needs to add a second pool of servers to an existing cluster—perhaps adding GPU nodes for machine learning workloads—Terraform’s plan-and-apply paradigm allows for precise, predictable changes.

The benefits of using this provider are multifaceted:
- Single command execution: terraform apply brings up the whole infrastructure.
- Elimination of glue code: No need to generate eksctl cluster.yaml files via Terraform and integrate them via shell scripts.
- IAM Consistency: Supports using the same pod IAM role across different clusters.
- Cluster Swapping: Facilitates scenarios such as swapping the ArgoCD cluster without altering the target clusters.

The feature set of the provider includes managing eksctl clusters via Terraform, adding or removing nodegroups declaratively, supporting AssumeRole and cross-account usage, installing and upgrading the eksctl binary itself via Terraform, and enabling complex canary deployments using Application Load Balancers (ALB) or Route 53 combined with Network Load Balancers (NLB).

Installation and Provider Configuration

The installation strategy for terraform-provider-eksctl varies depending on the version of Terraform being utilized. For modern environments running Terraform 0.13 and later, the provider is available on the Terraform Registry. This simplifies the onboarding process significantly, requiring only a required_providers block in the root Terraform module.

To install the provider from the registry, the following configuration must be added to the .tf file. The version number must be specified without the v prefix. For example, if the provider version is v0.3.14, the string value should be 0.3.14.

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

Once the provider block is declared, there are no further configuration parameters required for the provider itself. The declaration is minimal:

hcl provider "eksctl" {}

For legacy environments using Terraform 0.12, the installation process is manual. The binary must be placed under the .terraform/plugins/${OS}_${ARCH} directory within the workspace. Alternatively, the provider can be installed globally under ${HOME}/.terraform.d/plugins/${OS}_${ARCH}, making it available to all Terraform workspaces on the machine. When building the provider from source, the Go build toolchain is used. Developers can navigate to the repository directory and execute go build. For convenience, a Make target is provided to install the provider into the global Terraform providers directory:

bash cd terraform-provider-eksctl make install

This command installs the binary under ${HOME}/.terraform.d/plugins/${OS}_${ARCH}. If a user is working with Terraform 0.13 or later and building from source, they must tweak the .tf file to provide a dummy version number and place the binary in the corresponding registry path. For instance, using a dummy version of 0.0.1, the binary must be placed at:

text $(PWD)/.terraform/plugins/registry.terraform.io/mumoshu/eksctl/0.0.1/darwin_amd64/terraform-provider-eksctl_v0.0.1

The implementation of this provider is heavily inspired by terraform-provider-shell, utilizing similar architectural patterns for executing external binaries while maintaining state integrity.

Resource Definitions and CRUD Mechanics

The core of the provider’s functionality lies in two distinct resources: eksctl_cluster and eksctl_cluster_deployment. Understanding the distinction between these two is critical for effective infrastructure design.

The eksctl_cluster resource is the primary tool for most users. It runs eksctl to manage the cluster exactly as declared in the Terraform file. On terraform apply, this resource executes a series of eksctl update [RESOURCE] commands. Notably, when deleting nodegroups, the provider uses eksctl delete nodegroup --drain to ensure high availability and proper workload eviction. On terraform destroy, the provider executes eksctl delete to tear down the entire cluster infrastructure.

The eksctl_cluster_deployment resource is designed for more complex scenarios where a set of eksctl clusters needs to be managed in an opinionated way. On terraform apply, this resource runs eksctl create followed by a series of eksctl update [RESOURCE] and eksctl delete commands depending on the specific situation. Like the standard cluster resource, it utilizes eksctl delete nodegroup --drain for nodegroup deletion.

The computed field output is available on these resources to surface the output from eksctl commands. This allows for string interpolation within Terraform to produce useful outputs for downstream resources.

Configuration Patterns and Spec Embedding

Configuring the eksctl_cluster resource involves embedding an eksctl specification within the Terraform definition. This approach is akin to writing and embedding an eksctl cluster.yaml file into the spec attribute of the Terraform resource, with the exception that certain high-level attributes like cluster name and region have dedicated HCL attributes.

Depending on the infrastructure strategy, there are four primary patterns for declaring a cluster:
1. Ephemeral cluster (No reuse of VPC, subnets, or other resources).
2. Reuse VPC.
3. Reuse VPC and subnets.
4. Reuse VPC, subnets, and ALBs.

For any non-ephemeral cluster scenario, specific pre-requisites must be established in the underlying AWS account:
- A defined VPC.
- Public and Private subnets.
- ALB and listeners (required only when using blue-green cluster deployment).

In the simplest ephemeral scenario, where eksctl manages every AWS resource, the resource definition looks 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
}
```

When reusing an existing VPC, the vpc_id attribute is populated with the existing VPC identifier. For example, if a VPC with ID vpc-09c6c9f579baef3ea already exists:

```hcl
provider "eksctl" {}

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
}
```

In more complex scenarios involving the reuse of VPCs and subnets, the spec attribute requires detailed mapping of subnets by availability zone. This often involves integrating with other Terraform modules, such as the terraform-aws-vpc module. The spec block must provide private and/or public subnets by availability zone. Optional fields such as cidr must match the CIDR blocks used by the given VPC or subnet.

Advanced Integration with VPC Modules

For production environments where the VPC and subnets are managed by Terraform modules, the eksctl_cluster resource can dynamically reference these resources. This ensures that the cluster configuration remains synchronized with the underlying network infrastructure.

Consider a scenario where the VPC is defined using module.vpc. The eksctl_cluster resource can reference module.vpc.vpc_id and module.vpc.private_subnets directly. The following example demonstrates a resource configuration that includes OIDC support, security group attachments, and detailed subnet mapping:

```hcl
resource "eksctlcluster" "existingvpc2" {
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 level of detail allows for precise control over the network topology. The securityGroups section within the nodeGroups ensures that the node instances attach to the correct security groups, which is crucial for enforcing least-privilege network access policies. The iam section enables OIDC integration, allowing for fine-grained authorization within the Kubernetes cluster.

Comparative Analysis: EKSCTL vs. Terraform Native

While terraform-provider-eksctl offers a streamlined interface, it is essential to understand the trade-offs compared to using native Terraform AWS modules for EKS. The following table compares the two approaches based on key operational factors.

For small experiments, eksctl (and by extension, the provider) is preferred due to the ability to create a cluster with a short command. However, for production infrastructure where every single detail of the cluster configuration is critical, native Terraform may be chosen by teams that require absolute visibility into every AWS API call. The terraform-provider-eksctl strikes a balance by abstracting the complexity while still allowing for significant customization through the spec block.

A critical advantage of the Terraform approach (both native and provider-based) over pure eksctl CLI usage is the handling of incremental updates. Consider a scenario where a second pool of servers needs to be added to an existing cluster. In a native Terraform module configuration, one can amend the eks_managed_node_groups map to include new node types.

```hcl
module "eks" {
source = "terraform-aws-modules/eks/aws"
version = "18.30.3"
clustername = "${local.clustername}"
clusterversion= "1.24"
subnets = module.vpc.privatesubnets
vpcid = module.vpc.vpcid

eksmanagednodegroups = {
first = {
desiredcapacity = 1
maxcapacity = 10
mincapacity = 1
instancetype = "m5.large"
}
gpu = {
desiredcapacity = 1
maxcapacity = 10
mincapacity = 1
instance_type = "p3.2xlarge"
}
}
}
```

When executing terraform plan, the output indicates the specific changes: Plan: 8 to add, 0 to change, 1 to destroy. Once validated, terraform apply executes the changes. This deterministic nature ensures that infrastructure changes are auditable and reversible, a key requirement for enterprise-grade cloud operations.

Conclusion

The integration of eksctl with Terraform through the terraform-provider-eksctl represents a significant advancement in Kubernetes infrastructure management on AWS. By abstracting the complex creation and update logic of EKS clusters into a declarative Terraform resource, this tool eliminates the traditional friction of managing state and configuration drift. The provider’s ability to handle both ephemeral and persistent VPC scenarios, along with its support for canary deployments and cross-account IAM roles, makes it a versatile tool for both development and production environments.

The distinction between eksctl_cluster and eksctl_cluster_deployment provides users with the flexibility to choose the right level of abstraction for their specific needs. The use of embedded YAML specs within HCL allows for the detailed configuration of node groups, security groups, and IAM policies without leaving the Terraform ecosystem. Furthermore, the elimination of the need for a management Kubernetes cluster reduces operational costs and complexity, allowing teams to focus on application deployment rather than infrastructure plumbing.

For organizations aiming to adopt a "GitOps" or Infrastructure-as-Code mindset, terraform-provider-eksctl offers a robust pathway. It ensures that the entire lifecycle of the EKS cluster—from creation to upgrade to destruction—is managed through version-controlled code, executed via standard CI/CD pipelines. As the AWS ecosystem continues to evolve, the ability to declaratively manage clusters with tools that understand the specific nuances of eksctl will remain a critical competency for cloud engineers. The provider’s maturity, availability on the Terraform Registry, and its alignment with standard DevOps practices position it as a cornerstone tool for modern EKS management.

Sources

1. terraform-provider-eksctl
2. LearnKube Terraform EKS