Skip to content

kMetal Installation

This guide covers the installation of kMetal on a prepared under cluster.

Prerequisites

  • Under cluster — see Under Cluster Setup.
  • Registry credentials for ghcr.io/clastix/oci (Clastix-supplied).
  • A reserved IP range for MetalLB on the under cluster's external VLAN.

Step 1: Log in to the OCI registry

helm registry login ghcr.io -u <username> -p <token>

Step 2: Create the registry pull secret

The chart pulls images from a private registry. Create a pull secret in the namespace the chart will install into:

kubectl create namespace kmetal-flux

kubectl create secret docker-registry clastix-ghcr \
  --docker-server=ghcr.io \
  --docker-username=<username> \
  --docker-password=<token> \
  --namespace=kmetal-flux

Step 3: Prepare a values overlay

kMetal needs per-deployment configuration — at minimum the Kube-OVN tunnel interface and the MetalLB IP pool — provided through a values overlay file.

t.b.d. — A worked overlay example for typical hardware shapes is t.b.d. in this section. See Helm Values Reference for the supported top-level keys.

Step 4: Install the chart

helm install kmetal oci://ghcr.io/clastix/oci/kmetal \
  --namespace kmetal-flux \
  --values kmetal-values.yaml \
  --wait \
  --timeout=15m

Verify the release status:

helm status kmetal -n kmetal-flux

Step 5: Monitor installation

The chart deploys multiple component pods across several namespaces. Watch them come up:

kubectl get pods -n kmetal-cert-manager
kubectl get pods -n kube-flannel       # flannel
kubectl get pods -n kube-system        # kube-ovn
kubectl get pods -n kmetal-metallb
kubectl get pods -n kmetal-kamaji          # kamaji + kamaji-addon-ovn
kubectl get pods -n system-kubevirt
kubectl get pods -n system-cdi
kubectl get pods -n kmetal-capi-providers
kubectl get pods -n kmetal-local-path-storage

# Anything not Running or Completed
kubectl get pods -A | grep -v Running | grep -v Completed

Upgrade

helm upgrade kmetal oci://ghcr.io/clastix/oci/kmetal \
  --namespace kmetal-flux \
  --values kmetal-values.yaml \
  --wait \
  --timeout=15m

helm history kmetal -n kmetal-flux

Uninstall

Tenant clusters first

Delete every tenant Cluster before uninstalling the chart. Tearing down kMetal while tenant clusters still exist will leave orphaned VMs and PVCs.

# 1. Delete tenant clusters
kubectl get clusters -A
kubectl delete cluster <name> -n <namespace>      # for each

# 2. Uninstall the chart
helm uninstall kmetal -n kmetal-flux

# 3. Clean up namespaces (only after confirming nothing remains)
kubectl delete namespace kmetal-kamaji kubevirt cdi kmetal-metallb kmetal-capi-providers kmetal-local-path-storage cert-manager

Next Steps