Kubernetes Clusters

Create Kubernetes targeted Webscale clusters

A Kubernetes targeted cluster is a container based cluster that scales horizontally in response to increasing or decreasing traffic. The clusters are composed of Pods managed by a Kubernetes Horizontal Pod Autoscaler and routable through a Service in the Kubernetes cluster. Users can specify scaling conditions, an init job, init container, and other container specific parameters when setting up their cluster through the Webscale Control Panel.

Prerequisites

The Kubernetes cluster itself is not created through the Webscale Control Panel. It must be created independently and prior to enabling Kubernetes in your provider. Additionally, the cluster must have the following:

  • A metrics server must be installed. See Installing the Kubernetes Metrics Server for details steps on deploying.
  • The provider user must have access to the EKS cluster.
  • The Kubernetes cluster nodes must have the port range 30000-32767 open to the internet.

To grant EKS access to the provider user you will have to create a ClusterRole with the required permissions and create an EKS IAM identity mapping from the provider user to the Group created in the ClusterRoleBinding. Follow these steps to grant the Webscale provider access to the Kubernetes cluster:

  1. Create the ClusterRole and the ClusterRoleBinding. First, save the following contents to a file named ws-admin.yml.
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ws-admin
rules:
- apiGroups:
  - '*'
  resources:
  - "serviceaccounts"
  - "namespaces"
  - "nodes"
  - "rolebindings"
  - "roles"
  - "secrets"
  verbs:
  - "create"
  - "delete"
  - "get"
  - "update"
  - "patch"
  - "list"
  - "escalate"
  - "bind"
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ws-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: ws-admin
subjects:
- kind: Group
  name: ws-admin
  apiGroup: rbac.authorization.k8s.io
  1. Apply the following resources to the Kubernetes cluster. Authenticate to the cluster and run:
kubectl apply -f ./ws-admin.yml
  1. Create the IAM identity mapping with the new group created:
eksctl create iamidentitymapping \
    --cluster <eks-cluster-name> \
    --region <eks-region> \
    --arn <provider-arn> \
    --group ws-admin \
    --username webscale-provider

For example:

eksctl create iamidentitymapping \
    --cluster my-eks-cluster \
    --region us-east-1 \
    --arn arn:aws:iam::111111111111:user/provider-user \
    --group ws-admin \
    --username webscale-provider

To target a Kubernetes cluster you will need to enable Kubernetes for the provider. This is configured in the Providers tab. Select the “Use for Kubernetes” checkbox when creating or editing your provider and then enter the name of the preexisting Kubernetes cluster. This will result in a Kubernetes service being created for that provider.

You must also have a Docker registry service enabled either through the Docker Registry provider or with the “Use for ECR” checkbox in an AWS provider. This is configured in the Providers tab. See documentation on Working with Providers for more information.

Managed deployments must be enabled in your account in order to create Kubernetes targeted clusters. See documentation on Managed Deployments for more information.

Creating a Kubernetes targeted cluster

To create a cluster, click the Clusters tab and then click Add cluster. If you have enabled Kubernetes for at least one of your Providers, you will now be prompted to select a cluster type. For Kubernetes targeted clusters, select “kubernetes”.

This will then display the cluster editor:

Add Kubernetes Cluster Dialogue

Here you will define the properties of your Webscale cluster:

Property Description
Name Name of the Webscale cluster.
Min size Minimum number of pods.
Max size Maximum number of pods.
Manual size A specified number of pods (overrides minimum and maximum).
Verify timeout The amount of time to attempt to verify the cluster before marking the configuration as failed.
Manage deployments See Managed Deployments. Required for Kubernetes targeted clusters.
Destroy delay The amount of time to keep previous cluster resources running after a new cluster has been successfully deployed.
Retained configuration count The number of previous cluster configurations to store. Clusters in “Failed” or “Retained” states are included in this count.
Blueprint Kubernetes instance blueprint definition. See below.
Scale out when Predefined conditions that determine when the cluster should scale out.

