AWS EKS Cluster

AWS EKS Cluster Provisioner

The AWS EKS Cluster Provisioner deploys a production-ready Kubernetes cluster on Amazon Web Services (AWS), utilizing assume role and aws sts to generate temporary keys, eliminating the need for hardcoded AWS credentials.

AWS EKS Specification

The eks struct configures the EKS provisioner.

accountId: Required AWS account ID (12 digits).
vpcId: Optional field for VPC (required for BYOVPC).
vpcCIDR: Optional field for CIDR block (/16 to /28, required for BYOVPC).
subnets: Optional field for subnet specifications (required for BYOVPC).
kubernetesVersion: Optional field for Kubernetes version (e.g., 1.30 or 1.30.14).
amiFamily: Optional field for AMI family (default: AmazonLinux2023).
tags: Optional field for AWS resource tags.
credentials: Required field for cloud provider credentials.

Bring your own VPC (BYOVPC)

vpcId, vpcCIDR, and subnets are required fields for BYOVPC.

Prerequisites

Required tools

AWS CLI — required for IAM assume-role and kubeconfig token generation
kubectl (optional) — for direct cluster interaction
astroctl — for cluster management

Finding your AWS credentials

You need your 12-digit AWS account ID. Run:

aws sts get-caller-identity --query Account --output text

Example output: 123456789012

Make sure the AWS CLI is authenticated to the account you want to deploy into. If you manage multiple accounts, check the active profile:

aws sts get-caller-identity

Find available regions and zones

astroctl cloud aws regions list
astroctl cloud aws regions zones list -r <region-name>

Connect your AWS account

Run this once per cluster before creating it. Omitting this step will cause an error during cluster creation.

astroctl cloud aws connect \
  --account-id <YOUR_AWS_ACCOUNT_ID> \
  --cluster-name <YOUR_CLUSTER_NAME> \
  --region <YOUR_REGION>

Example:

astroctl cloud aws connect \
  --account-id 123456789012 \
  --cluster-name my-eks-cluster \
  --region us-east-1

The CLI opens a pre-filled AWS CloudFormation link in your browser. Log into the correct AWS account in that tab, then click Create stack. The CLI waits and prints a confirmation when the IAM role is ready.

Use the same --cluster-name and --region values when you create the cluster.

Complete Field Reference

The eks struct configures the EKS provisioner. This is the authoritative reference for all available fields.

Core Fields

Field	Type	Required	Default	Description
`accountId`	string	Yes	-	AWS account ID (12 digits) where the cluster will be created
`credentials`	object	Yes	-	Cloud provider credentials. Only `type: dynamic` is supported (uses AWS STS assume role)

Networking Fields (BYOVPC)

Field	Type	Required	Default	Description
`vpcId`	string	No	-	Existing VPC ID for BYOVPC. If not provided, platform creates a new VPC
`vpcCIDR`	string	No	-	CIDR block for the VPC. Required when `vpcId` is provided. See Supported CIDR Ranges
`subnets`	map[zone][]subnet	No	-	Subnet specifications per availability zone. Required when `vpcId` is provided
`subnets[zone][].type`	string	Yes*	-	Subnet type: `public` or `private`
`subnets[zone][].id`	string	Yes*	-	Subnet ID (e.g., `subnet-0b9e119bdba3f8add`)

*Required when vpcId is provided. Each zone must have at least one public and one private subnet.

Cluster Configuration Fields

Field	Type	Required	Default	Description
`kubernetesVersion`	string	No	Latest	Kubernetes version. Accepts: `1.30` or `1.30.14` format
`amiFamily`	string	No	`AmazonLinux2023`	AMI family for node groups. Values: `AmazonLinux2`, `AmazonLinux2023`, `Bottlerocket`, `Ubuntu`
`tags`	map[string]string	No	-	Key-value pairs for AWS resource tagging

Field Validation Rules

Field	Validation
`accountId`	Must be exactly 12 digits
`vpcId`	Must start with `vpc-` followed by alphanumeric characters
`vpcCIDR`	Must be valid CIDR notation (e.g., `10.0.0.0/16`)
`subnets[zone][].id`	Must start with `subnet-` followed by alphanumeric characters
`subnets[zone][].type`	Must be one of: `public`, `private`
`kubernetesVersion`	Must be valid K8s version format: `1.30` or `1.30.14`
`amiFamily`	Must be one of: `AmazonLinux2`, `AmazonLinux2023`, `Bottlerocket`, `Ubuntu`

EKS Networking Architecture

EKS uses per-zone subnets with both public and private subnets in each availability zone. This differs from GKE which uses regional subnets.

See Networking Overview for visual diagrams comparing EKS architectures.

Supported CIDR Ranges

