Advanced Installation on KlustreFS

Kind Quickstart

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

This walkthrough targets Linux hosts with Docker/Podman because Kind worker nodes run as containers. macOS and Windows hosts cannot load kernel modules required by Lustre, but you can still observe the driver boot sequence. The shim below fakes mount.lustre with tmpfs so you can run the end-to-end demo locally.

Requirements

Docker 20.10+ (or a compatible container runtime supported by Kind).
Kind v0.20+.
kubectl v1.27+ pointed at your Kind context.
A GitHub personal access token with read:packages if you plan to pull images from GitHub Container Registry via an image pull secret (optional but recommended).

1. Create a Kind cluster

Save the following Kind configuration and create the cluster:

Amazon EKS Notes

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

The AWS-oriented quickstart is under construction. It will cover:

Preparing EKS worker nodes with the Lustre client (either Amazon Linux extras or the FSx-provided packages).
Handling IAM roles for service accounts (IRSA) and pulling container images from GitHub Container Registry.
Connecting to FSx for Lustre file systems (imported or linked to S3 buckets) and exposing them via static PersistentVolumes.

Until the full write-up lands, adapt the Introduction flow by:

Installing the Lustre client on your managed node groups (e.g., with yum install lustre-client in your AMI or through user data).
Labeling the nodes that have Lustre access with lustre.csi.klustrefs.io/lustre-client=true.
Applying the Klustre CSI manifests or Helm chart in the klustre-system namespace.

Feedback on which AWS-specific topics matter most (FSx throughput tiers, PrivateLink, IAM policies, etc.) is welcome in the community discussions.

Bare Metal Notes

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

This guide will describe how to prepare on-prem or colocation clusters where you manage the operating systems directly (kernel modules, Lustre packages, kubelet paths, etc.). While the detailed walkthrough is in progress, you can already follow the general Introduction page and keep the following considerations in mind:

Ensure every node that should host Lustre-backed pods has the Lustre client packages installed via your distribution’s package manager (for example, lustre-client RPM/DEB).
Label those nodes with lustre.csi.klustrefs.io/lustre-client=true.
Grant the klustre-system namespace Pod Security admission exemptions (e.g., pod-security.kubernetes.io/enforce=privileged) because the daemonset requires hostPID, hostNetwork, and SYS_ADMIN.

If you are interested in helping us document more advanced configurations (multiple interfaces, bonded networks, RDMA, etc.), please open an issue or discussion in the GitHub repository.

Install with Helm

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

The Helm chart is published under oci://ghcr.io/klustrefs/charts/klustre-csi-plugin.

1. Authenticate (optional)

If you use a GitHub personal access token for GHCR:

helm registry login ghcr.io -u <github-user>

Skip this step if anonymous pulls are permitted in your environment.

2. Install or upgrade

helm upgrade --install klustre-csi \
 oci://ghcr.io/klustrefs/charts/klustre-csi-plugin \
 --version 0.1.1 \
 --namespace klustre-system \
 --create-namespace \
 --set imagePullSecrets[0].name=ghcr-secret

Adjust the release name, namespace, and imagePullSecrets as needed. You can omit the secret if GHCR is reachable without credentials.

Install with kubectl/manifests

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

1. Install directly with Kustomize (no clone)

If you just want a default install, you don’t need to clone the repository. You can apply the published manifests directly from GitHub:

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

The manifests/ directory includes the namespace, RBAC, CSIDriver, daemonset, node service account, default StorageClass (klustre-csi-static), and settings config map.

2. Work from a local clone (recommended for customization)

If you plan to inspect or customize the manifests, clone the repo and work from a local checkout: