EKS Cluster Setup

Skip this guide if you already have an EKS cluster with sufficient CPU/memory and the ability to create LoadBalancer services. Proceed directly to PrivateLink or Hybrid Edition.

This guide provisions a production-ready EKS cluster from scratch — VPC with public/private subnets, IAM roles, node groups, and required add-ons.

Prerequisites

AWS CLI v2 configured with appropriate credentials
kubectl installed
Helm v3 installed
An AWS account with permissions to create EKS clusters, VPCs, and IAM roles

1. Create a VPC

Create a VPC with public and private subnets across two availability zones.

# Create VPC
aws ec2 create-vpc \
  --cidr-block 10.100.0.0/16 \
  --tag-specifications 'ResourceType=vpc,Tags=[{Key=Name,Value=xpander-vpc},{Key=Project,Value=xpander}]' \
  --region <REGION> --profile <PROFILE>

# Enable DNS
aws ec2 modify-vpc-attribute --vpc-id <VPC_ID> --enable-dns-support '{"Value":true}' \
  --region <REGION> --profile <PROFILE>
aws ec2 modify-vpc-attribute --vpc-id <VPC_ID> --enable-dns-hostnames '{"Value":true}' \
  --region <REGION> --profile <PROFILE>

Create four subnets:

Subnet	CIDR	AZ	Type	Tag
public-a	`10.100.1.0/24`	AZ-a	Public	`kubernetes.io/role/elb: 1`
public-b	`10.100.2.0/24`	AZ-b	Public	`kubernetes.io/role/elb: 1`
private-a	`10.100.10.0/24`	AZ-a	Private	`kubernetes.io/role/internal-elb: 1`
private-b	`10.100.20.0/24`	AZ-b	Private	`kubernetes.io/role/internal-elb: 1`

# Create subnets (repeat for each)
aws ec2 create-subnet \
  --vpc-id <VPC_ID> \
  --cidr-block <CIDR> \
  --availability-zone <AZ> \
  --tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=<NAME>},{Key=kubernetes.io/role/elb,Value=1}]' \
  --region <REGION> --profile <PROFILE>

2. Create Internet Gateway and NAT Gateway

Air-Gapped installs skip this step. A sealed VPC has no internet or NAT gateways; the cluster reaches AWS services through VPC endpoints instead — at minimum ecr.api, ecr.dkr, and the S3 gateway endpoint (image pulls when your mirror is ECR), ec2 and sts, plus eks-auth if any add-on uses EKS Pod Identity (the EBS CSI setup below does). Add bedrock-runtime when using Bedrock over PrivateLink, and the ssm/ssmmessages/ec2messages trio if operators connect through Session Manager.

# Internet Gateway
aws ec2 create-internet-gateway \
  --tag-specifications 'ResourceType=internet-gateway,Tags=[{Key=Name,Value=xpander-igw}]' \
  --region <REGION> --profile <PROFILE>
aws ec2 attach-internet-gateway --internet-gateway-id <IGW_ID> --vpc-id <VPC_ID> \
  --region <REGION> --profile <PROFILE>

# Elastic IP for NAT
aws ec2 allocate-address --domain vpc --region <REGION> --profile <PROFILE>

# NAT Gateway (in a public subnet)
aws ec2 create-nat-gateway \
  --subnet-id <PUBLIC_SUBNET_A_ID> \
  --allocation-id <EIP_ALLOC_ID> \
  --tag-specifications 'ResourceType=natgateway,Tags=[{Key=Name,Value=xpander-nat}]' \
  --region <REGION> --profile <PROFILE>

3. Route Tables

# Public route table → Internet Gateway
aws ec2 create-route-table --vpc-id <VPC_ID> --region <REGION> --profile <PROFILE>
aws ec2 create-route --route-table-id <PUBLIC_RT_ID> \
  --destination-cidr-block 0.0.0.0/0 --gateway-id <IGW_ID> \
  --region <REGION> --profile <PROFILE>
aws ec2 associate-route-table --route-table-id <PUBLIC_RT_ID> \
  --subnet-id <PUBLIC_SUBNET_A_ID> --region <REGION> --profile <PROFILE>
aws ec2 associate-route-table --route-table-id <PUBLIC_RT_ID> \
  --subnet-id <PUBLIC_SUBNET_B_ID> --region <REGION> --profile <PROFILE>