AWS VPC supports both RFC 1918 private ranges and other CIDR blocks:

Range Type	CIDR Block	Available IPs	Notes
RFC 1918 Class A	`10.0.0.0/8`	16,777,216	Recommended for production
RFC 1918 Class B	`172.16.0.0/12`	1,048,576	172.16.x.x - 172.31.x.x
RFC 1918 Class C	`192.168.0.0/16`	65,536	Common for small clusters
Shared address space	`100.64.0.0/10`	4,194,304	Carrier-grade NAT

VPC CIDR (vpcCIDR):

Prefix length: /16 to /28
Must not overlap with other VPCs or peered networks
RFC 1918 ranges recommended for production

Subnet CIDR recommendations:

Subnet Type	Recommended Prefix	IPs per Subnet	Notes
Public	/24	256	NAT gateways, load balancers
Private	/19 or /20	8,192 or 4,096	Worker nodes, pods

Examples:

vpcCIDR: "10.0.0.0/16"       # 65,536 IPs (recommended)
vpcCIDR: "172.31.0.0/16"     # 65,536 IPs
vpcCIDR: "192.168.0.0/16"    # 65,536 IPs
vpcCIDR: "10.100.0.0/20"     # 4,096 IPs (smaller VPC)

CIDR Planning

When planning your VPC CIDR:

Leave room for future expansion (pods, services, additional subnets)
Avoid overlaps with on-premises networks if using VPN/Direct Connect
Use /16 for production clusters to ensure sufficient IP space

Bring Your Own Account (BYOA)

The astro platform allows you to bring your own account for EKS cluster creation. The following example illustrates the EKS specification, with the platform managing VPC, subnet, and other networking configurations. You only need to provide the account ID and ensure proper quota for these configurations. The astroctl will verify quota and permissions before cluster creation.

apiVersion: platform.astropulse.io/v1
kind: K8sCluster
spec:
  clusterName: my-eks-cluster
  provider: aws
  region: us-west-2
  provisioner:
    type: eks
    eks:
      accountId: "123456789012"  # your AWS account id
      tags:
        environment: "dev"
        owner: "foo@bar.com"
      credentials:
        type: dynamic  # uses assume role and aws sts to generate temporary keys
  clusterSpec:
    dataPlane:
      nodeGroups:
        - name: default-node-group
          minNode: 1
          maxNode: 3
          instanceType: ondemand  # or "spot" for cost savings
          machineTypes:
            - t3.medium
          labels:
            environment: dev

Bring Your Own VPC (BYOVPC)

To facilitate BYOVPC, the astroctl generates a cloudformation stack for creating a new VPC, subnets, and other networking configurations. This stack is created in the target account and region, outputting the VPC ID, CIDR block, and subnets to the console. To generate the stack, use the following command:

astroctl cloud aws generate-vpc --region <target-region> --vpc-cidr 10.0.0.0/16 --cluster-name <cluster-name> --output-file vpc.yaml

After executing the command, you will receive a cloudformation stack file. Load this stack into your AWS account to create the VPC, subnet, and other networking configurations. You can customize this stack to manage your own VPC. This stack has all the necessary configurations to create an EKS cluster with BYOVPC via astro platform.

In this example, the customer brings their own VPC for the EKS cluster.

apiVersion: platform.astropulse.io/v1
kind: K8sCluster
spec:
  clusterName: my-eks-vpc-cluster
  provider: aws
  region: us-west-2
  provisioner:
    type: eks
    eks:
      accountId: "123456789012"  # your AWS account id
      vpcId: "vpc-12345678"      # your VPC id
      vpcCIDR: "10.0.0.0/16"     # your CIDR block
      subnets:
        us-west-2a:
          - type: public
            id: subnet-0b9e119bdba3f8add
          - type: private
            id: subnet-09ad1a17f7ee64ded
        us-west-2b:
          - type: public
            id: subnet-019c01369039cfb22
          - type: private
            id: subnet-0a40e1b1bb879d47c
        us-west-2c:
          - type: public
            id: subnet-0be1c43d23931e8b7
          - type: private
            id: subnet-072d6cdf209a85b7f
      tags:
        environment: "dev"
        owner: "foo@bar.com"
      credentials:
        type: dynamic  # uses assume role and aws sts to generate temporary keys
  clusterSpec:
    dataPlane:
      nodeGroups:
        - name: default-node-group
          minNode: 1
          maxNode: 3
          machineTypes:
            - t3.medium
          labels:
            environment: dev

For BYOVPC, the astroctl validates quota, permissions, and configurations before cluster creation. Ensure subnets are in the same region as the provisioner and follow the 3 availability zone, 3 public subnet, 3 private subnet pattern. The platform checks quota, permissions, and configurations, failing if any are not met.

