How to deploy a cluster

Instructions for deploying a client cluster in the GUI for Shturval v2, VMware vSphere, oVirt, OpenStack, Yandex Cloud, vCloud Director and Basis Dynamix.

Once the working management cluster is available in the platform and the infrastructure provider instance is configured, you are ready to create a client cluster in the platform GUI. Below is a checklist of preconditions, then where to start creating, details for each provider (tabs), general steps of the wizard for the certificate and services, status tracking and links to reference materials.

Preconditions (check before starting)

Before clicking Create Cluster or Add Cluster make sure:

Management cluster in Ready status — Where to look: Clusters → list of clusters.
IP address pool created, if you need it for your scenario (facilitates deployment with internal balancers and infrastructure providers VMware vSphere, oVirt and the like, Shturval v2) - Where to look: Providers → IP pools.
In the pool used minimum 2 free addresses, if you issue a VIP from the pool - Where to look: pool page, “Status” column.
Provider instance created - Where to look: Providers → Provider configuration.
Provider connection check passed - Where to look: green check mark on the instance.
For providers with VM templates/images: template added for the required version of Kubernetes - Where to look: provider instance card.
IP pool tied to the provider instance, if you use a pool - Where to look: editing an instance, the “IP Pool” field.
Checking the intersection of subnets when creating a cluster: subnets of pods/services and VIP are consistent with the infrastructure - Where to look: step of the “Basic data” wizard.

Note: For OpenStack, Yandex Cloud, vCloud Director, Basis Dynamix IP pools are not used - addresses are set differently (often through external balancers). See the corresponding provider tab.

If something is not completed, go to How to work with providers in the platform. General requirements for nodes and network are on the Requirements page.

Briefly about providers

Provider	When to choose	Preparing nodes
Shturval v2	Naked hosts, SSH	Hosts and OS, without VM template
VMware vSphere	vCenter	VM template (stc), upload to vSphere
oVirt and analogues	zVirt, oVirt, HostVM, ED Virtualization, ROSA Virtualization	VM Template, DHCP in VNIC Profile
OpenStack and similar	VK Cloud, Selectel, etc.	Images, VPC, security groups
Yandex Cloud	Yandex Cloud	Image with `--keep-cloud-init`, VPC
vCloud Director	vCloud Organization	Catalogs, templates, DHCP on the network
Basis Dynamix	Basis Dynamix Environment	Templates/images, customizing LB after creation

Recommendation for the first time: VMware vSphere or Shturval v2.

Where to create a cluster in the platform

Open the Cluster section and click Add a cluster.
Select the provider type and specify Cluster Name (see the screenshot below).
Go through the steps of the wizard: basic data (instance, network and entry points according to the provider’s script, template or image if necessary), nodes Control Plane and Worker, certificate, select services, check data → Create (see the screenshot below).

By default, a required field is filled in automatically when only one allowed option is available. If there are several options, select the appropriate one yourself.

Illustration: Where to create a cluster in the platform

Field	Purpose
Cluster name	Unique identifier. Limited to 37 characters: The cluster name is used when generating labels for related objects that are limited in length (63 characters)

Detailed wizard fields and environment features are on the tabs in the “Deployment by Provider” section.

Deleting PVs when deleting a cluster

For oVirt (and compatible platforms), VMware vSphere, OpenStack / VK Cloud / Selectel, vCloud Director, and Yandex Cloud, the Basic data step offers Delete PVs when deleting a cluster with CSI integration enabled if CSI integration is allowed on the provider instance.

With CSI integration enabled, volumes live in the provider’s external storage, not on node disks. You can delete the cluster and the VMs — CSI disks still remain and keep occupying infrastructure. The choice controls whether those disks are cleaned up with the cluster.

Screenshot: PV deletion field on the Basic data step

Value	What happens when the cluster is deleted
No (default)	PVs in the cluster are not cleaned up. Disks on the virtualization or cloud side remain.
Yes	Before the cluster is deleted, PVs in the cluster are deleted.

