Deployment of a Kubernetes Cluster via Terraform

This guide demonstrates the automated deployment of a Kubernetes cluster in the Peerobyte cloud using our prepared Terraform configuration. This configuration:

• creates a virtual network and router;
• configures a security group with the required ports;
• deploys and configures control (master) and worker nodes according to the profile you choose;
• (optionally) installs the Kubernetes Dashboard.

Prerequisites

1. Peerobyte account
   You must have a registered account in the Peerobyte control panel. For detailed registration instructions, see “Creating an Account”.
   
2. “Cloud Infrastructure” service ready
   The Peerobyte “Cloud Infrastructure” service must be ordered and ready. You will receive an email notification and an in-panel notice when it’s ready. For ordering instructions, see “How to Order Cloud Infrastructure”.
   
3. Sufficient project quotas
   Ensure your project has enough free quota. You can view available resources in Horizon under Home → Quota Overview. If insufficient, contact Peerobyte support.
   
4. Terraform installed
   On the machine from which you’ll manage deployment, install Terraform version 1.0 or later. See “Installing Terraform”.
   
5. Key pair in the project
   You must have a key pair in your OpenStack project, with the private key available locally. To add a key pair via Horizon, see “Quick Start in Cloud Infrastructure: I. Adding a Key Pair”.
   
6. Free subnet 172.16.254.0/24
   Your project must have the 172.16.254.0/24 subnet free. If it’s in use, you have two options:
   • In main.tf, replace all occurrences of the prefix 172.16.254. with another free subnet prefix (e.g. 172.16.253.). See main.tf below for details.
   • Create a separate project for the new cluster with a free subnet.

What does the deployment code include?

We’ve placed everything needed for an automated, full-fledged Kubernetes cluster deployment in a GitHub repo. This includes Terraform configurations (HCL) and Cloud-Init templates that let you define all key cluster parameters—from Kubernetes/CRI-O versions and sizes to VM and disk types.

In this section we’ll cover: configurable parameters; infrastructure components that will be deployed; cluster-opened ports; output data during cluster creation; deployment configuration elements.

Configurable parameters

You can adjust the following cluster parameters by editing rraform.tfvars:

• Cluster size – the profile (cluster_profile) automatically defines the number of control (master) and worker nodes and their disk sizes.

Profile	Masters	Workers	Disk size (GB)
small	1	2	20
medium	2	3	30
large	3	6	50

• Component versions — Kubernetes (kubernetes_version) and CRI-O (crio_version).
• Web UI — enable or disable Kubernetes Dashboard (enable_dashboard).
• Instance types (flavors) — flavors for masters (master_flavor) and workers (worker_flavor), defining vCPU and RAM.
• Disk type — storage type (volume_type): All-Flash or Hybrid.
• SSH access — key pair (keypair) for managing VMs.
• OS image — VM image (image_name) and default user (default_os_user).
• External network — external network ID (external_network_id) for router attachment and external IP (optional).

Created components

When applying the Terraform configuration, the following resources are created automatically:

• Network — virtual network, subnet, and router.
• Security group — firewall rules for cluster access.
• VMs — master and worker nodes.

Open ports

By default, the security group (k8s-secgroup) allows:

• 22/TCP — SSH access;
• 6443/TCP — Kubernetes API-server;
• 30000–32767/TCP — NodePort services;
• ICMP — ping.

Within the cluster subnet:

• All TCP and UDP — inter-component communication;
• 2379–2380/TCP — etcd;
• 53/UDP, 53/TCP — DNS;
• 10250/TCP — Kubelet API;
• 10259/TCP — kube-scheduler;
• 10257/TCP — kube-controller-manager;
• 10256/TCP — kube-proxy (health/metrics);
• 4443/TCP — metrics-server;
• 65414/UDP — Flannel VXLAN.

Note: The detailed rules are shown for clarity and potential tightening, although “all TCP/UDP inside subnet” already covers them.

Output data

After successful deployment, Terraform prints:

• IP addresses of master nodes;
• IP addresses of worker nodes.

Deployment configuration elements

• terraform.tfvars — user-set cluster parameters (edit for custom settings).

• README.md — project description: capabilities, requirements, structure, profiles, and a brief step-by-step.
• main.tf — authenticates to OpenStack, creates network, subnet, router, security group; deploys masters and workers with static IPs; configures VMs and runs Cloud-Init templates.
• outputs.tf — defines output parameters, e.g. node IPs.
• variables.tf — all input variables: auth, network & compute settings, cluster profile, storage and version settings.
• Cloud-Init templates — user-data files for VM bootstrap:
  • master-main.sh.tpl — initial setup of the first master: install CRI-O & Kubernetes, configure sysctl & disable swap, kubeadm init, deploy Flannel CNI, copy admin.conf.
  • master-default.sh.tpl — additional masters: same stack, enable IP forwarding & sysctls, kubeadm join to control-plane.
  • worker.sh.tpl — worker preparation & join: install CRI-O & Kubernetes, set sysctls, kubeadm join.

