EKS Cluster Setup

Build an EKS cluster for xpander from scratch: VPC, IAM, nodes and add-ons.

Skip this guide if your EKS cluster has enough CPU and memory and can create LoadBalancer services. Go to PrivateLink or Hybrid deployment.

On EKS Auto Mode, three steps change: see EKS Auto Mode. Air-Gapped installs skip step 2.

Prerequisites

AWS CLI v2 with credentials, kubectl, Helm v3, and permission to create EKS clusters, VPCs and IAM roles.

---

1. Create a VPC

# 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>

Four subnets across two availability zones:

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 and reach AWS through VPC endpoints:

VPC endpoints	When
ecr.api, ecr.dkr, and the S3 gateway endpoint	Always (image pulls when your mirror is ECR)
ec2 and sts	Always
eks-auth	If any add-on uses EKS Pod Identity (the EBS CSI setup below does)
bedrock-runtime	When using Bedrock over PrivateLink
ssm, ssmmessages and ec2messages	If operators connect through Session Manager

Keyless Bedrock on any private-subnet cluster (Hybrid included) also needs sts, eks-auth (Pod Identity) and bedrock-runtime endpoints.

# 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 the 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 about 10 minutes for the cluster:

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

6. Create a node group

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

Minimum requirements:

Item	Value
Recommended minimum	3 × m5.xlarge nodes
xpander pod requests	~8 vCPU / ~20 GiB memory at chart defaults (single replicas, one executor, the LLM Gateway’s two pods)
Each additional agent-worker replica	Add ~2 vCPU / 2.5 GiB, plus capacity for active agent workspaces
Headroom	Plan extra for Kubernetes system pods, DaemonSets, upgrades, and burst capacity

Per-service numbers and a calculator: Sizing & Resource Requirements.

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 m5.xlarge \
  --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

Add-on	What it does
vpc-cni	Pod networking
coredns	Cluster DNS
kube-proxy	Kubernetes service networking
aws-ebs-csi-driver	Persistent volumes
eks-pod-identity-agent	Pod Identity
metrics-server	Resource metrics

# 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)

# 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. xpander’s PVCs hold customer data. The StorageClass above sets encrypted: "true" with the default aws/ebs KMS key. For a customer-managed key, add kmsKeyId: "<key-arn>" to parameters and grant the EBS CSI role kms:CreateGrant, kms:Decrypt and kms:GenerateDataKey*. Treat encryption as required for compliance-sensitive deployments.

---

EKS Auto Mode

AWS runs storage, load balancing and nodes for you. Three things change:

Change	Classic EKS (this guide)	EKS Auto Mode
Storage provisioner	ebs.csi.aws.com	ebs.csi.eks.amazonaws.com
IngressClass	From the load balancer controller	None shipped. Create an IngressClassParams and an IngressClass
IAM for pods	Pod Identity for the EBS CSI driver	Pod Identity for xpander’s service accounts

1. Storage provisioner. Skip the aws-ebs-csi-driver add-on and its role. A StorageClass on ebs.csi.aws.com never binds on Auto Mode. Use ebs.csi.eks.amazonaws.com in the default StorageClass and the chart’s fleet class:

   # Air-Gapped chart; on Hybrid the same keys sit under fleet.storage
   global:
     fleet:
       storage:
         createClass: true
         provisioner: ebs.csi.eks.amazonaws.com
   

2. IngressClass. Auto Mode ships no IngressClass and ignores the alb.ingress.kubernetes.io/group.name annotation, so it creates one ALB per Ingress. Create an IngressClassParams with the scheme and group, and an IngressClass that references it, and set the chart’s className to it. Repeat with scheme: internal for private hosts such as deployment-manager or an internal IdP.

   apiVersion: eks.amazonaws.com/v1
   kind: IngressClassParams
   metadata:
     name: alb
   spec:
     scheme: internet-facing
     group:
       name: xpander
   ---
   apiVersion: networking.k8s.io/v1
   kind: IngressClass
   metadata:
     name: alb
   spec:
     controller: eks.amazonaws.com/alb
     parameters:
       apiGroup: eks.amazonaws.com
       kind: IngressClassParams
       name: alb
   

3. IAM for pods. Bind Bedrock and S3 permissions to the default and agent-controller service accounts with aws eks create-pod-identity-association, as in the EBS CSI example. Keep the eks-pod-identity-agent add-on.

---

Before you install on Auto Mode

• Cluster access for the installer’s identity. With authenticationMode=API, IAM roles get nothing by default. Give the role that runs kubectl and Helm an access entry with AmazonEKSClusterAdminPolicy:

  aws eks create-access-entry --cluster-name <cluster> --principal-arn <role arn>
  aws eks associate-access-policy --cluster-name <cluster> --principal-arn <role arn> \
    --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy --access-scope type=cluster
  

• Node consolidation during the install. The built-in general-purpose NodePool consolidates after thirty seconds and reverts patches, so an install can lose nodes mid-schedule. Add a higher-weight NodePool:

  apiVersion: karpenter.sh/v1
  kind: NodePool
  metadata:
    name: xpander-stable
  spec:
    weight: 100
    disruption:
      consolidationPolicy: WhenEmptyOrUnderutilized
      consolidateAfter: 10m
    template:
      spec:
        nodeClassRef: { group: eks.amazonaws.com, kind: NodeClass, name: default }
        requirements:
          - { key: karpenter.sh/capacity-type, operator: In, values: ["on-demand"] }
          - { key: kubernetes.io/arch, operator: In, values: ["amd64"] }
          - { key: eks.amazonaws.com/instance-category, operator: In, values: ["c", "m", "r"] }
          - { key: eks.amazonaws.com/instance-generation, operator: Gt, values: ["4"] }
  

• Fresh nodes refuse kubectl exec for a moment. Until the kubelet certificate is signed, kubectl exec and kubectl run -i fail with tls: internal error. Retry after a few seconds, also in pipelines.

Next steps

Keep traffic inside AWS with PrivateLink

When traffic must stay in AWS.

Install xpander Hybrid

The installer wizard.