Setup Under Cluster¶

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

Lab / evaluation path

This walkthrough uses a temporary single-VM Kubernetes cluster to demonstrate the kMetal installation and interface. It is not a supported kMetal deployment and does not evaluate the complete platform. kMetal deployments and full proofs of concept require bare-metal infrastructure, see the Admin Guide: Under Cluster Setup.

Prerequisites¶

Before beginning the setup, ensure you have access to a 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, 2 NICs (the second is required for kMetal's provider network)

Operating System¶

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

Access Requirements¶

SSH access to the machine
sudo/root privileges on the 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¶

yctl drives YAKI, the CLASTIX bootstrap script, over SSH. Bootstrapping this way is also what makes the cluster's own Kubernetes version upgradeable later from inside the cluster — see Node Upgrades.

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 Evaluation Machine¶

Connect to your host and prepare it for cluster installation.

Connect and Update¶

# Connect to your host
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 evaluation 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 evaluation 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 evaluation 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 evaluation 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.

Install CNI¶

kMetal does not install a primary CNI and will not start without one. Install Flannel now, before verifying the cluster:

helm install flannel flannel/flannel \
  --version v0.28.2 \
  --namespace kube-flannel --create-namespace \
  --repo https://flannel-io.github.io/flannel \
  --set podCidr=$POD_CIDR \
  --set flannel.backend=host-gw

kubectl rollout status -n kube-flannel ds/kube-flannel-ds

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