Amazon EKS — Cluster Config YAML

Cluster Config YAML

While CLI flags work for quick clusters, production teams use YAML config files. They’re version-controlled, reviewable, and reproducible.

---

Why Use a Config File?

CLI Approach	Config File Approach
Hard to reproduce	Git-versioned, reproducible
Hard to review	PR-reviewable
Limited options	All eksctl features available
Good for quick tests	Good for production

---

Basic Config File

Create cluster.yaml:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: demo
  region: us-east-1
  version: "1.29"

managedNodeGroups:
  - name: demo-nodes
    instanceType: t3.medium
    desiredCapacity: 2
    minSize: 1
    maxSize: 3
    volumeSize: 20
    labels:
      role: worker
    tags:
      Environment: tutorial
      ManagedBy: eksctl

Create the cluster:

$ eksctl create cluster -f cluster.yaml

---

Production-Grade Config File

Here’s a more realistic config:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: production
  region: us-east-1
  version: "1.29"
  tags:
    Environment: production
    Team: platform

# Use existing VPC (recommended for production)
# vpc:
#   id: vpc-0abc123def456
#   subnets:
#     private:
#       us-east-1a: { id: subnet-0abc123 }
#       us-east-1b: { id: subnet-0def456 }

# IAM OIDC provider (required for IRSA)
iam:
  withOIDC: true

managedNodeGroups:
  # General-purpose workloads
  - name: general
    instanceType: m5.xlarge
    desiredCapacity: 3
    minSize: 2
    maxSize: 10
    volumeSize: 50
    volumeType: gp3
    privateNetworking: true     # Nodes in private subnets
    labels:
      workload-type: general
    tags:
      NodeGroup: general

  # Spot instances for non-critical workloads
  - name: spot-workers
    instanceTypes:
      - m5.large
      - m5a.large
      - m4.large
    spot: true
    desiredCapacity: 2
    minSize: 0
    maxSize: 10
    volumeSize: 30
    volumeType: gp3
    privateNetworking: true
    labels:
      workload-type: spot
    taints:
      - key: spot
        value: "true"
        effect: NoSchedule

# EKS managed add-ons
addons:
  - name: vpc-cni
    version: latest
  - name: coredns
    version: latest
  - name: kube-proxy
    version: latest

# CloudWatch logging
cloudWatch:
  clusterLogging:
    enableTypes:
      - api
      - audit
      - authenticator
      - controllerManager
      - scheduler

---

Config File Sections Explained

Section	Purpose
metadata	Cluster name, region, K8s version
vpc	VPC settings (or use existing VPC)
iam	OIDC provider, service accounts
managedNodeGroups	Worker node configurations
addons	EKS managed add-ons
cloudWatch	Control plane logging

---

Common Config Patterns

Multi-AZ with Private Networking

managedNodeGroups:
  - name: workers
    instanceType: m5.large
    desiredCapacity: 6
    privateNetworking: true    # Nodes in private subnets
    availabilityZones:
      - us-east-1a
      - us-east-1b
      - us-east-1c

Mixed Instance Types (Cost Optimization)

managedNodeGroups:
  - name: mixed
    instanceTypes:
      - m5.large      # Primary
      - m5a.large     # AMD alternative (cheaper)
      - m4.large      # Previous gen (cheaper)
    desiredCapacity: 3

---

Validate Config Before Applying

# Dry run — shows what would be created
$ eksctl create cluster -f cluster.yaml --dry-run

# Just generate CloudFormation — don't create
$ eksctl create cluster -f cluster.yaml --without-nodegroup --dry-run

---

Update Existing Cluster

Some changes can be applied to a running cluster:

# Scale a node group
$ eksctl scale nodegroup --cluster demo --name demo-nodes --nodes 3

# Add a new node group
$ eksctl create nodegroup -f cluster.yaml --include "spot-workers"

# Delete a node group
$ eksctl delete nodegroup --cluster demo --name spot-workers

---

Common Mistakes

Mistake	Fix
Not setting privateNetworking: true	Nodes get public IPs (security risk)
Small volumeSize	Docker images fill up the disk; use 30+ GB
Not enabling OIDC (withOIDC: true)	Can’t use IRSA for pod IAM permissions
Forgetting to version-control the config	Lose track of cluster configuration

---

Quick Reference

# Create from config
$ eksctl create cluster -f cluster.yaml

# Dry run
$ eksctl create cluster -f cluster.yaml --dry-run

# Update node group
$ eksctl scale nodegroup --cluster demo --name demo-nodes --nodes 3

# Get cluster config
$ eksctl utils describe-stacks --cluster demo --region us-east-1

---

What’s Next?

Your cluster is created. Now let’s connect to it: Kubeconfig Setup.