EKS

KSail supports Amazon Elastic Kubernetes Service (EKS) as a managed Kubernetes distribution via eksctl. A declarative eks.yaml (eksctl ClusterConfig) defines the cluster shape; KSail provisions it and manages its lifecycle with the same commands used for local clusters.

EKS is the only distribution that uses the AWS provider. It is a cloud distribution — local mirror registries and local registry containers are not supported.

When to Use EKS

EKS is ideal when you:

Need a managed AWS Kubernetes cluster with full cloud integrations (ELB, EBS, VPC, IAM OIDC)
Want to use the same KSail workflow (init → create → delete) for cloud clusters
Require GitOps workflows (Flux or ArgoCD) on managed AWS infrastructure

For local development and testing, consider the Vanilla, K3s, or VCluster distributions instead.

Prerequisites

AWS account — with permissions to create EKS clusters, IAM roles, and VPCs
AWS credentials — configure via aws configure or environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_DEFAULT_REGION)
Docker — required locally for the ksail CLI

What EKS Provides by Default

Component	Status	Details
CNI	Built-in	Amazon VPC CNI (vpc-cni addon)
CSI	Built-in	Amazon EBS CSI Driver addon
LoadBalancer	Built-in	AWS `Service` type `LoadBalancer` support via AWS cloud integration
Metrics Server	❌	Not provided by default

Quick Start

1. Initialize an EKS Project

mkdir my-eks-cluster
cd my-eks-cluster

ksail project init \
  --name eks-default \
  --distribution EKS \
  --provider AWS

This generates:

ksail.yaml — KSail cluster configuration
eks.yaml — eksctl ClusterConfig (source of truth for cluster metadata)
k8s/kustomization.yaml — directory for Kubernetes manifests

2. Review and Edit `eks.yaml`

The scaffolded eks.yaml is a minimal starting point:

# eksctl cluster configuration.
# See https://eksctl.io/usage/schema/ for the full schema.
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: eks-default
  region: us-east-1
  version: "1.31"

iam:
  withOIDC: true

addons:
  - name: vpc-cni
  - name: kube-proxy
  - name: coredns
  - name: aws-ebs-csi-driver

managedNodeGroups:
  - name: default
    instanceType: t3.medium
    desiredCapacity: 2
    minSize: 1
    maxSize: 3
    volumeSize: 20
    amiFamily: AmazonLinux2023

Edit this file to match your AWS environment: region, Kubernetes version, instance types, nodegroup sizing, and addon configuration. Creating a cluster requires this file; read-only operations (list, info) and lifecycle ones (start, stop, delete) work against an existing cluster without it.

3. Configure `ksail.yaml`

The ksail.yaml references your EKS cluster. All cluster metadata lives in eks.yaml — do not duplicate it in ksail.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/devantler-tech/ksail/main/schemas/ksail-config.schema.json
apiVersion: ksail.io/v1alpha1
kind: Cluster
metadata:
  name: eks-default
spec:
  cluster:
    distribution: EKS
    provider: AWS

4. Create the Cluster

export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

ksail cluster create

KSail invokes eksctl to provision the cluster from eks.yaml and waits for completion. See the AWS provider guide for the full credential and environment-variable reference.

Lifecycle

Command	Effect
`ksail cluster create`	Provisions the cluster from `eks.yaml` via eksctl and waits for it
`ksail cluster delete`	Deletes the cluster, unwinding the eksctl CloudFormation stacks
`ksail cluster stop`	Scales every managed nodegroup to zero to halt node costs
`ksail cluster start`	Restores the managed nodegroups to their configured capacity
`ksail cluster list`	Lists clusters in the configured region (all regions when unset)
`ksail cluster info`	Shows cluster details

kubeconfig Context

EKS contexts written by eksctl follow the format <iam-identity>@<name>.<region>.eksctl.io. Set spec.cluster.connection.context in ksail.yaml after cluster creation if you need to override the auto-detected context.

Limitations

EKS is a cloud distribution — local mirror registries and local registry containers are not supported. Use external registry URLs (e.g., docker.io=https://registry-1.docker.io)
EKS only supports the AWS provider — the Docker, Hetzner, and Omni providers are not available
The control plane keeps running (and billing) while nodegroups are stopped — use ksail cluster delete to tear down the cluster and stop its cluster-related charges (resources provisioned by workloads, such as load balancers or persistent volumes, may need separate cleanup)
KSail-managed component installation (CNI/CSI/GitOps/security add-ons beyond eksctl’s built-ins) is still in progress — the AWS Load Balancer Controller is available behind the experimental spec.cluster.eks.experimentalAWSLoadBalancerController opt-in, and ksail cluster update can apply node-group scaling in-place behind spec.cluster.eks.experimentalInPlaceUpdates; see Support Matrix

EKS