Once you have specified the properties of your cluster, click Save. If you have specified a minimum size greater than zero, a Kubernetes instance will begin to be created. Progress can be monitored in the Task monitor or the Clusters page.

Defining a Kubernetes blueprint

Your Kubernetes cluster blueprint specifies configuration details for the Kubernetes Replica Set, Horizontal Pod Autoscaler (HPA), and Service. You may only provide a single blueprint for Kubernetes clusters.

Kubernetes Blueprint Editor

Main blueprint

Property Description
Service Webscale service used to create the cluster resources. Required.
Application The Webscale application the cluster will target. Only required if a Stratus service is being used.
Docker registry service The Docker registry service to be used to specify the container image. Required.
Docker image repo The Docker image repository where the container image is stored. Repositories are configured in the Providers tab either in the Docker Registry Provider or AWS Provider. Required.
Docker image tag The Docker image tag to be used in the Kubernetes instance. This image must be a functioning webserver that can accept HTTP/S traffic on a given port. Required.
Container port The container port to expose. Required.
Target cpu usage The required CPU usage for a single instance of your container.
Accepted units: millicores (m) or cores. Ex: “1000m” or “1”
Target memory usage The required memory for a single instance of your container.
Accepted units: K, Ki, M, Mi, G, Gi, T, Ti, P, Pi, E, or Ei. Ex: “2000M” or “2Gi”

Init Container

The Init Container section of a Kubernetes blueprint defines the container image and command to be run as a Kubernetes Init Container. Init Containers run before a Pod is started on every Pod creation (including scale out events). This entire section is optional and the required fields shown below are only required if you are specifying an Init Container. See the Kubernetes Init Containers documentation for more information about how Init Containers work.

Property Description
Init container docker registry service The Docker registry service used to specify the Init Container image. Required.
Init container docker image repo The Docker image repository where the Init Container image is stored. Required.
Init container docker image tag The Docker image tag to be used for the Init Container. This image must contain an executable script that will run the Init Container logic. Required.
Init container command The absolute path to the executable script within the container image. This command will be run when the Init Container starts up and must exit successfully in order for the main container to start. Required.

Init Job

The Init Job section of a Kubernetes blueprint defines the container image and command to be run as a Kubernetes Job before the Init Container and main container start. The Init Job is only executed once on a new Webscale cluster deployment and will not be executed as new Pods scale out. This entire section is optional and the required fields shown below are only required if you are specifying an Init Job. See the Kubernetes Jobs documentation for more information about how Jobs work.

Property Description
Init job docker registry service The Docker registry service used to specify the Init Job image. Required.
Init job docker image repo The Docker image repository where the Init Job image is stored. Required.
Init job docker image tag The Docker image tag to be used for the Init Job. This image must contain an executable script that will run the Init Job logic. Required.
Init job command The absolute path to the executable script within the container image. This command will be run when the Init Job starts up and must exit successfully in order for the main container or Init Container (if specified) to start. Required.
Init job timeout The time in seconds to wait for the Init Job success. Once this timeout has been exceeded the Webscale cluster will fail verification and newly created resources will be destroyed. Required.

Volume Mounts

You have the option to specify volume mounts when using a Stratus service. When creating a volume mount you specify a source and target path. These paths must both be absolute paths where the source path is the absolute path from within the volume. In the Stratus service case, the volume is the Stratus environment’s webroot volume. The target is the absolute path within the container where the directory or file specified in the source path should be mounted.

Common use cases for Volume Mounts include mounting media contents and var directories into the container.

Metadata

You have the option to specify key/value pairs that are made available in the container(s) environment created using that blueprint.

Files

You have the option to specify Webscale files that are made available in the container(s) created using that blueprint. The combination of these files can not exceed 1MB due to Kubernetes object restrictions. If the combination of these files exceeds 1MB, the cluster will fail verification.

Files must be uploaded to your Webscale account prior to blueprint creation via the Files tab. See Working with Files for more information on uploading Webscale files.

Further reading

Have questions not answered here? Please Contact Support to get more help.


Last modified February 27, 2023