I. Cluster Deployment Procedure

1. Download the project
   Clone the GitHub repo into a folder on the machine from which you’ll manage the cluster via Terraform. If Terraform isn’t installed yet, install it per “Installing Terraform”.
   
2. Obtain authentication parameters
   Get auth parameters for Terraform as described in “Authentication in Cloud Infrastructure via Terraform”.
   
3. Open terraform.tfvars
   Edit terraform.tfvars in a plain-text UTF-8 editor (e.g. VS Code, Notepad++, Vim, Nano). Avoid rich-text editors like Word.
   
4. Enter authentication data
   Enter the authentication data obtained in step 2 into the opened terraform.tfvars:
   

    
       
    ##########################################
   # OpenStack authentication (IaaS access)
   # Authorize access to your OpenStack project
   ##########################################
   auth_url    = "<OS_AUTH_URL>"
   tenant_name = "<OS_PROJECT_NAME>"
   user        = "<OS_USERNAME>"
   password    = "<PASSWORD>"
   domain      = "<OS_USER_DOMAIN_NAME>"
   ... 

   
   Take , <OS_PROJECT_NAME>, <OS_USERNAME>, <OS_USER_DOMAIN_NAME> from your OpenRC file.
   
   If <OS_AUTH_URL> contains /v3//v3/, leave only one /v3/.
   
   Get <PASSWORD> from the “Cloud Infrastructure” panel (use Click to copy or reveal with ******).
   
   Example:
   

    
       
    ##########################################
   # OpenStack authentication (IaaS access)
   # Authorize access to your OpenStack project
   ##########################################
   auth_url    = "https://cli.peerobyte.com:5000/v3/"
   tenant_name = "my-project-31-715-715"
   user        = "ruofcmvh"
   password    = "8bw12nZuK9"
   domain      = "my-domain-31-715-715-1746522363"
   ... 

   
   Security note: Storing passwords in Terraform code is insecure. Instead, export as an environment variable: 
   

    
       
    export TF_VAR_password=<your_password> 

   
   Then comment out the password line in terraform.tfvars:
   

    
       
    #password = "<PASSWORD>" 

5. Select cluster profile
   In terraform.tfvars, specify the cluster profile:
   

    
       
    ...
   ##########################################
   # Cluster profile# Defines the size of the cluster: number of master and worker nodes
   # and the disk volume size for each node.
   # Values are set via local.profiles in main.tf
   # Available profiles: small, medium, large
   ##########################################
   cluster_profile = "<cluster_profile>"
   ... 

   
   Choose based on required masters, workers, and disk size:
   

   <cluster_profile>	Masters	Workers	Disk (GB)
   small	1	2	20
   medium	2	3	30
   large	3	6	50

   
   Example:

    
       
    ...
   ##########################################
   # Cluster profile# Defines the size of the cluster: number of master and worker nodes
   # and the disk volume size for each node.
   # Values are set via local.profiles in main.tf
   # Available profiles: small, medium, large
   ##########################################
   cluster_profile = "medium"
   ... 

6. Choose component versions
   In terraform.tfvars, specify the versions of Kubernetes and CRI-O:

To list available Kubernetes tags:

To list CRI-O releases:

Recommendations:

• Prefer the latest patch in your minor series for fixes and security.
• Upgrade minor versions (X.Y→X.(Y+1)) only when needed or near EOL—wait 2–4 weeks post-release and test.
• Match CRI-O minor with Kubernetes and use the latest patch.

Example:: 

7. Configure node flavors
   In terraform.tfvars, specify the flavours of the master and workers:

List available flavors in Horizon (Compute → Flavors) or via CLI:

Depending on the actual load, choose instance configurations (flavor), in which there are two or more virtual processor cores, also 4 or more gigabytes of RAM.

We recommend::

* - Based on 10 pods per 1 vCPU and 5 pods per 1 GB RAM. The nominal number of pods may be different for your load.

Example: 

8. Select disk type
   In terraform.tfvars, specify the type of virtual machine disks:

Use the OpenStack CLI to list available disk types for <volume_type>:

We recommend using All-Flash-Datastore. 

Example: 

9. Select image
   In terraform.tfvars, specify the image name for the cluster node VMs:

