> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/terraform-aws-modules/terraform-aws-eks/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Deploy a working Amazon EKS cluster using EKS Auto Mode in under 10 minutes with the terraform-aws-eks module.

This guide walks you through deploying an EKS cluster with EKS Auto Mode — the simplest compute configuration, where AWS manages node provisioning and lifecycle automatically.

## Prerequisites

Before you start, make sure you have:

* An AWS account with permissions to create IAM roles, EKS clusters, VPCs, and EC2 resources.
* [Terraform](https://developer.hashicorp.com/terraform/install) `>= 1.5.7` installed.
* The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed and configured (`aws configure` or environment variables set).
* [kubectl](https://kubernetes.io/docs/tasks/tools/) installed for verifying the cluster after creation.

## Deploy the cluster

<Steps>
  <Step title="Create your Terraform configuration">
    Create a new directory and add a `main.tf` file with the following configuration. This uses the `general-purpose` built-in node pool, which is sufficient for most workloads.

    ```hcl theme={null}
    module "eks" {
      source  = "terraform-aws-modules/eks/aws"
      version = "~> 21.0"

      name               = "example"
      kubernetes_version = "1.33"

      # Enable the public API endpoint so kubectl can reach the cluster
      endpoint_public_access = true

      # Adds the Terraform caller identity as a cluster administrator
      enable_cluster_creator_admin_permissions = true

      compute_config = {
        enabled    = true
        node_pools = ["general-purpose"]
      }

      vpc_id     = "vpc-1234556abcdef"
      subnet_ids = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]

      tags = {
        Environment = "dev"
        Terraform   = "true"
      }
    }
    ```

    Replace `vpc_id` and `subnet_ids` with the IDs of an existing VPC and private subnets in your AWS account. The subnets must be in at least two availability zones.

    <Tip>
      If you need to create a VPC as part of the same Terraform configuration, use the [`terraform-aws-modules/vpc/aws`](https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws) module. See the [EKS Auto Mode example](https://github.com/terraform-aws-modules/terraform-aws-eks/tree/master/examples/eks-auto-mode) for a complete working setup including VPC creation.
    </Tip>
  </Step>

  <Step title="Initialize Terraform">
    Download the module and provider plugins:

    ```bash theme={null}
    terraform init
    ```

    You should see output confirming that the `terraform-aws-modules/eks/aws` module and the AWS, TLS, and Time providers were installed.
  </Step>

  <Step title="Review the execution plan">
    See exactly what Terraform will create before applying:

    ```bash theme={null}
    terraform plan
    ```

    The plan will include resources for the EKS cluster, IAM roles, KMS key, security groups, OIDC provider, and CloudWatch log group. EKS Auto Mode does not create EC2 nodes at this stage — nodes are provisioned automatically when you schedule workloads.
  </Step>

  <Step title="Apply the configuration">
    Create the cluster:

    ```bash theme={null}
    terraform apply
    ```

    Type `yes` when prompted. Cluster creation typically takes 10–15 minutes. Terraform will print the cluster outputs when complete.
  </Step>

  <Step title="Configure kubectl">
    Update your local kubeconfig so `kubectl` can connect to the new cluster:

    ```bash theme={null}
    aws eks update-kubeconfig \
      --region us-west-2 \
      --name example
    ```

    Replace `us-west-2` with the region you deployed to and `example` with the value you set for `name` in your module configuration.

    If you used `terraform output` to capture the cluster name, you can also run:

    ```bash theme={null}
    aws eks update-kubeconfig \
      --region us-west-2 \
      --name $(terraform output -raw cluster_name)
    ```
  </Step>

  <Step title="Verify the cluster">
    Confirm the cluster is reachable and the API server is responding:

    ```bash theme={null}
    kubectl cluster-info
    ```

    Check that the system pods are running:

    ```bash theme={null}
    kubectl get pods -n kube-system
    ```

    List the cluster nodes (with EKS Auto Mode, nodes appear only after you schedule a workload that requires compute):

    ```bash theme={null}
    kubectl get nodes
    ```
  </Step>
</Steps>

## Important caveats

<Warning>
  **Disabling EKS Auto Mode requires an explicit configuration step.**

  Due to the current EKS Auto Mode API, you cannot disable Auto Mode by simply removing the `compute_config` block. If you try, the apply will fail. To disable EKS Auto Mode, you must first apply with `enabled = false`:

  ```hcl theme={null}
  compute_config = {
    enabled = false
  }
  ```

  Only after that apply succeeds can you safely remove the `compute_config` block entirely from your configuration.
</Warning>

<Note>
  The `enable_cluster_creator_admin_permissions = true` setting adds your current IAM identity as a cluster administrator via an EKS access entry. This is different from the one-time `bootstrap_cluster_creator_admin_permissions` flag on the EKS API, which this module intentionally hardcodes to `false`. Using an access entry means you can revoke or modify access at any time without recreating the cluster.
</Note>

## Clean up

To destroy all resources created by this configuration:

```bash theme={null}
terraform destroy
```

<Warning>
  This permanently deletes the EKS cluster and all associated resources. Ensure any persistent data (EBS volumes, S3 objects created by workloads, etc.) is backed up before running this command.
</Warning>

## Next steps

<Columns cols={2}>
  <Card title="EKS managed node groups" icon="server" href="/compute/eks-managed-node-groups">
    Use EKS managed node groups for more control over instance types and node configuration.
  </Card>

  <Card title="Cluster access entries" icon="key" href="/configuration/access-entries">
    Grant other IAM roles and users access to your cluster.
  </Card>

  <Card title="EKS add-ons" icon="puzzle" href="/configuration/addons">
    Install and manage EKS add-ons like CoreDNS, VPC CNI, and kube-proxy.
  </Card>

  <Card title="IRSA" icon="shield" href="/configuration/irsa">
    Assign AWS IAM permissions to Kubernetes service accounts.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.