initial commit

roles/nvidia-drivers/README.md

@@ -0,0 +1,68 @@
+# NVIDIA Drivers Role
+
+Installs NVIDIA drivers and CUDA runtime on Debian/Ubuntu systems with proper idempotency and error handling.
+
+## Features
+
+- Automatic OS detection (Debian/Ubuntu)
+- Idempotent repository management
+- Support for both proprietary and open-source drivers
+- Post-installation verification
+- Automatic cleanup on failures
+- Architecture detection (x86_64/arm64)
+
+## Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `nvidia_install_kernel_modules` | `false` | Install kernel modules (full drivers) vs userspace only |
+| `nvidia_open_source_drivers` | `false` | Use open-source nvidia-open instead of proprietary drivers |
+| `nvidia_cuda_runtime_version` | `"13-1"` | CUDA runtime version to install |
+| `nvidia_optional_packages` | `[]` | Additional NVIDIA packages to install |
+| `kernel_module_type` | `linux` | Kernel module type (linux/linux-image) |
+
+## Usage
+
+### Full Driver Installation (with kernel modules)
+```yaml
+- name: Install NVIDIA drivers with kernel modules
+  include_role:
+    name: nvidia-drivers
+  vars:
+    nvidia_install_kernel_modules: true
+    nvidia_open_source_drivers: false
+```
+
+### Userspace Only (containers/existing drivers)
+```yaml
+- name: Install NVIDIA userspace libraries
+  include_role:
+    name: nvidia-drivers
+  vars:
+    nvidia_install_kernel_modules: false
+```
+
+### With Optional Packages
+```yaml
+- name: Install NVIDIA with extras
+  include_role:
+    name: nvidia-drivers
+  vars:
+    nvidia_install_kernel_modules: true
+    nvidia_optional_packages:
+      - nvidia-settings
+      - nvidia-modprobe
+```
+
+## Requirements
+
+- Debian 11+ or Ubuntu 20.04+
+- Root privileges
+- Internet connectivity
+
+## Notes
+
+- Role is idempotent - safe to run multiple times
+- Automatically detects if drivers are already installed
+- Cleans up on installation failures
+- Supports both x86_64 and arm64 architectures