Klustre Documentation on KlustreFS

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Klustre CSI Plugin is an open-source Container Storage Interface (CSI) node driver that lets Kubernetes workloads mount existing Lustre file systems. The project focuses on high-performance computing (HPC), AI/ML training, and media workloads that need shared ReadWriteMany semantics with the bandwidth of Lustre.

What does it provide?

Kubernetes-native storage – Exposes Lustre exports via CSI objects such as CSIDriver, PersistentVolume, and PersistentVolumeClaim.
Node daemonset – Runs a privileged pod on every Lustre-capable worker node to perform mounts and unmounts using the host’s Lustre client.
Static provisioning – Administrators define PersistentVolumes that point at existing Lustre paths (for example 10.0.0.1@tcp0:/lustre-fs) and bind them to workloads.
Helm and raw manifests – Install using the published manifests in manifests/ or the OCI Helm chart oci://ghcr.io/klustrefs/charts/klustre-csi-plugin.
Cluster policy alignment – Default RBAC, topology labels, and resource requests are tuned so scheduling is constrained to nodes that actually have the Lustre client installed.

Why would I use it?

Use the Klustre CSI plugin when you:

Requirements

Mon, 01 Jan 0001 00:00:00 +0000

Use this page when you need the full checklist (versions, node prep, and registry access) before installing Klustre CSI. The Quickstart and Introduction pages summarize this information, but this serves as a canonical reference.

Kubernetes cluster

Kubernetes v1.20 or newer with CSI v1.5 enabled.
Control plane and kubelets must allow privileged pods (hostPID, hostNetwork, SYS_ADMIN capability).
Cluster-admin kubectl access.

Lustre-capable worker nodes

Install the Lustre client packages (mount.lustre, kernel modules, user-space tools) on every node that will host Lustre-backed workloads.

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Looking for the fastest path from zero to a mounted Lustre volume? Follow this TL;DR workflow, then explore the detailed installation pages if you need customization.

Requirements

Before you sprint through the commands below, complete the requirements checklist. You’ll need:

kubectl, git, and optionally helm.
Worker nodes with the Lustre client installed and reachable MGS/MDS/OSS endpoints.
Nodes labeled lustre.csi.klustrefs.io/lustre-client=true.
The klustre-system namespace plus optional GHCR image pull secret (see the requirements page for the canonical commands).

Step 1 — Install Klustre CSI

export KLUSTREFS_VERSION=main
kubectl apply -k "github.com/klustrefs/klustre-csi-plugin//manifests?ref=$KLUSTREFS_VERSION"

Step 2 — Verify the daemonset

Wait for the DaemonSet rollout to complete:

Contribution Guidelines

Mon, 01 Jan 0001 00:00:00 +0000

These instructions target the klustrefs/website repository. Follow them whenever you update content, navigation, or styling.

Toolchain

Static site generator: Hugo extended edition, v0.146.0 or newer.
Theme: Docsy.
Package manager: npm (used for Docsy assets).
Hosting: Netlify deploy previews triggered from pull requests.

Contribution workflow

Fork https://github.com/klustrefs/website.
Create a feature branch (docs/my-topic).
Make your edits (Markdown lives under content/en/...).
Run npm install once, then npm run dev or hugo server to preview locally.
Commit with clear messages (docs: add getting started guide).
Open a pull request against main. If the work is in progress, prefix the title with WIP.
Ensure the Netlify preview (deploy/netlify — Deploy preview ready!) renders correctly before requesting review.

All PRs need review by a maintainer before merging. We follow the standard GitHub review process.

Mon, 01 Jan 0001 00:00:00 +0000

title: Concepts description: Understand the Klustre CSI architecture, components, and data flow. weight: 2

This page explains how the Klustre CSI Plugin is structured so you can reason about what happens when volumes are created, mounted, or removed.

High-level architecture

Klustre CSI Plugin implements the CSI node service for Lustre file systems. It focuses on node-side operations only:

Kubernetes API Kubelet on each node
-------------- --------------------
PersistentVolume -> NodePublishVolume -> mount.lustre -> Pod mount
PersistentVolumeClaim NodeUnpublishVolume -> umount.lustre

There is no controller deployment or dynamic provisioning. Instead, administrators define static PersistentVolume objects that reference existing Lustre exports. The plugin mounts those exports inside pods when a PersistentVolumeClaim is bound to a workload.