The choice made when creating a cluster takes priority over the policy in the cluster profile. If the parameter is not passed in the GUI or shtil, the profile value is used. If it is set in neither the request nor the profile, PVs are not deleted.

The resulting cluster setting is in the ClusterConfig resource (API group cluster.shturval.tech) in the management cluster. The object name and namespace match the cluster name. The field is spec.deletePersistentVolumes: true — PVs are deleted before the cluster is deleted, false or the field is omitted — they are not. Resource description: Custom platform resources.

Where to look:

in the GUI: management cluster → Administration → Custom Resources → API group cluster.shturval.tech → ClusterConfig → cluster name;
in the CLI:

kubectl -n <cluster-name> get clusterconfig <cluster-name> -o yaml

Selecting a VM template

For all providers except Shturval v2, the Basic data step can show a VM template field after you select the platform version.

The field appears only if the selected instance has several VM templates with the same Kubernetes version for that platform version. If there is one template, the field is hidden and the platform selects it.

If the field is on the screen, it is required. The selected template is applied to all cluster nodes (Control Plane and Worker). The Data verification step shows the selected VM template name.

During a cluster upgrade, if the instance has several VM templates for the target Kubernetes version, the platform selects the first one in alphabetical order and applies it to all node groups. To make sure the intended template is used on upgrade, add one template of the next version. If there are several templates, the first one in alphabetical order is selected.

Deployment by provider

Below are the prerequisites, GUI flow, wizard fields (steps 1-4 or equivalent), environment specifics, and API call for each provider. General steps installing a certificate and selecting services are listed after the tabs.

After filling out the provider fields in the wizard, go to the sections “Installing a certificate” and “Selecting services”, then complete data verification and cluster creation.

Shturval v2

Prerequisites

Configured provider instance Shturval v2 with added hosts;
Pool of IP addresses with free addresses for KubeAPI and Ingress (optional, simplifies the selection of VIP addresses when using internal balancers for Kube-API/Ingress);
Hosts with OS from supported list, SSH access.

Advantage: No VM template is needed - the platform deploys Kubernetes directly on selected hosts. For more information about the model without VM templates and Cluster API, see Creating nodes when deploying a client cluster.

Process in GUI

Going to the wizard and selecting a provider with an instance is described at the beginning of the page. Next in the wizard for Shturval v2:

Fill in basic details (basic or advanced mode): instance, platform version, network entry points (see table), external balancers, subnets and cluster profile if necessary.
Configure Control Plane and Worker groups: host selection, scaling, selectors in advanced mode.
Go through certificate installation, select services, data verification and create a cluster.

Step 1: Basic data

At the “Basic data” step, the fields are available in basic mode and in advanced settings mode (the “Show advanced settings” toggle switch). When switching from advanced to basic mode, values in hidden fields are lost.

Basic mode - minimum set: VIP for management access to the cluster and VIP Ingress, if necessary, selecting addresses from the instance pool. Advanced information security parameters, external balancers and explicit CIDR of pods/services are not set in this mode (platform default values are used).

Screenshot: basic data in basic mode

In the basic mode the following are specified:

Field	Purpose
Instance	Instance Shturval v2; if there is one, it is selected automatically.
Platform Version	Version of the Shturval platform from which the cluster will be installed
Version Kubernetes	Version of Kubernetes in accordance with the selected platform version
cluster API server address	IP or FQDN for KubeAPI; you can enter it manually or select a free IP from the pool associated with the instance. Copying of value is available.
VIP address for Ingress	IPv4 in internal subnet and nodes or from a pool; will be configured on one of the Workers for the system Ingress. Copying available.

If an instance has an IP pool defined, the drop-down lists only show free addresses in the pool. If one address is free, it can be specified either for the API or for Ingress; otherwise, set the addresses manually or expand the pool.