Cluster Updates

EKS clusters support updates to Kubernetes version, node group configurations, and cluster settings. You can use either the Console UI or the CLI.

Option 1: Console (Upgrade Wizard)

The Console provides a guided 5-step upgrade wizard:

Preflight Check - Validates upgrade paths and checks for issues
Readiness Report - Generates comprehensive upgrade analysis with risk score
Pre-Upgrade Checklist - Interactive checklist with verification commands
Configuration - Select target version and rolling update settings
Confirmation - Review summary and confirm by typing cluster name

To access: Go to Clusters → Select cluster → Click Upgrade button

The wizard shows:

Visual version timeline (current → next → locked future versions)
Node group scaling controls (min/max nodes)
Rolling update settings (maxSurge, maxUnavailable)
Impact summary before execution

Option 2: CLI Commands

Version Discovery

# List available versions for this cluster
astroctl infra k8s upgrade <cluster-name> --list-versions

# Check versions for a region
astroctl cloud aws k8s-versions
astroctl cloud aws k8s-versions -r us-west-2
astroctl cloud aws k8s-versions --show-upgrade-paths

Kubernetes Version Upgrade

# Dry-run validation first
astroctl infra k8s upgrade <cluster-name> 1.30 --dry-run

# Generate readiness report
astroctl infra k8s upgrade <cluster-name> 1.30 --generate-report

# Execute upgrade
astroctl infra k8s upgrade <cluster-name> 1.30

# Skip confirmation (for automation)
astroctl infra k8s upgrade <cluster-name> 1.30 --yes

Rollback Node Groups

EKS control plane cannot be rolled back. Node groups are replaced with a blue-green deployment targeting the previous version.

# List versions available for rollback
astroctl infra k8s rollback <cluster-name> --list-versions

# Dry-run first — validates rollback path and warns about limitations
astroctl infra k8s rollback <cluster-name> 1.29 --dry-run

# Execute rollback
astroctl infra k8s rollback <cluster-name> 1.29 --yes

Scaling Node Groups

# List node groups
astroctl infra k8s scale <cluster-name> --list

# Preview changes first (dry-run)
astroctl infra k8s scale <cluster-name> <nodegroup-name> --min 3 --max 10 --dry-run

# Apply the scale
astroctl infra k8s scale <cluster-name> <nodegroup-name> --min 3 --max 10

Advanced Updates (YAML)

# Show YAML examples for your cluster
astroctl infra k8s update <cluster-name> --example

# Dry-run validation first
astroctl infra k8s update <cluster-name> -f update.yaml --dry-run

# Apply update
astroctl infra k8s update <cluster-name> -f update.yaml

# Skip confirmation (for automation)
astroctl infra k8s update <cluster-name> -f update.yaml --auto-approve

Monitor Progress

# Stream real-time progress
astroctl infra k8s progress stream <cluster-name>

# Get current status
astroctl infra k8s progress get <cluster-name>

# View operation history
astroctl infra k8s progress history <cluster-name>

Update File Reference

apiVersion: platform.astropulse.io/v1
kind: K8sClusterUpdate
spec:
  # Kubernetes version
  kubernetesVersion: "1.30"

  # Rolling update configuration
  updateConfig:
    maxSurge: "1"           # Nodes added during update (number or %)
    maxUnavailable: "1"     # Nodes down during update (number or %)
    dryRun: false           # Validate without applying
    generateReport: false   # Generate readiness report

  # Node groups
  nodeGroups:
    - name: "default-node-group"
      minNode: 2
      maxNode: 8
      machineTypes: ["t3.medium"]
      instanceType: "ondemand"  # or "spot"
      labels:
        workload: "general"

  # EKS-specific settings
  eks:
    amiFamily: "AmazonLinux2023"

  # Resource tags
  tags:
    environment: "production"

EKS Update Options

Field	Values	Description
`eks.amiFamily`	`AmazonLinux2023`, `AmazonLinux2`, `Bottlerocket`, `Ubuntu2004`, `Ubuntu2204`, `Ubuntu2404`	AMI family for nodes (changing triggers node replacement)

Rolling Update Strategy

Control the speed and safety of node group upgrades with --max-unavailable and --max-surge flags:

# Configure rolling update speed
astroctl infra k8s upgrade my-cluster 1.30 --max-unavailable 2 --max-surge 1

# Use percentage-based configuration
astroctl infra k8s upgrade my-cluster 1.30 --max-unavailable 25%

Smart Defaults: If you don't specify these flags, AstroPulse automatically determines optimal values:

