loading
loading
NVIDIA GPUDirect Storage (GDS) accelerates GPU storage access in on-premises and cloud environments. It provides a robust, portable, and efficient data path between NVIDIA GPUs and storage targets to increase bandwidth, minimize latency, and reduce CPU and memory utilization across a broad range of platforms, application frameworks, and workload patterns. Configuring NVIDIA GPUDirect Storage starts with understanding your environment. Which settings and storage paths are appropriate for your platform and workload? Extensive documentation describes how to configure and troubleshoot supported architectures and storage solutions, but you must navigate this information and optimize your deployment. The gds-diag tool was developed by the GPUDirect Storage team to simplify optimization and configuration of GPUDirect Storage. gds-diag is a simple, open-source command-line utility that assesses environments, identifies problems, and suggests improvements to help you make the most of your GDS deployment. It is also bundled with an optional agent skill that adds a natural-language interface and orchestration layer. The skill interprets your intent, selects and invokes the appropriate subcommands, and coordinates multi-step diagnostic workflows. Beyond command selection and routing, the skill extends gds-diag with model-guided reasoning. It can interpret diagnostic results, apply relevant system context, and propose or carry out appropriate remediation. This post shows you how to get started with gds-diag using either the command-line interface or the agent skill. Download and installation To use gds-diag, you need a Linux system with Python 3.8 or newer. GPUDirect Storage requires an NVIDIA datacenter-class GPU and NVIDIA CUDA Toolkit 12.2 or newer, but these are not dependencies of gds-diag itself. gds-diag is distributed as part of the NVIDIA Magnum IO GitHub repository with no other dependencies to install. Clone the repository on the machine where you plan to run it with git clone https://github.com/NVIDIA/MagnumIO.git and select one of the following usage models: - Command-line tool: This provides a deterministic, minimal-dependency path to diagnose GDS deployments. Go to the gds-diag directory, run gds-diag.py --help, and follow the Command-line usage guidance. - AI agent: This provides the most intuitive, flexible, interactive, natural-language mechanism to diagnose GDS deployments while still retaining the reliable determinism of the underlying command-line tool. Open the gds-diag directory in your preferred AI coding assistant and follow the Agent skill usage guidance. Command-line usage The gds-diag command-line tool is a single Python script with multiple subcommands to focus on different diagnostic tasks. You can browse available subcommands by running ./gds-diag.py --help. For more information about a specific subcommand, run ./gds-diag.py <subcommand> --help. Figure 2 groups the available subcommands into four categories. Choose a diagnostic category based on your stage of deployment or the problem you need to investigate. - End-to-end checks: Use all to automatically select appropriate diagnostics for your environment and run them in sequence. - Preparing for installation: Use pre-install to check GPU support and CUDA Toolkit installation. Use support-matrix to view supported storage targets and plan your deployment. - Validating an installation: Use post-install to check whether GDS is installed correctly and identify blockers. Use config-audit to review configuration files and environment variables that influence GDS behavior. - Deep diagnostics: Use container-check to assess GDS support in container environments, including containerd, Docker, Enroot, and Kubernetes. Use mount-check to diagnose a specific mount point or directory. The anatomy of a gds-diag finding The output of most gds-diag subcommands is presented as a set of findings grouped into sections, as Figure 3 shows. Each finding and each section has a status badge. - “FAIL” indicates a hard blocker. - “WARN” indicates a potential blocker. - “INFO” communicates notable information. - “PASS” indicates a nominal finding and is shown only when you use the --verbose option. Each finding includes an explanation followed by a mitigation plan. gds-diag will not implement the mitigation plan or otherwise modify the system on its own. Its role is to identify problems and optimization opportunities and help you or your administrator make improvements. Multiple sections (and findings within those sections) may be shown. Most subcommands follow the same structure. The gds-diag.py support-matrix command is a notable exception: it emits output in the form of a table with footnotes. This subcommand shows which platform combinations GDS supports. Use the --static option to present general data (shown in Figure 4) or the --live option to incorporate information from the system as presently configured. Items marked in green are fully supported, items marked in yellow are supported depending on architectural or configuration caveats, and items marked in red are not supported. Command-line demo To demonstrate, consider preparing a new or modified GDS configuration file for production deployment. The config-audit subcommand is an ideal choice for this scenario. If called with no arguments, it will audit the current effective configuration, including both static configuration files and dynamic environment variable modifiers. The following example uses the --config option to specify a candidate configuration to review. The configuration audit reveals a misspelled entry in the configuration file. After you correct the error, config-audit confirms that the configuration is valid and provides additional informational hints. Agent skill usage The gds-diag agent skill activates automatically when you open the gds-diag repository using a coding assistant such as Claude or Codex. The skill does not attempt to duplicate deterministic checks that are already provided by the gds-diag command-line tool. Instead, its primary role is to aid in routing between gds-diag subcommands and interpreting their output. The following are a few examples of queries you could pose using the skill: - Is this system eligible to use GDS? - Is it available for /mnt/data? - How do I configure GDS optimally to access /mnt/data? - What configuration files are being used by GDS? - Do any configuration parameters need to be updated? - Which NVMe device has the best locality to GPU3? Agents are a capability multiplier for gds-diag; you can ask follow-up questions or even ask the agent to implement mitigations on your behalf. Agent skill demo Figure 6 shows how to combine the gds-diag agent skill with a model’s inherent reasoning to diagnose a container configuration problem. This example uses Anthropic Claude Code CLI. In this case, the agent inspects the shell script used to launch the container and determines the best gds-diag tool to use to investigate the problem. It then offers the option to modify the script in response to its findings and confirms the solution. Note that the coding assistant will honor your local settings and site policies to determine which actions require confirmation. Get started Use gds-diag as your first diagnostic tool when investigating GPUDirect Storage configuration and optimization. Its modular design provides a foundation for additional diagnostics, such as checks for network transports, object storage systems, and application frameworks. Have a diagnostic check or file system you would like to contribute? Community contributions are welcome and strongly encouraged. Both the source code and the agent skill are published under open-source licenses (Apache 2.0 and Creative Commons Attribution 4.0 International). See the contributor guidelines to get started.
document fetched 2026-10-31 02:54 · canonical https://developer.nvidia.com/blog/how-to-check-and-configure-nvidia-gpudirect-storage-for-your-platform