Advanced mode adds external balancing, subnets and profile fields.

Screenshot: extended master data

Field	Purpose
API server address	Same as in basic mode; when using an external LB for the API, specify the FQDN to which the balancer is configured (see below).
VIP address for Ingress and DNS record for Ingress	IPv4 and/or Wildcard FQDN for Ingress. If you are using an internal balancer for Ingress, both fields are available. The Ingress DNS record is limited to 53 characters to ensure that the resulting `commonName` for cert-manager does not exceed the allowed length.
Use external balancer for Ingress	When enabled, haproxy is used; with an internal scheme, balancing on the API may not be applied; the traffic goes to the VIP. With an external LB, the Ingress DNS record (Wildcard FQDN) field remains for Ingress.
Use an external balancer for the API server	Disabled by default. If enabled, in the API server address field, specify the FQDN of the external balancer. The balancer must be configured before the start of cluster deployment.

Screenshot: external balancer for API

Screenshot: external balancer for Ingress

Field	Purpose
Set advanced information security settings	Secret Encryption for etcd, TLS connection to Kubelet and pre-configured audit policy.
PodSubnet	CIDR for Pod; should not intersect with the network of nodes and services. Typical range: `172.16.0.0/16`.
Service Subnet	CIDR for `ClusterIP`; does not intersect with nodes and Pods. `10.96.0.0/12` is recommended.
Cluster Profile	See Cluster Profiles; by default - default profile.

Before saving, check the ranges for intersections; see FQDN and VIP and checking the intersection of subnets when creating a cluster.

Note: There is no reservation IP mechanism: the address could be free when filling out the form and occupied by the time of deployment - a cluster will not be created. Allocate non-overlapping subnets and pools for different clusters.

FQDN in the cluster depend on Ingress:

for DNS record Ingress: *.<ingress-dns-record>;
for VIP Ingress: *.<CLUSTER_NAME>.ip-<VIP-Ingress>.shturval.link.

Step 2–3: Node Configuration

Unlike providers with VM templates, nodes are instance hosts (roles and labels are set when adding hosts or in the provider).

Control Plane — an odd number of nodes, no more than 5. The Potentially available hosts block shows hosts with the role controlplane (or according to the selector). If there are no hosts, add them to the provider instance.

Screenshot: Control Plane, basic mode

In advanced settings a host selector (labels, expressions) is available; by default the role label controlplane is added.

Screenshot: Control Plane, selector

Worker groups - by default, two protected groups of three nodes: default and infra. They can be created without adding hosts (number 0), then MachineDeployments will remain for subsequent scaling. You can add custom groups, copy settings between groups, and duplicate configuration.

Screenshot: Worker groups

For each group: manual or automatic scaling (the minimum number of nodes in the GUI is usually not lower than 2), in the basic mode - host role (workers, infra, etc.; the controlplane role is not available for Worker). In advanced mode - host selector with default labels for the group.

Screenshot: Worker group parameters, basic mode

Screenshot: Worker selector

Note: Selector rule: labels specified as a match in one group should be excluded in other groups using NotIn (samekey and value) to prevent the host from being in two groups at the same time.

If at the start of creation there are not enough hosts with the required roles/labels, some nodes may not join: add hosts in the provider and check the labels on the node page (Labels and annotations / Cluster API).

Recommended host resources: client cluster requirements.

Next is the general step “Installing a certificate” and “Selecting services”.

Features Shturval v2

No template: The platform installs Kubernetes on bare metal hosts with a pre-installed OS.
Hosts: Added to the provider instance. SSH access by key is required. A sudo password, if needed, is set in the host credentials — see How to add a password for sudo commands. When creating the management cluster, set the same password in the installation wizard or from the console — see SSH user password for sudo. The hosts must be on the same subnet.
Resources: CPU, RAM, disk are set on the hosts. The platform does not create VMs - it uses existing ones.
Recommended for: First cluster, test benches, bare metal.