# Private route table → NAT Gateway
aws ec2 create-route-table --vpc-id <VPC_ID> --region <REGION> --profile <PROFILE>
aws ec2 create-route --route-table-id <PRIVATE_RT_ID> \
  --destination-cidr-block 0.0.0.0/0 --nat-gateway-id <NAT_GW_ID> \
  --region <REGION> --profile <PROFILE>
aws ec2 associate-route-table --route-table-id <PRIVATE_RT_ID> \
  --subnet-id <PRIVATE_SUBNET_A_ID> --region <REGION> --profile <PROFILE>
aws ec2 associate-route-table --route-table-id <PRIVATE_RT_ID> \
  --subnet-id <PRIVATE_SUBNET_B_ID> --region <REGION> --profile <PROFILE>

4. IAM Roles

EKS Cluster Role

# Create cluster role
aws iam create-role \
  --role-name xpander-eks-cluster-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": { "Service": "eks.amazonaws.com" },
        "Action": ["sts:AssumeRole", "sts:TagSession"]
      }
    ]
  }' \
  --profile <PROFILE>

# Attach policies
aws iam attach-role-policy --role-name xpander-eks-cluster-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSClusterPolicy --profile <PROFILE>
aws iam attach-role-policy --role-name xpander-eks-cluster-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSComputePolicy --profile <PROFILE>
aws iam attach-role-policy --role-name xpander-eks-cluster-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSBlockStoragePolicy --profile <PROFILE>
aws iam attach-role-policy --role-name xpander-eks-cluster-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSLoadBalancingPolicy --profile <PROFILE>
aws iam attach-role-policy --role-name xpander-eks-cluster-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSNetworkingPolicy --profile <PROFILE>

Node Role

aws iam create-role \
  --role-name xpander-node-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": { "Service": "ec2.amazonaws.com" },
        "Action": "sts:AssumeRole"
      }
    ]
  }' \
  --profile <PROFILE>

aws iam attach-role-policy --role-name xpander-node-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy --profile <PROFILE>
aws iam attach-role-policy --role-name xpander-node-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy --profile <PROFILE>
aws iam attach-role-policy --role-name xpander-node-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly --profile <PROFILE>
aws iam attach-role-policy --role-name xpander-node-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore --profile <PROFILE>
aws iam attach-role-policy --role-name xpander-node-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy --profile <PROFILE>

5. Create EKS Cluster

aws eks create-cluster \
  --name xpander-cluster \
  --role-arn arn:aws:iam::<ACCOUNT_ID>:role/xpander-eks-cluster-role \
  --kubernetes-version 1.35 \
  --resources-vpc-config "subnetIds=<ALL_SUBNET_IDS>,endpointPublicAccess=true,endpointPrivateAccess=true,publicAccessCidrs=<YOUR_IP>/32" \
  --access-config "authenticationMode=API" \
  --region <REGION> --profile <PROFILE>

Wait for the cluster to become active (~10 minutes):

aws eks wait cluster-active --name xpander-cluster --region <REGION> --profile <PROFILE>

6. Create Node Group

xpander container images are amd64 only. Do not use ARM/Graviton instances (t4g, m7g, c7g, etc.).

Minimum requirements:

Recommended minimum: 3 × m5.xlarge nodes (or 2 × t3.xlarge for evaluation)
xpander platform pod requests: ~5 vCPU / ~10 GiB memory at single-replica defaults
Add ~2 vCPU / 2.5 GiB per additional Agent Worker replica, plus capacity for active agent workspaces
Plan additional headroom for Kubernetes system pods, DaemonSets, upgrades, and burst capacity
See Sizing & Resource Requirements for per-service numbers and a calculator that sizes the cluster for your user count.

aws eks create-nodegroup \
  --cluster-name xpander-cluster \
  --nodegroup-name xpander-nodes \
  --node-role arn:aws:iam::<ACCOUNT_ID>:role/xpander-node-role \
  --subnets <PRIVATE_SUBNET_A_ID> <PRIVATE_SUBNET_B_ID> \
  --instance-types t3.large \
  --ami-type AL2023_x86_64_STANDARD \
  --scaling-config minSize=2,maxSize=4,desiredSize=3 \
  --capacity-type ON_DEMAND \
  --region <REGION> --profile <PROFILE>

Wait for the node group:

aws eks wait nodegroup-active \
  --cluster-name xpander-cluster \
  --nodegroup-name xpander-nodes \
  --region <REGION> --profile <PROFILE>

7. Configure kubectl