Node Group Type	Default Strategy	Why
Small (1-3 nodes)	surge=1, unavailable=0	Maintain full capacity
Medium (4-10 nodes)	surge=2, unavailable=1	Balance speed and safety
Large (10+ nodes)	surge=10%, unavailable=10%	Percentage-based scaling
GPU nodes	surge=1, unavailable=0	Protect expensive resources
System/Critical	surge=1, unavailable=0	Ensure cluster stability

Upgrade Process

Control plane is upgraded first (AWS managed)
Node groups are upgraded using blue-green replacement
Karpenter provisioners are updated to use new AMIs
Progress is tracked and reported in real-time

Upgrade Considerations

EKS only supports upgrades to sequential minor versions (cannot skip versions)
Control plane cannot be downgraded after upgrade
Node groups use blue-green replacement strategy for zero-downtime upgrades
Always test upgrades in a non-production environment first

KubeConfig

With simple command like below, you can set the context to the cluster and have the access to the cluster. You need to make sure to install the kubectl CLI as required.

astroctl infra k8s set-context <cluster-name>

The cluster managed by the astro platform uses aws token to authenticate the kubectl. You need to make sure aws cli installed.

Added Capabilities

The EKS provisioner automatically provisions the following capabilities:

The EKS provisioner automatically enables the following capabilities for EKS clusters:

Karpenter: A flexible and efficient node provisioning service. You can tailor the provisioner to your needs by referring to the NodeClasses and NodePool documentation for more information.
- You can find the existing node classes and node pool by running kubectl -n karpenter get nodeclasses and kubectl -n karpenter get nodepools.
Required Roles: The necessary roles for Karpenter, External-DNS, Cert-Manager, and AWS-Load-Balancer-Controller are provisioned to ensure seamless integration.
AWS VPC CNI Plugin: This plugin is enabled to manage pod networking in your EKS cluster.
CoreDNS: A DNS service that provides name resolution for your cluster.

Additional Capabilities

You can always install addons by yourself by using the EKS marketplace.

Security

What you get out of the box

What	How
No stored AWS credentials	The platform uses IAM role assumption (AWS STS) to generate short-lived credentials (~15 minutes). No long-lived access keys are stored in AstroPulse infrastructure.
Least-privilege IAM roles	A dedicated IAM role is created in your account via CloudFormation with only the permissions needed to provision and manage your cluster.
OIDC enabled	AWS OIDC is enabled so your workloads can authenticate to AWS services (S3, Secrets Manager, etc.) using IAM roles — no access keys in pods.
Private node communication	Cluster nodes communicate with the control plane over the private endpoint. The public endpoint is used only for external management access.

How to harden further

Restrict public API server access to known CIDRs (recommended for production)

By default, the EKS public endpoint accepts connections from any IP. You can restrict this to specific CIDRs — your office network, VPN egress, or CI/CD egress IPs — via the AWS console or eksctl:

aws eks update-cluster-config \
  --name <cluster-name> \
  --region <region> \
  --resources-vpc-config publicAccessCidrs="35.206.79.104/32,203.0.113.0/24,10.0.0.0/8"

Include the AstroPulse egress IP

publicAccessCidrs applies to all connections — including the AstroPulse connector service. If you restrict the public endpoint without including the platform egress IP, application deployments will fail.

Always include 35.206.79.104/32 (AstroPulse platform egress IP):

--resources-vpc-config publicAccessCidrs="35.206.79.104/32,<your-office-cidr>,<your-vpn-cidr>"

BYOVPC for network isolation

Use vpcId and subnets to deploy EKS into your existing VPC. This lets you apply your own security groups, NACLs, and route tables to the cluster.

Private endpoint is always enabled

The private EKS endpoint is always enabled. Even if you restrict the public endpoint to specific CIDRs, nodes and internal workloads continue to communicate with the control plane over the private endpoint — your cluster stays fully operational.

AWS EKS Cluster Provisioner​

AWS EKS Specification​

Prerequisites​

Required tools​

Finding your AWS credentials​

Connect your AWS account​

Complete Field Reference​

Core Fields​

Networking Fields (BYOVPC)​

Cluster Configuration Fields​

Field Validation Rules​

EKS Networking Architecture​

Supported CIDR Ranges​

Bring Your Own Account (BYOA)​

Bring Your Own VPC (BYOVPC)​

Cluster Updates​

Option 1: Console (Upgrade Wizard)​

Option 2: CLI Commands​

Version Discovery​

Kubernetes Version Upgrade​

Rollback Node Groups​

Scaling Node Groups​

Advanced Updates (YAML)​

Monitor Progress​

Update File Reference​

EKS Update Options​

Rolling Update Strategy​

Upgrade Process​

KubeConfig​

Added Capabilities​

Security​

What you get out of the box​

How to harden further​