# eksctl turns CloudFormation templates into the cluster lifecycle you forgot

> The official CLI for Amazon EKS writes CloudFormation rather than calling APIs, ships as a single Go binary or a public ECR image, and every release bumps the add-on versions it defaults to.

**eksctl-io/eksctl** — The official CLI for Amazon EKS

- Repository: https://github.com/eksctl-io/eksctl
- Website: https://eksctl.io
- Stars: 5,215 · Forks: 1,504
- Language: Go
- License: NOASSERTION
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/eksctl-io-eksctl

## One command, and what it quietly decides for you

The pitch is a single command. `eksctl create cluster` creates a cluster on EKS, Amazon's managed Kubernetes service for EC2, and the README leads with the fact that you can do it in minutes.

What that command chooses is spelled out immediately after, as a list of defaults: an exciting auto-generated name such as "fabulous-mushroom-1527688624", two `m5.large` nodes with the README noting that this instance type suits most common use cases and is good value, and defaults for the rest. The auto-generated name is a small touch that tells you the tool is optimised for the first run rather than for reproducibility. For anything you intend to keep, you will replace it with a name of your own.

The important architectural fact is in the second line of the README: eksctl is written in Go and uses CloudFormation. That single word explains most of this project's behaviour. It is not calling AWS APIs imperatively to build a cluster, it is generating and applying a CloudFormation stack. So a cluster has a stack, the stack is inspectable, and the same tool can take it away again.

It also explains why the release notes look the way they do. If eksctl is a template generator, then every AWS API change, every add-on version bump and every permission change is something the templates have to keep up with.

## Install paths, and which one the project wants you to use

The README is direct about installation: eksctl is available from official releases, and it recommends installing only from the official GitHub releases. Third-party installers exist and are documented, with a clear advisory that AWS does not maintain nor support those methods, at your own discretion.

The Unix path builds a platform string from `uname` and then downloads the tarball, and it includes an optional checksum verification step against `eksctl_checksums.txt` that is worth taking rather than skipping:

```sh
# for ARM systems, set ARCH to: `arm64`, `armv6` or `armv7`
ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
PLATFORM=$(uname -s)_$ARCH

curl -sLO "https://github.com/eksctl-io/eksctl/releases/latest/download/eksctl_$PLATFORM.tar.gz"

# (Optional) Verify checksum
curl -sL "https://github.com/eksctl-io/eksctl/releases/latest/download/eksctl_checksums.txt" | grep $PLATFORM | sha256sum --check

tar -xzf eksctl_$PLATFORM.tar.gz -C /tmp && rm eksctl_$PLATFORM.tar.gz

sudo install -m 0755 /tmp/eksctl /usr/local/bin && rm /tmp/eksctl
```

The mapping from `uname -m` output to release artefact names is the fiddly part, and it is why that first line exists at all: the release artefacts are named `eksctl_Darwin_arm64` and the like, while the machine reports `arm64` or `aarch64`.

Windows gets four direct download links, AMD64 through ARMv7, plus a documented checksum route using `CertUtil -hashfile` in Command Prompt or `Get-FileHash` in PowerShell, and a Git Bash variant that unzips into `$HOME/bin`. Docker is one line, since every release and release candidate pushes an image to `public.ecr.aws/eksctl/eksctl`:

```bash
docker run --rm -it public.ecr.aws/eksctl/eksctl version
```

The third-party routes are Homebrew and MacPorts on macOS and chocolatey and scoop on Windows. They are one command each, which is exactly why the README marks them not recommended.

## The prerequisites table is the real documentation

Before any of that you need AWS API credentials configured, and the README says what works for the AWS CLI or any other tool such as kops or Terraform should be sufficient, using either the `~/.aws/credentials` file or environment variables.

The less obvious prerequisite is a second tool. You also need AWS IAM Authenticator for Kubernetes available as `aws-iam-authenticator`, or `aws eks get-token` from AWS CLI version 1.16.156 or greater, in your `PATH`. eksctl creates the cluster but does not replace your kubeconfig authentication, so this is a hard dependency rather than a convenience.

