Configuring and Validating NVIDIA GPUDirect Storage with gds-diag
Optimize GPU storage performance using the open-source gds-diag diagnostic utility and agent.
1Introducing the gds-diag Utility
The gds-diag tool is an open-source command-line utility designed to assess environments for NVIDIA GPUDirect Storage. It identifies configuration issues and suggests performance improvements for data paths between GPUs and storage. Administrators can clone the tool from the NVIDIA Magnum IO GitHub repository to begin validating their specific deployment environments.
2System Requirements and Installation
To run gds-diag, you must have a Linux system equipped with Python 3.8 or newer. While GPUDirect Storage itself requires NVIDIA datacenter-class GPUs and CUDA Toolkit 12.2, these are not direct dependencies for the diagnostic utility. The tool is distributed as a single Python script within the Magnum IO repository.
3Categorized Diagnostic Subcommands
The utility organizes subcommands into four distinct categories: end-to-end checks, pre-installation validation, post-installation verification, and deep diagnostics for containers. Users can access help menus via the command line to identify the appropriate category for their current deployment stage. This modular structure ensures that users can target specific architectural or configuration concerns.
4Interpreting Diagnostic Findings
Findings are presented with status badges labeled FAIL, WARN, INFO, or PASS. Each result includes a detailed explanation and a specific mitigation plan for administrators to implement. The tool does not modify system settings automatically, ensuring that human oversight remains central to the configuration process and production environment safety.
5Support Matrix and Auditing
The support-matrix subcommand provides a table showing supported platform combinations, using color-coded indicators for full, partial, or unsupported configurations. Additionally, the config-audit command reviews current settings, including static files and environment variables. This allows users to detect errors, such as misspelled entries, before they impact production storage performance or connectivity.
6Leveraging Agent-Based Diagnostics
An optional agent skill integrates with coding assistants like Claude or Codex to provide a natural-language interface. This layer orchestrates multi-step workflows and applies model-guided reasoning to interpret diagnostic results. It helps users route between subcommands and proposes remediation steps based on the specific system context and identified configuration bottlenecks.
7Containerized Environment Troubleshooting
The agent skill excels at diagnosing container startup problems by inspecting launch scripts and determining the necessary gds-diag subcommands. It can suggest modifications to shell scripts while adhering to local site policies and security settings. This capability simplifies the complex task of debugging storage access within isolated containerized GPU workloads.
8Community and Future Extensibility
Both the source code and agent skill are published under open-source licenses, specifically Apache 2.0 and Creative Commons. NVIDIA encourages community contributions to expand diagnostic checks for network transports and object storage systems. This collaborative approach ensures the tool evolves alongside new application frameworks and diverse storage architectures in the future.