EKS

The EKS stack creates and manages an Amazon Elastic Kubernetes Service (EKS) cluster in your AWS account. Webscale deploys Helm charts to the EKS cluster through the Control Plane, and your own tools reach it with kubectl and Helm.

An EKS stack consists of:

• An EKS cluster with a public and a private API endpoint
• A fixed-size node group of Arm nodes
• The vpc-cni, kube-proxy, coredns, and metrics-server add-ons
• External Secrets Operator with a ClusterSecretStore for AWS Secrets Manager (enabled by default)
• Karpenter node autoscaling (enabled by default)
• Supporting infrastructure (subnets and their route tables, a NAT gateway, IAM roles, and the security group rule, plus a VPC in the new VPC mode)

Network topology

The stack can be deployed in three modes:

• Data plane VPC (private nodes): Set data_plane_vpc to the VPC ID of your dedicated data plane and network_cidr to a free block of that VPC. The stack creates its subnets there, and the proxies reach the nodes over the VPC’s own routing. The nodes reach the internet through one NAT gateway, whose address the nat_ip output reports for allowlisting. The VPC must be in the same AWS account and region, with an internet gateway attached and DNS support and DNS hostnames enabled.
• New VPC (public nodes): Set public_nodes and data_plane_cidr, which is 0.0.0.0/0 because the proxies reach public nodes from their public addresses. The stack creates a new VPC from network_cidr and gives each node a public address. It creates no NAT gateway, each node uses its own address, and nat_ip is null.
• Existing network: Uses the subnets you list in node_subnets. The stack creates no network. The subnets must already have a route to the internet, or the nodes cannot pull images. Set data_plane_cidr to the network of the proxies, or the stack opens no port and deployments fail their reachability test. Connect the two networks yourself when the subnets are in another VPC.

The mode cannot change for the life of the EKS cluster, which cannot move between VPCs. A different mode needs a new stack.

Data plane

A data plane is a set of Webscale proxies that receive the traffic for your applications, and a dedicated data plane serves your account alone. Its proxies send traffic directly to the EKS cluster’s nodes on the node port of the release’s Service. Because the port can change with every deployment, the stack opens the whole NodePort range (30000-32767) to the network of the proxies. In a created network, private nodes need data_plane_vpc and public nodes need data_plane_cidr.

Variables

Example:

{
  "type": "eks",
  "environment": "/v2/environments/tu8aovkn7waj",
  "service": "/v2/services/2tpkjj7e0b28",
  "name": "production-eks",
  "variables": {
    "region": "us-east-1",
    "network_cidr": "10.0.16.0/20",
    "data_plane_vpc": "vpc-0123456789abcdef0",
    "kubernetes_admins": ["arn:aws:iam::123456789012:role/PlatformAdmin"]
  }
}

Outputs

Cluster access

The stack grants cluster admin through EKS access entries to the Webscale IAM user and to each ARN in kubernetes_admins. Webscale creates that user in your account during onboarding. Use kubernetes_admins for your own roles and users, and for a provider whose access key belongs to another user. The Webscale user and the stack’s own IAM roles already have entries, and listing one of them fails the stack update.

To deploy through Webscale, enable Use for Kubernetes on the AWS provider and enter the kubernetes_cluster_name output in Cluster Name. Then create a Kubernetes cluster with a Helm blueprint. See Working with Providers for the provider settings.

Secrets

When enable_external_secrets is true, the stack installs External Secrets Operator in the external-secrets namespace and a ClusterSecretStore named aws-secretsmanager for AWS Secrets Manager. The operator reads each value directly from Secrets Manager, so no value passes through Webscale. It can read only secrets whose names start with webscale/. Your chart declares an ExternalSecret that names the secret, and the operator writes a Kubernetes Secret in the namespace of the deployment.

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: example
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: aws-secretsmanager
  target:
    name: secret-to-be-created
  dataFrom:
    - extract:
        key: webscale/acme-api/prod

Reference the Secret in the container spec of your Deployment with envFrom:

envFrom:
  - secretRef:
      name: secret-to-be-created

Containers read environment variables at start. A rotated value reaches the application on the next deployment.

Node autoscaling

When enable_karpenter is true, Karpenter adds temporary nodes when pods do not fit on the existing nodes and removes them as demand falls. It launches on-demand Arm instances from the c, m, and r families, generation 3 or newer, size large or larger. They share the disk size, node role, and security group of the base nodes. karpenter_cpu_limit caps the total, and karpenter_node_lifetime sets when Karpenter replaces a node.

Karpenter evicts pods when it removes a node and honors a PodDisruptionBudget for up to 20 minutes, then deletes the remaining pods. Add a budget that selects each Deployment’s pods.

Deleting the stack

Delete the Kubernetes clusters that deploy to the EKS cluster before you delete the stack, and wait for Karpenter to remove its temporary nodes. Karpenter launches and terminates those instances itself, so the stack cannot delete them. If temporary nodes are still running, the delete waits for Karpenter to drain them, which can take up to 20 minutes. The stack releases the NAT address when you delete it, and a replacement stack gets a different one. The stack removes only the network pieces it created.

Last modified on September 2, 2026