Amazon EKS
AstroPulse creates and runs an Amazon EKS cluster in your AWS account. AWS runs the control plane; you choose the node groups, and AstroPulse creates, updates and deletes them with the cluster. AstroPulse works in the account with short-lived credentials from a role you create once per cluster, on the Connect step; no AWS access key is stored in a cluster manifest. This page is the AWS reference; the full walkthrough is Create a cluster.
Before you start
- Your 12-digit AWS account ID, and permission to create a CloudFormation stack and IAM roles in it.
- A region whose machines and Kubernetes versions fit the workload. For GPUs, compare models, zones and prices under Infrastructure › Accelerators first.
- Room in the account's service quotas for the machines you pick, and for a VPC unless you bring your own.
- If you connect the VPC to other networks, a range that does not overlap them.
The AWS CLI, kubectl and astroctl are not needed for the console. Use them for automation or direct access.
In the console
Create a cluster walks through every step with an EKS cluster. What is particular to AWS:
- Name and cloud. Node groups use the region's first three zones unless you pick zones for a group.
- Account. Under How Kubernetes runs, pick Amazon EKS. The Account ID is 12 digits.
- Connect. Creates a CloudFormation stack in the AWS tab that opens (what it creates).
- Kubernetes. Adds the Compute Mode (Managed node groups or Auto Mode) and the AMI Family for node groups.
- Network. The collapsed section under Use Existing VPC holds the new VPC's CIDR Block (Optional) and Image registries in other AWS accounts (ECR) (Networking).
- Node groups. Each group runs at its Nodes count (Node groups). With Auto Mode, this step is skipped.
The dry run on Review checks the account, quotas, machines in each zone and the VPC.
You should see
The cluster's page reads Ready and Connected once it is up, its node groups have the nodes you set, and Events shows each stage of the create without a failure. Creating an EKS cluster takes several minutes.
Connect the AWS account
A connection belongs to one cluster: its name, account and region. Connect this account opens AWS's CloudFormation console in a new tab with a stack ready to create. Review it, create it, and come back: the step checks the account every few seconds and reads Connected when AstroPulse can use the role. An account already connected for this cluster reads "Already connected to Amazon Web Services." with the Account, Region and Last verified.
The stack creates, in your account:
- An IAM role named
astro-target-<id>that AstroPulse assumes to create and manage the cluster. Its trust policy requires an external ID unique to the connection, and a session lasts at most 12 hours. - A permissions boundary and the policies the role works under, scoped to creating and running the cluster: EKS, its network, its compute and the IAM roles its nodes use.
Each cluster AstroPulse creates also gets an IAM role for its vulnerability scanner that can only pull images from ECR, so private images can be scanned.
When AWS refuses the role later, the step says so and offers Update the connection or Connect again, which updates the same stack. Infrastructure › Cloud accounts lists every connection and its state.
Node groups
Managed node groups are fixed capacity: each runs at the number of nodes you set, so the console asks for Nodes, not a minimum and a maximum. For nodes that come and go with demand, install Node Autoscaling from the cluster's Add-ons tab once it is ready, or choose Auto Mode. A managed node group cannot have minNode: 0: nothing on the cluster would scale it back up.
- Pick machine types pins one or more machine types; Choose machines opens the catalog with prices.
- Request GPU hardware names a GPU model and Devices per node; AstroPulse picks the cheapest machine in the region that carries exactly that GPU, and the dry run shows which under Machines AstroPulse chose. GPU node groups need Kubernetes 1.36 or newer: GPU node groups.
- Pricing is On-Demand or Spot. Spot costs less, but AWS can take a node back at short notice. Keep at least one On-Demand group of 1 node or more for AstroPulse's system pods; with only Spot groups the dry run warns System pods run only on Spot nodes. Capacity your account already holds, an EC2 capacity reservation or a Capacity Block, shows under Capacity you already hold and is used as is; AstroPulse never buys it.
Compute mode
computeMode is fixed when the cluster is created:
ManagedNodeGroups(the default): you declare node groups underclusterSpec.dataPlane, and AstroPulse creates and manages them.AutoMode: AWS provisions nodes from workload demand. LeaveclusterSpec.dataPlaneout: a request with node groups is refused. The Node Autoscaling add-on is refused too, because Auto Mode already manages capacity.
provisioner:
type: eks
eks:
computeMode: AutoMode
autoMode:
enableGpuNodePool: true # optional: let Auto Mode provision GPU instances
gpuLimit: 10 # optional: GPUs across the pool, 1 to 1000, default 10
gpuCapacityTypes: ["OnDemand"] # optional: OnDemand, Spot or both
Auto Mode provisions no GPU nodes on its own. autoMode.enableGpuNodePool adds a GPU pool: its nodes are tainted nvidia.com/gpu:NoSchedule, so pods need a matching toleration, and AWS owns the NVIDIA driver and device plugin on them. gpuCapacityTypes is how the pool buys GPU nodes: a new cluster's pool buys OnDemand unless you list Spot, and an update that leaves it out keeps what the pool buys. An update dry run warns when the pool starts buying Spot (ClusterGPUPoolBuysSpot) and when it stops, which replaces its Spot nodes with On-Demand ones (ClusterGPUPoolDropsSpot). Keep serving on On-Demand and use Spot for work that can restart.
Networking
EKS uses subnets per zone: a public and a private subnet in each of the cluster's three zones. Nodes run in the private subnets and reach the internet through a NAT gateway; load balancers use the public ones. Networking has the diagrams.
The Kubernetes API server endpoint has both private and public access on: nodes reach it inside the VPC, and you reach it from outside, for example with kubectl.
A new VPC
With Use Existing VPC off, AstroPulse creates the VPC, its subnets, gateways and routes with the cluster, and deletes them with it. vpcCIDR sets its range; left empty, the platform picks one.
Supported CIDR ranges
The range must be a /16 to /24 inside one of:
| Range | Notes |
|---|---|
10.0.0.0/8 | RFC 1918, the usual choice for production |
172.16.0.0/12 | RFC 1918, 172.16.x.x to 172.31.x.x |
192.168.0.0/16 | RFC 1918 |
100.64.0.0/10 | Shared address space |
198.19.0.0/16 | Benchmarking range, also accepted |
Use a /16 for production, so pods, services and later subnets have room, and keep it clear of networks you connect over VPN or Direct Connect.
Bring your own VPC
Turn on Network › Use Existing VPC and enter the VPC ID, the VPC CIDR Block, and a Public Subnet and Private Subnet for each zone. Setup Commands under it shows the commands below, filled in with your cluster name, region and range.
A VPC you bring is yours: deleting the cluster keeps it.
Create a VPC from the AstroPulse template
-
Generate the CloudFormation template:
Terminalastroctl cloud aws generate-vpc -r us-west-2 -v 10.60.0.0/16 -c eks-byovpc --output-file vpc.yamlIt holds a VPC with DNS support, a public and a private subnet in each of three zones, an internet gateway, a NAT gateway per zone, route tables, and the subnet tags.
-
Deploy it and read its outputs:
Terminalaws cloudformation deploy --template-file vpc.yaml --stack-name eks-byovpc-vpc --region us-west-2aws cloudformation describe-stacks --stack-name eks-byovpc-vpc --region us-west-2 \--query "Stacks[0].Outputs" --output table -
Put the outputs into the cluster manifest: the VPC ID into
vpcId, the CIDR intovpcCIDR, and each zone's public and private subnet intosubnets:eks-byovpc.yamlapiVersion: platform.astropulse.io/v1kind: K8sClusterspec:clusterName: eks-byovpcprovider: awsregion: us-west-2clusterSpec:dataPlane:nodeGroups:- name: systemminNode: 1maxNode: 1machineTypes: [t3.medium, t3a.medium]instanceType: OnDemandprovisioner:type: ekseks:accountId: "123456789012"vpcId: vpc-0123456789abcdef0vpcCIDR: 10.60.0.0/16subnets:us-west-2a:- {type: Public, id: subnet-0aaaaaaaaaaaaaaa1}- {type: Private, id: subnet-0aaaaaaaaaaaaaaa2}us-west-2b:- {type: Public, id: subnet-0bbbbbbbbbbbbbbb1}- {type: Private, id: subnet-0bbbbbbbbbbbbbbb2}us-west-2c:- {type: Public, id: subnet-0ccccccccccccccc1}- {type: Private, id: subnet-0ccccccccccccccc2}credentials:type: Dynamic123456789012and the VPC and subnet IDs stand for your own. -
Dry-run, then create:
Terminalastroctl infra k8s apply -f eks-byovpc.yaml --dry-runastroctl infra k8s apply -f eks-byovpc.yamlThe dry run checks the VPC before anything is created:
[PASS] VPC / Network: VPC vpc-0123456789abcdef0 validated: DNS support, DNS hostnames enabled (CIDR: 10.60.0.0/16)[PASS] VPC / Network: Internet gateway attached to VPC vpc-0123456789abcdef0[PASS] Routing Tables: Public subnet subnet-0aaaaaaaaaaaaaaa1 has internet gateway route[PASS] Routing Tables: Private subnet subnet-0aaaaaaaaaaaaaaa2 has NAT gateway route to public subnet subnet-0aaaaaaaaaaaaaaa1[PASS] Subnet Configuration: Public subnet subnet-0aaaaaaaaaaaaaaa1 has MapPublicIpOnLaunch enabled[PASS] Subnet Configuration: Subnet pair for zone us-west-2a validated (public: subnet-0aaaaaaaaaaaaaaa1, private: subnet-0aaaaaaaaaaaaaaa2)...[PASS] Subnet IP Capacity: Subnet IP capacity sufficient: 49119 available across 6 subnets for 1 nodes[SKIPPED] VPC Quota: No new VPC is created[SKIPPED] Subnet Quota: No new subnets are created -
To remove it after the cluster, delete the cluster first, then the stack. Its three NAT gateways and Elastic IPs are billed until you delete the stack.
Terminalastroctl infra k8s delete eks-byovpcWhen the delete finishes, its result names any volume it kept, for example This volume is still in your cloud account: astro-security/data-trivy-server-0 (5Gi, astro-default-gp3, vol-0123456789abcdef0). Delete it if you no longer need it. Delete those volumes, then the stack:
Terminalaws ec2 delete-volume --region us-west-2 --volume-id vol-0123456789abcdef0aws cloudformation delete-stack --stack-name eks-byovpc-vpc --region us-west-2aws cloudformation wait stack-delete-complete --stack-name eks-byovpc-vpc --region us-west-2While the cluster's network interfaces are still in the VPC, the stack delete fails. Delete a cluster lists everything else a delete keeps.
Bring a VPC you already have
Your VPC passes the dry run when it has:
- A VPC that is not the default VPC, with DNS support and DNS hostnames on, and
vpcCIDRequal to its CIDR, inside the ranges above. - An internet gateway attached.
- The region's first three zones (for example
us-west-2a,bandc), each with one public and one private subnet insubnets. - Public subnets that route
0.0.0.0/0to the internet gateway and have MapPublicIpOnLaunch on. - Private subnets that route to the internet through a NAT gateway in the same zone's public subnet. Nodes need it to pull images and reach AstroPulse.
- Enough free addresses: about 30 per node.
Also add the subnet tags; the dry run does not check them.
To fill in vpcCIDR and subnets, read the VPC with the AWS CLI. Each
command is read-only.
-
The VPC's CIDR, and whether it is the default VPC:
Terminalaws ec2 describe-vpcs --region us-west-2 --vpc-ids vpc-0123456789abcdef0 \--query "Vpcs[0].[CidrBlock,IsDefault]" --output text10.60.0.0/16 False -
Its subnets, by zone. The fourth column is MapPublicIpOnLaunch, the fifth the free addresses:
Terminalaws ec2 describe-subnets --region us-west-2 --filters Name=vpc-id,Values=vpc-0123456789abcdef0 \--query "sort_by(Subnets,&AvailabilityZone)[].[AvailabilityZone,SubnetId,CidrBlock,MapPublicIpOnLaunch,AvailableIpAddressCount]" \--output table-------------------------------------------------------------------------------| DescribeSubnets |+------------+----------------------------+-----------------+--------+--------+| us-west-2a| subnet-0aaaaaaaaaaaaaaa1 | 10.60.0.0/19 | True | 8186 || us-west-2a| subnet-0aaaaaaaaaaaaaaa2 | 10.60.96.0/19 | False | 8187 || us-west-2b| subnet-0bbbbbbbbbbbbbbb2 | 10.60.128.0/19 | False | 8186 || us-west-2b| subnet-0bbbbbbbbbbbbbbb1 | 10.60.32.0/19 | True | 8186 || us-west-2c| subnet-0ccccccccccccccc2 | 10.60.160.0/19 | False | 8156 || us-west-2c| subnet-0ccccccccccccccc1 | 10.60.64.0/19 | True | 8186 |+------------+----------------------------+-----------------+--------+--------+ -
Where each subnet sends internet traffic. A subnet whose route goes to an internet gateway (
igw-) is public; one whose route goes to a NAT gateway (nat-) is private:Terminalaws ec2 describe-route-tables --region us-west-2 --filters Name=vpc-id,Values=vpc-0123456789abcdef0 \--query "RouteTables[?Associations[?SubnetId]].{Subnets:join(\`,\`,Associations[?SubnetId].SubnetId),Internet:Routes[?DestinationCidrBlock==\`0.0.0.0/0\`].[NatGatewayId || GatewayId][0][0]}" \--output table---------------------------------------------------------------------------------------------------------| DescribeRouteTables |+-----------------------+-------------------------------------------------------------------------------+| Internet | Subnets |+-----------------------+-------------------------------------------------------------------------------+| igw-0123456789abcdef0| subnet-0ccccccccccccccc1,subnet-0bbbbbbbbbbbbbbb1,subnet-0aaaaaaaaaaaaaaa1 || nat-0ccccccccccccccc0| subnet-0ccccccccccccccc2 || nat-0aaaaaaaaaaaaaaa0| subnet-0aaaaaaaaaaaaaaa2 || nat-0bbbbbbbbbbbbbbb0| subnet-0bbbbbbbbbbbbbbb2 |+-----------------------+-------------------------------------------------------------------------------+A subnet missing from this table has no route table of its own and uses the VPC's main route table. The dry run fails it: associate a route table with it.
-
Which public subnet each NAT gateway is in. It must sit in the public subnet of the same zone as the private subnet it serves, with connectivity type
publicand stateavailable:Terminalaws ec2 describe-nat-gateways --region us-west-2 --filter Name=vpc-id,Values=vpc-0123456789abcdef0 \--query "NatGateways[].[NatGatewayId,SubnetId,ConnectivityType,State]" --output table------------------------------------------------------------------------------| DescribeNatGateways |+------------------------+----------------------------+---------+------------+| nat-0bbbbbbbbbbbbbbb0 | subnet-0bbbbbbbbbbbbbbb1 | public | available || nat-0aaaaaaaaaaaaaaa0 | subnet-0aaaaaaaaaaaaaaa1 | public | available || nat-0ccccccccccccccc0 | subnet-0ccccccccccccccc1 | public | available |+------------------------+----------------------------+---------+------------+
Put each zone's public and private subnet into subnets as in the
manifest above, with the CIDR from step 1 as vpcCIDR.
When a VPC check fails
The dry run names the check and what it found:
vpcCIDR is not the VPC's CIDR.vpcCIDR to the VPC's CIDR.aws ec2 modify-vpc-attribute --vpc-id <vpc> --enable-dns-support.aws ec2 modify-vpc-attribute --vpc-id <vpc> --enable-dns-hostnames.subnets does not exist in that region and account.aws ec2 modify-subnet-attribute --subnet-id <subnet> --map-public-ip-on-launch.0.0.0.0/0 to the internet gateway.A private subnet that reaches the internet through something other than a NAT gateway, such as a firewall or transit gateway, gets a warning instead of a pass: make sure it forwards traffic to the internet and to your container registries.
Subnet tags
Load balancers find the subnets by their tags. Replace <cluster> with the
cluster name:
| Subnets | Tags |
|---|---|
| Public | kubernetes.io/cluster/<cluster>: shared, kubernetes.io/role/elb: 1 |
| Private | kubernetes.io/cluster/<cluster>: shared, kubernetes.io/role/internal-elb: 1 |
The cluster tag's value can be shared or owned; load balancers accept
either. Use shared: the VPC is yours and outlives the cluster. The AstroPulse
template tags every subnet shared, adds karpenter.sh/discovery: <cluster>
to the private subnets only, and names its resources eks-<cluster>-cluster/...,
so a cluster named eks-byovpc gives eks-eks-byovpc-cluster/PublicSubnetUSWEST2A.
Images from other AWS accounts
Nodes pull from the cluster's own account's ECR with no secret. To pull from ECR in other accounts, add up to 20 account IDs under Image registries in other AWS accounts (ECR) (ecrAccountIds). After the cluster is created, add its node roles, which the cluster's page lists under Cloud identity, to each account's repository policy.
Kubernetes versions
AstroPulse default sends no version, and the platform picks its own default. Any other version must be one EKS offers in the region; a short form like <major>.<minor> picks the newest matching patch. GPU node groups need 1.36 or newer. To list what EKS offers:
astroctl cloud aws k8s-versions -r us-west-2
astroctl cloud aws k8s-versions --show-upgrade-paths
AstroPulse plans every upgrade one minor version at a time, and an EKS control plane cannot be rolled back.
Updates and upgrades
The cluster's Update tab upgrades Kubernetes, changes node groups, and edits the AMI family and tags; Node groups › Modify changes one group. Each change runs a dry run first and shows on Events as it runs. Update and upgrade covers every surface; what is particular to EKS:
- The control plane upgrades first, then each managed node group, one after another, by AWS's own rolling update, which adds the replacement nodes first.
--max-unavailable(a number or a percentage) is set on each group before it upgrades;0keeps the group's own setting.--max-surgedoes not apply to managed node groups, and the upgrade says so.- Nodes that Node Autoscaling provisions follow the new control-plane version and roll on their own, under their NodePool's disruption budget.
- A PodDisruptionBudget that blocks an eviction stops that group's upgrade and says why. Pods are never forced off.
- Changing
amiFamilyreplaces the nodes. - A rollback cannot move the control plane back. It replaces the node groups with new ones at the previous version, creating the new group before draining the old.
astroctl infra k8s upgrade eks-prod <next-version> --max-unavailable 2 --dry-run
astroctl infra k8s rollback eks-prod --list-versions
astroctl infra k8s scale eks-prod platform --min 3 --max 3 --dry-run
<next-version> stands for a version from --show-upgrade-paths.
What the create installs
The EKS control plane, the AWS VPC CNI and CoreDNS, the node groups you reviewed, the cluster's OIDC provider for workload identity, and the AstroPulse agent. Ingress, DNS, certificates, Node Autoscaling, model serving and the other add-ons install separately, from the cluster's Add-ons tab. For direct kubectl access, open the cluster's Access tab or run astroctl infra k8s set-context eks-prod: Access with kubectl.
Other ways in
- Nova: ask it, for example "create an EKS cluster in my connected AWS account with a small system group and an L4 GPU group". Nova shows the plan and creates the cluster after you approve it.
- SDK and API: the same operations, in the API reference.
With astroctl
astroctl cloud aws connect --account-id 123456789012 --region us-west-2 --cluster-name eks-prod
astroctl infra k8s template eks > eks-prod.yaml
astroctl infra k8s apply -f eks-prod.yaml --dry-run
astroctl infra k8s apply -f eks-prod.yaml
connect opens the same pre-filled stack in your browser and waits for it. Use the same cluster name and region in the manifest. --force-update repairs or updates an existing stack. Every flag: astroctl cloud aws connect and astroctl infra k8s apply.
Settings
The fields under spec.provisioner.eks. The settings every cloud shares are on Create a cluster.
accountIdRequiredThe AWS account the cluster is created in.
"123456789012".credentialsRequiredHow AstroPulse reaches the account. Required for a new cluster; applying an existing cluster again without it keeps the stored one.
type: Dynamic, the role the Connect step created.kubernetesVersionThe Kubernetes version.
major.minor or major.minor.patch, one EKS offers in the region.astroctl cloud aws k8s-versionscomputeModeWho provisions worker nodes. Fixed at creation.
ManagedNodeGroupsManaged node groups AstroPulse creates and manages the cluster's node groups.AutoModeEKS Auto Mode EKS creates and manages the worker nodes.
ManagedNodeGroups
autoModeAuto Mode's GPU pool: enableGpuNodePool, gpuLimit (1 to 1000, default 10) and gpuCapacityTypes (OnDemand, Spot). Only with computeMode: AutoMode.
amiFamilyThe operating system image for node groups. Changing it replaces the nodes.
AmazonLinux2023Amazon Linux 2023 The current Amazon Linux release.BottlerocketBottlerocket A minimal operating system from AWS built for running containers.Ubuntu2004Ubuntu 20.04 Ubuntu 20.04 LTS. Standard support has ended.Ubuntu2204Ubuntu 22.04 Ubuntu 22.04 LTS.Ubuntu2404Ubuntu 24.04 Ubuntu 24.04 LTS.Ubuntu2604Ubuntu 26.04 Ubuntu 26.04 LTS.UbuntuPro2004Ubuntu Pro 20.04 Ubuntu Pro 20.04, with extended security maintenance from Canonical.UbuntuPro2204Ubuntu Pro 22.04 Ubuntu Pro 22.04, with extended security maintenance from Canonical.UbuntuPro2404Ubuntu Pro 24.04 Ubuntu Pro 24.04, with extended security maintenance from Canonical.UbuntuPro2604Ubuntu Pro 26.04 Ubuntu Pro 26.04, with extended security maintenance from Canonical.
AmazonLinux2023
tagsAWS tags on the cluster's node groups.
_ . : / = + - @. Keys may not start with aws:, platform.astropulse.io/ or karpenter.sh/, among other reserved prefixes.vpcIdAn existing VPC to create the cluster in. Left out, a new VPC is created.
vpc- followed by 8 or 17 hexadecimal characters.vpcCIDRThe VPC's IPv4 range. Required with vpcId, where it must equal the VPC's own; optional without, where it sets the new VPC's range.
subnetsWith vpcId: each zone the cluster runs in, mapped to one Public and one Private subnet, {type, id}.
ecrAccountIdsOther AWS accounts whose ECR the nodes pull from.
If it's refused
aws sts get-caller-identity.astroctl cloud aws connect with --force-update.clusterSpec.dataPlane, or use computeMode: ManagedNodeGroups.AutoMode is set on a cluster with managed node groups.AutoMode, or set computeMode: AutoMode.minNode: 0.vpcCIDR is larger than a /16 or smaller than a /24./16 to /24, for example 10.0.0.0/16.vpcCIDR to the VPC's CIDR.subnets lists zones other than the cluster's; the message lists both.subnets has two of one type, or one is missing.