Kubernetes Clusters

A Kubernetes cluster is a Webscale cluster that deploys a Helm chart to an Amazon Elastic Kubernetes Service (EKS) cluster. Every deployment installs your chart as a Helm release in its own namespace. Webscale verifies that its proxies can reach the release, then routes traffic to it. Because the previous release keeps running until the destroy delay expires, a rollback is immediate. Your chart controls replica counts and pod autoscaling.

Prerequisites

• EKS cluster: The EKS stack creates and manages one in your AWS account, including the security group rule for the Webscale proxies. An EKS cluster you built yourself must let the proxies reach the NodePort range 30000-32767. Private nodes must be in the data plane’s VPC or in a network joined to it, and the security group opens the range. The provider’s IAM user must have cluster admin access through an EKS access entry. The EKS stack grants one to the Webscale IAM user and to each ARN in kubernetes_admins . The Webscale Control Plane must reach the EKS cluster’s public API endpoint, which the EKS stack configures for you.
• AWS provider: Check Use for Kubernetes on the provider and enter the EKS cluster name in Cluster Name. The provider’s region must be the region of the EKS cluster. Saving the provider creates the Kubernetes service that Kubernetes clusters deploy through. See Working with Providers .
• Managed deployments: Kubernetes clusters are always managed. See Managed Deployments .
• Chart file: Package the chart directory as a .zip, .tar, or .tar.gz with Chart.yaml and the templates directory at the root of the archive. Upload it on the Files page with the Helm chart file type (helm-chart in the API). See Working with Files .

Chart requirements

Webscale installs the chart with Helm and reads one Service from it. The chart has to meet these rules.

• NodePort Service: One Service receives the traffic. Name it in the blueprint. It needs a selector and exactly one port. Do not set nodePort. Two releases run side by side, and a fixed port collides. The proxies connect to the nodes on that node port directly, without a load balancer. Both externalTrafficPolicy values work, but leave it at Cluster, the default. Webscale refreshes the node list once a minute, and between refreshes a node that lost its pod still forwards traffic under Cluster but refuses it under Local.
• Namespace: Do not set one in the chart. Each deployment installs into a new namespace whose name is the deployment’s ID. The namespace starts empty, and Webscale deletes it with the deployment. Pull secrets, quotas, and network policies come from the chart. Webscale passes the values webscale_cluster_id, webscale_deployment_id, and webscale_namespace to the chart, and they override values of the same name.
• Cluster-scoped resources: Two releases run side by side during a deployment and the destroy delay. The chart cannot carry CRDs, ClusterRoles, or webhooks that two copies would share. Plan node capacity for two copies.
• PodDisruptionBudget: Karpenter on the EKS stack evicts pods when it removes a node. A budget on the serving pods keeps enough of them running.
• Secrets: Declare an ExternalSecret against the aws-secretsmanager store the EKS stack installs. See Secrets on the EKS stack page.

Create a Kubernetes cluster

To create a Kubernetes cluster, click the Clusters tab and then click Add cluster. Choose the Kubernetes service of your provider in the Service field. The editor then shows these properties.

Once you have specified the properties of your Kubernetes cluster, click Save. With a minimum size above 0, the first deployment starts at once. A Kubernetes cluster created with a minimum size of 0 deploys at the next change to its blueprint. You can monitor progress in the Task monitor or on the Clusters page.

Defining the Helm blueprint

A Kubernetes cluster has one blueprint, and it describes the Helm release.

The release does not use the metadata and files of a Helm blueprint. Pass configuration through the chart values.

In the API, the blueprint looks like this:

{
  "server_blueprints": [
    {
      "name": "helm",
      "service": "/v2/services/abc123",
      "helm_chart_reference": "/v2/files/xyz789",
      "helm_chart_values": "<base64 encoded YAML>",
      "helm_release_name": "my-release",
      "helm_service_name": "my-service"
    }
  ]
}

A helm_chart_reference names the file, and each install uses the current version of that file. To deploy a new chart, upload it as a new version of the file and make that version current. Then change the blueprint, for example its values, to start a deployment. See Automated Deployments for an example.

Deployment steps

A deployment starts when you save a change to the blueprint, such as new values or a different chart file, or to the Kubernetes cluster’s hostnames. It also starts when you raise the maximum size from 0. Changes to the destroy delay or the retained configuration count do not deploy.

1. Install: Webscale runs helm upgrade --install --wait --create-namespace in the namespace of the deployment. The output of Helm appears in the task log as it arrives.
2. Verify: Webscale checks that the named Service is a NodePort Service with one port and a selector. It registers the nodes that serve the Service and tests the connection from every proxy of the applications that use the Kubernetes cluster. A Kubernetes cluster without an application skips the test.
3. Activate: Traffic moves to the new release. Webscale keeps the previous deployment for the destroy delay, and Rollback reactivates it without a Helm run.
4. Destroy: After the destroy delay, or on a failure or a cancel, Webscale uninstalls the release and deletes its namespace. A failed deployment never touches the release that serves traffic.

Every minute, Webscale re-reads the nodes that serve the Service and sends the proxies the new addresses when they change.

Troubleshooting

The task log names the cause of a failed deployment. These are the common messages.

Further reading

• Creating Clusters
• VM Clusters
• Managed Deployments
• EKS stack
• Working with Providers
• Working with Files

Last modified on September 11, 2026