aws eks update-kubeconfig --name xpander-cluster --region <REGION> --profile <PROFILE>
kubectl get nodes  # Verify nodes are Ready

EKS Add-Ons

Install the required EKS add-ons for networking, DNS, storage, and pod identity.

# VPC CNI (pod networking)
aws eks create-addon --cluster-name xpander-cluster --addon-name vpc-cni \
  --resolve-conflicts OVERWRITE --region <REGION> --profile <PROFILE>

# CoreDNS (cluster DNS)
aws eks create-addon --cluster-name xpander-cluster --addon-name coredns \
  --resolve-conflicts OVERWRITE --region <REGION> --profile <PROFILE>

# kube-proxy
aws eks create-addon --cluster-name xpander-cluster --addon-name kube-proxy \
  --resolve-conflicts OVERWRITE --region <REGION> --profile <PROFILE>

# EBS CSI Driver (persistent volumes)
aws eks create-addon --cluster-name xpander-cluster --addon-name aws-ebs-csi-driver \
  --resolve-conflicts OVERWRITE --region <REGION> --profile <PROFILE>

# Pod Identity Agent
aws eks create-addon --cluster-name xpander-cluster --addon-name eks-pod-identity-agent \
  --resolve-conflicts OVERWRITE --region <REGION> --profile <PROFILE>

# Metrics Server
aws eks create-addon --cluster-name xpander-cluster --addon-name metrics-server \
  --resolve-conflicts OVERWRITE --region <REGION> --profile <PROFILE>

EBS CSI IAM Setup (Pod Identity)

The EBS CSI driver needs IAM permissions to provision volumes.

# Create IAM role for EBS CSI
aws iam create-role \
  --role-name xpander-ebs-csi-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": { "Service": "pods.eks.amazonaws.com" },
        "Action": ["sts:AssumeRole", "sts:TagSession"]
      }
    ]
  }' \
  --profile <PROFILE>

aws iam attach-role-policy --role-name xpander-ebs-csi-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy --profile <PROFILE>

# Associate with service account
aws eks create-pod-identity-association \
  --cluster-name xpander-cluster \
  --namespace kube-system \
  --service-account ebs-csi-controller-sa \
  --role-arn arn:aws:iam::<ACCOUNT_ID>:role/xpander-ebs-csi-role \
  --region <REGION> --profile <PROFILE>

Create Default StorageClass

kubectl apply -f - <<'EOF'
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  fsType: ext4
  encrypted: "true"
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
EOF

Encrypt every volume. The platform’s PVCs hold customer data — agent workspaces, the data tier, Supabase storage, knowledge-base content — so the StorageClass above enables EBS encryption at rest (encrypted: "true", using the account’s default aws/ebs KMS key). To use a customer-managed key instead, add kmsKeyId: "<key-arn>" to parameters and grant the EBS CSI driver’s role kms:CreateGrant/kms:Decrypt/kms:GenerateDataKey* on it. Compliance-sensitive deployments should treat an encrypted StorageClass as a hard requirement, not an option.

Next Steps

Your EKS cluster is ready. Continue with:

PrivateLink — If your security policy requires traffic to stay within the AWS network
Hybrid Edition — the installer wizard, plus SSL, ingress, DNS, and verification

Overview

Platform

Getting Started

Building Agents

Workflows

Agentic Automation

Observability

Deployment Channels

Self-Hosted

Security & Compliance

Building In-Product Agents

Prerequisites

1. Create a VPC

2. Create Internet Gateway and NAT Gateway

3. Route Tables

4. IAM Roles

5. Create EKS Cluster

6. Create Node Group

7. Configure kubectl

EKS Add-Ons

EBS CSI IAM Setup (Pod Identity)

Create Default StorageClass

Next Steps

​Prerequisites

​1. Create a VPC

​2. Create Internet Gateway and NAT Gateway

​3. Route Tables

​4. IAM Roles

​5. Create EKS Cluster

​6. Create Node Group

​7. Configure kubectl

​EKS Add-Ons

​EBS CSI IAM Setup (Pod Identity)

​Create Default StorageClass

​Next Steps

Prerequisites

1. Create a VPC

2. Create Internet Gateway and NAT Gateway

3. Route Tables

4. IAM Roles

5. Create EKS Cluster

6. Create Node Group

7. Configure kubectl

EKS Add-Ons

EBS CSI IAM Setup (Pod Identity)

Create Default StorageClass

Next Steps