Then there is the table of minimal access levels for the IAM account used for cluster creation. CloudFormation needs Full Access. EC2 needs Full for Tagging and Limited List, Read, Write. EC2 Auto Scaling needs Limited List and Write. EKS needs Full Access. IAM needs Limited including Permissions Management. Systems Manager needs Limited List and Read. The inline policy JSON is linked from a Minimal IAM Policies page on the site.

Permissions Management on IAM and Full Access on CloudFormation are the two entries that make people pause. Both are necessary because eksctl creates roles for the cluster and its add-ons, and because CloudFormation has to be able to create those roles on your behalf. This is the reason to read the policy page before the first run: the first attempt failing on an IAM error is an expensive way to learn that.

## A Go module still named after the company it outgrew

The repository lives under `eksctl-io` on GitHub and is described as the official CLI for Amazon EKS, but the Go module path is a reminder of where it started:

```
module github.com/weaveworks/eksctl

go 1.26.5
```

The Homebrew tap in the README is `weaveworks/tap` for the same reason. eksctl began at Weaveworks and moved into an `eksctl-io` organisation, and the import path stayed put. That is normal for a Go project with thousands of importers, since changing a module path is a breaking change for every one of them.

The dependency list in `go.mod` is the clearest statement of what this tool actually talks to. It uses the v2 AWS SDK with individual service clients rather than the monolithic v1 SDK: `service/cloudformation`, `service/ec2`, `service/eks`, `service/iam`, `service/autoscaling`, `service/kms`, `service/outposts`, `service/ssm`, `service/sts` and `service/cloudwatchlogs`. Two entries are more revealing than the rest. `github.com/awslabs/amazon-eks-ami/nodeadm` is the node bootstrap path, and `github.com/cloudflare/cfssl` is a certificate authority library, which is what EKS control plane TLS needs.

There is also a comment at the top of `go.mod` that reads like a maintainer note: run `make generate-all`, `make lint` and `make check-all-generated-files-up-to-date` after changes to the file. A project that tells you how to verify generated code is up to date is a project where generated code is load-bearing.

## The tree is organised around generated code and tests

Thirty-three top level entries, and the ones that matter for understanding the project are `pkg/`, `cmd/`, `userdocs/`, `integration/`, `examples/` and the four Makefiles.

`cmd/` holds command entry points, which is the standard Go layout, and `pkg/` holds the bulk of the implementation. The Makefile names the pieces worth knowing about. It defines a variable pointing at `pkg/apis/eksctl.io/v1alpha5/zz_generated.deepcopy.go`, which is the generated deep-copy code for the cluster config API. The `v1alpha5` in that path is the config schema version, and the `zz_` prefix is the convention that marks a file as generated and not to be edited.

The Makefile also declares the generated AWS SDK mocks with a wildcard over `pkg/eks/mocks/*API.go`, and groups both under a variable called `conditionally_generated_files`. The word conditionally is doing work: not everything is regenerated on every run, and the Makefile has a target that regenerates unconditionally before a build. There is a `.mockery.yaml` at the top level, which is the configuration for the mock generator, so the mocks are produced rather than written by hand.

The `Makefile` help target is self-documenting, with an awk one-liner that formats target names and descriptions into a usage block, including a separate Windows branch because the shell differs. `Makefile.docker`, `Makefile.common` and `Makefile.docs` are included from the top, and `netlify.toml` with a `CNAME` at the root is how the documentation site at eksctl.io is built and hosted. `userdocs/src/usage/auto-mode.md` and `userdocs/src/usage/hybrid-nodes.md` are the two documentation files the README links for the newest features, which tells you the docs live in the repository rather than in a separate system.

## What changed in 0.229.0 and 0.230.0