To find available images for <image_name>, use Horizon UI (Compute → Images) or OpenStack CLI: 

We recommend using Debian_12_x64 for cluster nodes, as this image has been tested by us in a Kubernetes cluster environment.

For example:

10. Set default OS user
    In terraform.tfvars, specify the default user for the operating system whose image was selected in the previous step:

Images of popular Linux distributions usually contain a pre-created system user, for example:

• Ubuntu — default user: ubuntu;
• Debian — default user: debian;
• CentOS — default user: centos (or cloud-user in some builds);
• Fedora — default user: fedora.

Important: The default username must exactly match the one in the image — otherwise, the virtual machine cannot be configured automatically.

Example: 

11. Specify key pair
    In terraform.tfvars, specify an existing key pair from your project to manage cluster VMs:

To list available key pairs for <keypair>, use Horizon UI (Compute → Key Pairs) or OpenStack CLI: 

Example: 

12. Specify external network
    In terraform.tfvars, specify the ID of an existing external network in your project for cluster node connectivity:

To list external network IDs for <external_network_id>, use Horizon UI (Network → Networks → External Networks) or OpenStack CLI: 

Example: 

13. Enable/disable Dashboard
    In terraform.tfvars, specify if you want to install Kubernetes Dashboard on the cluster's control node:

Replace <dashboard_status> with:

• true — to install Kubernetes Dashboard,
• false — to skip installation.

Note: One Dashboard replica uses ~0.1–0.2 vCPU and 128–512 MB RAM (≈ 1–2 standard pods)..

Example: 

14. Save changes
    Save your edits to terraform.tfvars.
    
15. Initialize Terraform
    Go to the directory where the cluster deployment configuration is saved and run the command:

16. Format and validate
    Execute the commands:

If you see the message "Success! The configuration is valid," the configuration is correct, and you can proceed to the next step. 

If errors occur, fix them as indicated and retry the validation.

17. (Optional) Preview planned changes
    To review all infrastructure changes Terraform is about to make without actually applying them, run:
    

18. Apply infrastructure changes
    To start the cluster deployment, run:

Confirm when prompted:

Type yes and press Enter.

After completion, you’ll see something like:

This means the cluster was successfully deployed.

II. Connecting to the Kubernetes Dashboard

Our setup assumes masters are in a private network behind a load balancer, VPN, or bastion for security and resilience. To access the Dashboard directly, assign a floating IP to one master. Then you can SSH in, generate a token, and log in.

To connect, follow these steps:

1. Assign a floating IP
   Connect a floating IP to the master node via the Horizon control panel, following the instructions: “Attaching a Floating IP Address” or via Terraform, following the instructions: ”Allocating a Floating IP to an Instance”.
   
2. (Optional) Restrict key permissions
   If your private key was created through Horizon, it may be too permissive. 

Restrict it:

• Windows:
  Run the command as an administrator:

Where:

<path_to_private_key> — Path to the private key file (part of the key pair specified during cluster creation).

<username> — Name of the system user who will use the private key to connect to the master node.

Example:

• Linux / macOS:
  Run the following command in the terminal:

Where:
<path_to_private_key> — Path and filename of the private key associated with the key pair specified during cluster creation.

Example:

3. SSH to master
   Connect to the master node via SSH using the command:

Where:
<username> — Default OS username.

<master_node_IP> — IP address of the cluster’s master node.

-i — Specifies that the connection will use a private key, whose path is provided below.

<path_to_key> — Path and filename of the key.

Example:

4. Generate Dashboard token
   On the master node, generate and display a Kubernetes Dashboard token using the command:

Copy the displayed token.

5. Open Dashboard in browser
   Visit:

Where:
<master_IP> — IP address of the cluster master node.

Example:

The Kubernetes Dashboard authorisation page will open.

6. Log in
   Select Token as the authentication method, paste the token obtained in step 4 into the Enter token field, and click Sign In.
   
   
   
   You will be logged into the Kubernetes Dashboard.

III. Verification of Deployment

Check deployment status in Kubernetes Dashboard or via SSH to the master node.

Via Dashboard

1. Navigate to Cluster > Nodes.
2. Verify the total number of nodes per type matches your selected cluster_profile.
3. Check each node:
   1. Status: Ready
   2. CPU capacity (cores): Must match the chosen flavor for the node type.
   3. Memory capacity (bytes): memory capacity should match your flavor, noting Kubernetes reserves some RAM.

Via terminal

1. List nodes and their status/versions:

2. List nodes with CPU & memory capacities and allocatables:

What’s next?

See the official Kubernetes documentation [here] for further guidance.