{"id":42045825,"url":"https://github.com/vast-data/openshift-vastnfs-kmm-operator","last_synced_at":"2026-01-26T06:09:29.762Z","repository":{"id":317155010,"uuid":"1062610454","full_name":"vast-data/openshift-vastnfs-kmm-operator","owner":"vast-data","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-15T23:06:42.000Z","size":907,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-17T00:49:20.468Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vast-data.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-23T13:39:03.000Z","updated_at":"2025-10-15T23:06:46.000Z","dependencies_parsed_at":"2025-09-29T08:30:18.880Z","dependency_job_id":"deae56f6-a01e-4117-aa3c-b054e3185c2d","html_url":"https://github.com/vast-data/openshift-vastnfs-kmm-operator","commit_stats":null,"previous_names":["vast-data/openshift-vastnfs-kmm-operator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vast-data/openshift-vastnfs-kmm-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vast-data%2Fopenshift-vastnfs-kmm-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vast-data%2Fopenshift-vastnfs-kmm-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vast-data%2Fopenshift-vastnfs-kmm-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vast-data%2Fopenshift-vastnfs-kmm-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vast-data","download_url":"https://codeload.github.com/vast-data/openshift-vastnfs-kmm-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vast-data%2Fopenshift-vastnfs-kmm-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28768076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T03:54:34.369Z","status":"ssl_error","status_checked_at":"2026-01-26T03:54:33.031Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-26T06:09:29.258Z","updated_at":"2026-01-26T06:09:29.750Z","avatar_url":"https://github.com/vast-data.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VAST NFS KMM Operator for OpenShift\n\nThis repository provides automated deployment and management of **VAST NFS kernel modules** on OpenShift clusters using the Kernel Module Management (KMM) operator.\n\nVAST NFS is a high-performance NFS implementation that this operator installs and manages across your OpenShift nodes.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Prerequisites](#prerequisites)\n- [Quick Start](#quick-start)\n- [Installation Methods](#installation-methods)\n- [Usage](#usage)\n- [Verification](#verification)\n\n\n## Overview\n\nThis KMM (Kernel Module Management) operator enables automatic deployment and management of **VAST NFS kernel modules** across OpenShift clusters. \n\n**VAST NFS** is a high-performance NFS implementation that provides a modified version of the Linux NFS client and server kernel code stacks. It contains backported upstream NFS stack code from Linux v5.15.x LTS kernel branch, allowing older kernels to receive the full functionality of newer NFS stack code.\n\nFor complete VAST NFS documentation, refer to the [official VAST NFS documentation](https://vastnfs.vastdata.com/docs/4.0/Intro.html).\n\n### VAST NFS Features\n\nVAST NFS provides enhanced NFS capabilities including:\n\n- **NFS stack improvements and fixes** from Linux v5.15.x LTS\n- **Multipath support** for NFSv3 and NFSv4.1\n- **Nvidia GDS integration** for high-performance workloads\n- **Kernel compatibility** for kernels 4.15.x and above\n- **Performance optimizations** for enterprise workloads\n\n### KMM Operator Features\n\nThis KMM operator handles the automated installation and management of the VAST NFS driver, providing:\n\n- **Automatic kernel module building and loading**\n- **Multi-node deployment via DaemonSet**\n- **Secure boot environments**\n- **Comprehensive verification**\n- **Clean uninstallation**\n\n### Architecture\n\n![VAST NFS KMM Architecture \u0026 Workflow](img/vast_nfs_kmm_architecture_workflow.png)\n\n## Prerequisites\n\n### Required Tools\n- `oc` or `kubectl` CLI tool\n- `kustomize` (automatically installed if missing)\n- OpenShift cluster with KMM operator installed\n- Cluster admin privileges\n\n### KMM Operator Installation\nIf KMM operator is not installed:\n\n![KMM Operator Installation](img/kmm-operator-installation.gif)\n\n\n## Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/vast-data/openshift-vastnfs-kmm-operator\ncd openshift-vastnfs-kmm-operator\n\n# Install VAST NFS kernel modules (includes real-time log monitoring)\nmake install\n\n# Wait for deployment to complete (see timing note below)\n# then verify deployment\nmake verify\n\n# Upgrade to a new version (automatic graceful handling)\nexport VASTNFS_VERSION=4.0.36\nmake install\n\n# Uninstall (automatic graceful cleanup)\nmake uninstall\n```\n\n**Important Timing Note:** After `make install` completes the build stage, please wait approximately 1-2 minutes before running `make verify`. This allows time for:\n\n- The built kernel module image to be distributed to all nodes\n- DaemonSet pods to start on each node\n- The `modprobe` operation to load the VAST NFS kernel modules\n- All components to reach a ready state\n\nRunning `make verify` too early may show incomplete deployment status.\n\n## Installation Methods\n\n### 1. Standard Installation\n\n**Installation with real-time log monitoring:**\n```bash\nmake install\n\n# Wait 1-2 minutes for DaemonSet deployment, then verify\nmake verify\n```\n\n\n### 2. Secure Boot Installation\n\n**Generate keys and install (includes log monitoring):**\n```bash\nmake install-secure-boot\n\n# Wait 2-3 minutes for secure boot signing and DaemonSet deployment, then verify\nmake verify\n```\n\n**Using existing keys (includes log monitoring):**\n```bash\nexport PRIVATE_KEY_FILE=/path/to/private.key\nexport PUBLIC_CERT_FILE=/path/to/public.crt\nmake install-secure-boot-with-keys\n\n# Wait 2-3 minutes for secure boot signing and DaemonSet deployment, then verify\nmake verify\n```\n\n\n### 3. Custom Configuration\n\n**Optional environment variable overrides:**\n```bash\nexport NAMESPACE=my-namespace\nexport VASTNFS_VERSION=4.0.36\nmake install\n```\n\n### 4. Manual Manifest Generation\n\nFor fine-grained control over resources, generate and customize manifests:\n\n```bash\n# Generate consolidated manifest\nmake build-installer\n\n# Review and customize the generated manifest\nvi dist/install.yaml\n\n# Apply manually\noc apply -f dist/install.yaml\n```\n\nThis approach allows you to:\n- Review all resources before deployment\n- Customize specific configurations\n- Apply manifests in stages\n- Integrate with CI/CD pipelines\n\n\n## Upgrading VAST NFS Version\n\nUpgrading is fully automatic! Simply run `make install` with the new version:\n\n```bash\n# Upgrade to a new version (automatic graceful unload if already installed)\nexport VASTNFS_VERSION=4.0.36\nmake install\n\n# Wait 1-2 minutes for rebuild and deployment, then verify\nmake verify\n```\n\n### How Upgrades Work\n\n- `make install` automatically detects if VAST NFS is already loaded\n- If loaded (upgrade scenario): automatically performs graceful unload first\n- If not loaded (fresh install): proceeds directly with installation\n- Graceful unload unmounts NFS filesystems, stops services, and cleanly unloads modules\n- This prevents \"module in use\" errors during upgrades\n\nThe operator includes the VAST NFS version in the container image tag:\n```\nimage-registry.openshift-image-registry.svc:5000/vastnfs-kmm/vastnfs:${KERNEL_FULL_VERSION}-vastnfs-${VASTNFS_VERSION}\n```\n\nFor example:\n- **Version 4.0.35**: `5.14.0-570.33.1.el9_6.x86_64-vastnfs-4.0.35`\n- **Version 4.0.36**: `5.14.0-570.33.1.el9_6.x86_64-vastnfs-4.0.36`\n\nThis ensures that:\n1. KMM detects the version change and triggers a rebuild\n2. A new container image is built with the updated VAST NFS version\n3. KMM rolls out the new modules to all matching nodes\n4. The old modules are unloaded and new ones loaded automatically\n\n### Uninstallation\n\nExecute the following command to uninstall VAST NFS:\n\n```bash\nmake uninstall\n```\n\nThe `uninstall` target automatically:\n- Gracefully unloads VAST NFS modules from all nodes\n- Unmounts all NFS filesystems\n- Stops RPC services cleanly\n- Unloads kernel modules in the correct order\n- Removes all KMM resources (Module, ConfigMaps, ServiceAccounts, etc.)\n- Cleans up ImageStreams\n\nNo manual steps required!\n\n## Usage\n\n### Available Make Targets\n\n| Target | Description |\n|--------|-------------|\n| `make install` | Install or upgrade VAST NFS (auto-detects and handles graceful unload) |\n| `make install-secure-boot` | Secure boot installation with real-time log monitoring |\n| `make install-secure-boot-with-keys` | Secure boot with existing keys and real-time log monitoring |\n| `make uninstall` | Complete removal (automatically performs graceful unload first) |\n| `make verify` | Deployment verification |\n| `make build-installer` | Generate consolidated manifest in `dist/install.yaml` |\n| `make help` | Show all targets |\n\n### Log Monitoring\n\nAll installation commands now include real-time log monitoring by default. The installation will:\n\n1. **Install resources** - Deploy all KMM components\n2. **Wait for pods** - Monitor pod creation (up to 60 seconds)\n3. **Wait for containers** - Wait for containers to be ready (up to 5 minutes)\n4. **Stream logs** - Follow real-time logs with retry logic\n5. **Continue until interrupted** - Press `Ctrl+C` to stop\n\n**Post-Build Deployment Process:** After the build stage completes and you interrupt the log streaming:\n\n1. **Image Distribution** - The built kernel module image is pushed to the internal registry\n2. **DaemonSet Creation** - KMM creates DaemonSet pods on nodes matching the kernel version\n3. **Module Loading** - Each node downloads the image and runs `modprobe` to load VAST NFS modules\n4. **Ready State** - Modules become active and available for NFS operations\n\nThis post-build process typically takes 1-2 minutes (2-3 minutes for secure boot scenarios).\n\n**Example output:**\n```\n[STEP] Waiting for pods to start...\n[SUCCESS] Found pods: vastnfs-pull-pod-f9t9h\n[STEP] Following pod logs...\n[INFO] === Preparing to follow logs for vastnfs-pull-pod-f9t9h ===\n[INFO] Waiting for pod vastnfs-pull-pod-f9t9h to be ready...\n[SUCCESS] Pod vastnfs-pull-pod-f9t9h is ready for log streaming\n[INFO] Starting log stream for vastnfs-pull-pod-f9t9h...\n```\n\n## Verification\n\n\u003e **IMPORTANT:** After running `make install`, wait approximately **1-2 minutes** before verification. This allows time for:\n\u003e - Kernel module compilation to complete\n\u003e - DaemonSet pods to start on all cluster nodes  \n\u003e - VAST NFS kernel modules to be loaded via modprobe\n\u003e\n\u003e For secure boot installations, allow **2-3 minutes** due to additional signing time.\n\n### Automatic Verification\n```bash\nmake verify\n```\n\n### Manual Verification\n```bash\n# Check module status\noc get module vastnfs -n vastnfs-kmm\n\n# Check VAST NFS version on nodes\noc debug node/\u003cnode-name\u003e -- chroot /host cat /sys/module/sunrpc/parameters/nfs_bundle_version\n\n# Check loaded modules\noc debug node/\u003cnode-name\u003e -- chroot /host lsmod | grep -E \"(sunrpc|rpcrdma|nfs)\"\n```\n\n\n## Troubleshooting\n\nFor comprehensive VAST NFS driver troubleshooting and advanced configuration, refer to the [official VAST NFS documentation](https://vastnfs.vastdata.com/docs/4.0/Intro.html).\n\n### Common Issues\n\n**1. Installation hangs during uninstall:**\n```bash\n# The Makefile automatically handles finalizer removal\n# If still stuck, manually remove finalizers:\noc patch module vastnfs -n vastnfs-kmm -p '{\"metadata\":{\"finalizers\":[]}}' --type=merge\n```\n\n**2. Log following fails:**\n```bash\n# Check pod status\noc get pods -n vastnfs-kmm\n\n# Manual log access\noc logs \u003cpod-name\u003e -n vastnfs-kmm\n```\n\n**3. Module loading fails:**\n```bash\n# Check KMM operator logs\noc logs -n openshift-kmm deployment/kmm-operator-controller\n\n# Check node compatibility\noc debug node/\u003cnode-name\u003e -- chroot /host uname -r\n```\n\n**4. Secure boot issues:**\n```bash\n# Verify secure boot status\noc debug node/\u003cnode-name\u003e -- chroot /host mokutil --sb-state\n\n# Check module signatures\noc debug node/\u003cnode-name\u003e -- chroot /host modinfo sunrpc | grep signature\n```\n\n### Debug Commands\n\n```bash\n# Check all resources\noc get all -n vastnfs-kmm\n\n# Check module details\noc describe module vastnfs -n vastnfs-kmm\n\n# Check events\noc get events -n vastnfs-kmm --sort-by='.lastTimestamp'\n\n# Check node status\noc get nodes\noc describe node \u003cnode-name\u003e\n```\n\n## Additional Resources\n\n### VAST NFS Driver Documentation\nFor comprehensive information about the VAST NFS driver features, configuration, and troubleshooting, see the official documentation: [VAST NFS Documentation](https://vastnfs.vastdata.com/docs/4.0/Intro.html)\n\nThe documentation includes:\n- **Installation methods** for different Linux distributions\n- **Configuration options** including multipath setup\n- **Usage examples** and mount parameters  \n- **Monitoring and diagnosis** tools\n- **Troubleshooting guides** for common issues\n\n## Configuration\n\nAll variables have sensible defaults. Override only if needed.\n\n### Optional Environment Variable Overrides\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `NAMESPACE` | `vastnfs-kmm` | Target namespace |\n| `VASTNFS_VERSION` | `4.0.35` | VAST NFS version |\n| `KMM_IMG_REPO` | Auto-generated | Container image repository |\n| `KMM_IMG_TAG` | `${KERNEL_FULL_VERSION}` | Container image tag |\n| `KMM_PULL_SECRET` | Empty | Optional pull secret for private registries |\n| `KUSTOMIZE_DIR` | `k8s/base` | Kustomization directory |\n\n### Customization\n\n**Custom namespace:**\n```bash\nexport NAMESPACE=my-vastnfs\nmake install\n```\n\n**Custom version:**\n```bash\nexport VASTNFS_VERSION=4.0.36\nmake install\n```\n\n## Secure Boot Support\n\n### Key Generation\n```bash\n# Generate new signing keys\nmake generate-secure-boot-keys\n\n# Keys will be created in: secure-boot-keys/\n```\n\n### Installation with Secure Boot\n```bash\n# Method 1: Auto-generate keys (includes log monitoring)\nmake install-secure-boot\n\n# Method 2: Use existing keys (includes log monitoring)\nexport PRIVATE_KEY_FILE=/path/to/signing.key\nexport PUBLIC_CERT_FILE=/path/to/signing.crt\nmake install-secure-boot-with-keys\n```\n\n### Verification\n```bash\n# Verify secure boot deployment\nmake verify-secure-boot\n\n# Or use regular verification\nmake verify\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvast-data%2Fopenshift-vastnfs-kmm-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvast-data%2Fopenshift-vastnfs-kmm-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvast-data%2Fopenshift-vastnfs-kmm-operator/lists"}