Setup Under Cluster¶

This guide provides step-by-step instructions for setting up an under cluster for kMetal. The under cluster is a standard Kubernetes cluster that hosts the kMetal platform components.

Lab / evaluation path

The walkthrough below uses yctl to bring up a single-VM Kubernetes cluster — fine for evaluating kMetal but not a production under cluster. Production kMetal under clusters are 3-node HA Kubernetes installations. For the production-grade setup, see the Admin Guide: Under Cluster Setup.

Prerequisites¶

Before beginning the setup, ensure you have access to a virtual machine that meets the following requirements:

Hardware Requirements¶

CPU: 4 cores minimum (8+ cores recommended)
Memory: 8 GB RAM minimum (16+ GB recommended)
Storage: 50 GB disk space minimum (100+ GB recommended)
Network: Internet connectivity

Operating System¶

Ubuntu 24.04 LTS
Other Linux distributions may work but are not officially supported

Access Requirements¶

SSH access to the virtual machine
sudo/root privileges on the virtual machine

Prepare Your Workstation¶

Install required command line tools on your workstation.

Install kubectl¶

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/
kubectl version --client

Install helm¶

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
helm version

Install flux¶

curl -s https://fluxcd.io/install.sh | sudo bash
flux version

Install yctl¶

curl -fsSL -o yctl https://github.com/clastix/yctl/releases/latest/download/yctl-linux-amd64
chmod +x yctl
sudo mv yctl /usr/local/bin/
yctl version

Prepare Your Virtual Machine¶

Connect to your VM and prepare it for cluster installation.

Connect and Update¶

# Connect to your VM
ssh username@machine_address

# Update system packages
sudo apt update && sudo apt upgrade -y

Configure Hostname and Collect Info¶

# Set hostname
sudo hostnamectl set-hostname kmetal
hostname -f

# Collect system information for cluster setup
echo "Hostname: $(hostname -s)"
echo "Domain: $(hostname -d)"
echo "IP Address: $(hostname -I | awk '{print $1}')"
echo "Interface: $(ip route | grep default | awk '{print $5}')"

FQDN Resolution

The fully qualified domain name (FQDN) will be used to access the cluster. Ensure it's resolvable from both the virtual machine and your workstation. Configure DNS records or add entries to /etc/hosts if needed.

Configure Under Cluster¶

Return to your workstation to configure and deploy the under cluster.

Set Environment Variables¶

Configure the cluster settings using the information gathered from your virtual machine:

export CLUSTER_NAME=<hostname>
export CLUSTER_DOMAIN=<domain>
export CONTROL_PLANE_ENDPOINT=<address>
export CONTROL_PLANE_PORT=6443
export CONTROL_PLANE_INTERFACE=<interface>
export KUBERNETES_VERSION="v1.32.4"
export POD_CIDR="10.36.0.0/16"
export SVC_CIDR="10.96.0.0/16"

Replace Placeholder Values

Update the <hostname>, <domain>, <address>, and <interface> placeholders with the actual values from your virtual machine information collected above.

Run Pre-flight Checks¶

Verify your environment before installation:

# Check system requirements
yctl check --cluster-name $CLUSTER_NAME \
  --kubernetes-version $KUBERNETES_VERSION

# Verify network connectivity
yctl check --network \
  --control-plane-endpoint $CONTROL_PLANE_ENDPOINT \
  --interface $CONTROL_PLANE_INTERFACE

Network Access Requirements

Ensure these ports are accessible from your workstation to the virtual machine:

Port 22: SSH access for yctl cluster management
Port 6443: Kubernetes API server (required for kubectl access)
Port 443: HTTPS access for console and ingress services

Configure your firewall rules to allow inbound traffic on these ports. If using cloud infrastructure, update security groups or network ACLs accordingly.

Deploy Under Cluster¶

Now you're ready to deploy the under cluster using yctl.

Install the Cluster¶

Deploy your under cluster with the configured settings:

# Install the cluster using CLI options
yctl cluster install \
  --cluster-name $CLUSTER_NAME \
  --cluster-domain $CLUSTER_DOMAIN \
  --control-plane-endpoint $CONTROL_PLANE_ENDPOINT \
  --control-plane-port $CONTROL_PLANE_PORT \
  --control-plane-interface $CONTROL_PLANE_INTERFACE \
  --kubernetes-version $KUBERNETES_VERSION \
  --pod-cidr $POD_CIDR \
  --service-cidr $SVC_CIDR \
  --no-taints

Monitor Installation¶

# Check status
yctl cluster status --cluster-name $CLUSTER_NAME

# Or watch progress
watch yctl cluster status --cluster-name $CLUSTER_NAME

Installation typically takes 2-3 minutes. If it hangs for more than 5 minutes, check network connectivity, system resources, firewall rules, and DNS resolution.

Verify Installation¶

After installation completes, verify that your cluster is working correctly.

kubectl Configuration

yctl automatically configures kubectl access. Ensure the FQDN is resolvable and port 6443 is accessible.

# Check node status (should show Ready)
kubectl get nodes

# Check system pods (should all be Running)
kubectl get pods -n kube-system

# Check cluster information
kubectl cluster-info

# Optional: Test with a simple pod
kubectl run test-pod --image=nginx:alpine --port=80
kubectl wait --for=condition=Ready pod/test-pod --timeout=60s
kubectl delete pod test-pod

Troubleshooting¶

If installation fails:

Check network connectivity and firewall rules (ports 22, 6443, 443)
Verify FQDN configuration and DNS resolution
Ensure system resources meet minimum requirements

Reset and restart:

yctl cluster reset --cluster-name $CLUSTER_NAME

See Troubleshooting Guide for detailed help.

Quick Reference¶

# Check cluster status
kubectl get nodes
kubectl get pods -A

# yctl commands
yctl cluster status --cluster-name $CLUSTER_NAME
yctl cluster reset --cluster-name $CLUSTER_NAME

Next Steps¶

Your under cluster is now ready for kMetal installation. Continue to Install kMetal