Two feature releases and one release candidate are recorded. Version 0.229.0 shipped on 2026-07-01 and added cluster version rollback support with a `rollbackConfig`, plus support for EKS on Outposts with EC2 instance store. Version 0.230.0 shipped on 2026-08-14, with a release candidate the day before.

Version 0.230.0's features are control plane component config support and BottlerocketFips AMI family support in managed nodegroups. The improvement worth noting is making vpc-cni and kube-proxy optional when creating IPv6 clusters, which pairs with the bug fix granting `ec2:DescribeSubnets` to the IPv6 VPC CNI role. Those two lines together describe the usual cost of a new EKS feature: an option appears, and a permission has to be added for it.

The maintenance list is the real signal about what eksctl has to own. Version 0.230.0 updates aws-node to v1.23.0, coredns, ec2-info and nvidia-device-plugin to v0.19.3, and bumps oras-go to 2.6.2 to resolve five open advisories. Those are Kubernetes add-ons and transitive dependencies that eksctl either installs as part of a cluster or links in as a library, and someone has to move the versions when upstream does.

Both releases also thank outside contributors by handle, which is standard practice and worth noting because the acknowledgements list in 0.230.0 has six names and in 0.229.0 has two.

The version numbering is the other thing to understand. eksctl is at 0.230.0 while the README says EKS Auto Mode and EKS Hybrid Nodes each require version 0.195.0 or greater. eksctl versions do not map to Kubernetes versions, and the three most recent releases here span 2026-07-01 to 2026-08-14, which is a slower cadence than the AWS services it sits on top of.

## Conclusion

eksctl earns its place by making a cluster disposable. Because a cluster is a CloudFormation stack, the same tool that creates one can delete it, and the config file that describes it is reviewable in a pull request rather than buried in console clicks. The cost is that eksctl is opinionated about AWS: it will not manage a cluster created some other way, and every version bump pulls new defaults for add-ons like aws-node and coredns. Read the minimal IAM policy page before your first run so the first attempt is not a permissions error, keep the version pinned rather than tracking latest, and treat config changes the way you would treat infrastructure code.

## FAQ

### What is the difference between eksctl and kubectl?

They operate at different layers. eksctl creates and manages the cluster infrastructure itself, and it does so by generating and applying CloudFormation stacks, which is why a cluster created with eksctl is a stack you can inspect and delete with the same tool. kubectl talks to a running cluster's API server to deploy and inspect workloads. The README also notes you need AWS IAM Authenticator for Kubernetes, or `aws eks get-token` from AWS CLI 1.16.156 or greater, in your PATH for authentication after cluster creation.

### How do I install eksctl?

The README recommends installing only from the official GitHub releases. On Unix you derive a platform string from `uname`, download the matching tarball, optionally verify it against `eksctl_checksums.txt`, and install the binary into `/usr/local/bin`. For every release and release candidate there is also a container image at `public.ecr.aws/eksctl/eksctl`, run with `docker run --rm -it public.ecr.aws/eksctl/eksctl version`. Third-party installers exist for Homebrew, MacPorts, chocolatey and scoop, but the README advises that AWS does not maintain or support them.

### What permissions does my AWS account need to create a cluster with eksctl?

The README publishes a minimal access table. CloudFormation and EKS need Full Access. EC2 needs Full for Tagging and Limited List, Read and Write. EC2 Auto Scaling needs Limited List and Write. IAM needs Limited including Permissions Management, which is required because eksctl creates roles for the cluster and its add-ons. Systems Manager needs Limited List and Read. The inline policy JSON is published on the eksctl site under Minimal IAM Policies.

## Sources

- [eksctl-io/eksctl on GitHub](https://github.com/eksctl-io/eksctl)
- [Issues](https://github.com/eksctl-io/eksctl/issues)
- [Project website](https://eksctl.io)
- [README](https://github.com/eksctl-io/eksctl/blob/main/README.md)
- [Releases](https://github.com/eksctl-io/eksctl/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/eksctl-io-eksctl