Fault Remediation

Overview

The Fault Remediation module is NVSentinel’s bridge to external repair systems. After a node has been quarantined and drained, this module creates maintenance requests that trigger break-fix workflows - such as node reboots, hardware replacements, or cloud provider interventions.

Think of it as a dispatch coordinator - similar to how a facility manager calls in specialists when equipment needs repair, Fault Remediation notifies your maintenance systems that a node is ready for servicing.

Why Do You Need This?

After NVSentinel isolates a faulty node and evacuates workloads, the hardware needs to be fixed:

• Hardware replacement: Faulty GPUs need to be physically replaced
• Node reboots: Some issues resolve with a clean restart
• GPU resets: Some issues resolve with a GPU reset
• Cloud provider actions: VMs may need termination and recreation

The Fault Remediation module creates Kubernetes Custom Resources (CRDs) that external operators (like Janitor) watch and act upon to perform the actual repair work.

How It Works

The Fault Remediation module watches the datastore for drained nodes that need repair:

1. Receives events with recommended actions (RESTART_VM, REPLACE_VM, etc.)
2. Filters out NONE and UNKNOWN actions
3. Checks if a maintenance CR already exists for the node
4. Optionally triggers log collection
5. Creates maintenance Custom Resource using configured template
6. Updates node labels to track remediation state

External operators watch for these CRs and perform the actual maintenance work (reboot, terminate, replace, etc.).

Configuration

Configure the Fault Remediation module through Helm values:

1
fault-remediation:
2
  enabled: true
3
  dryRun: false          # Test mode - logs actions without executing
4
5
  maintenance:
6
    actions:
7
      "RESTART_VM":
8
        apiGroup: "janitor.dgxc.nvidia.com"
9
        version: "v1alpha1"
10
        kind: "RebootNode"
11
        scope: "Cluster"
12
        completeConditionType: "NodeReady"
13
        templateFileName: "rebootnode-template.yaml"
14
        equivalenceGroup: "restart"
15
      "COMPONENT_RESET": 
16
        apiGroup: "janitor.dgxc.nvidia.com"
17
        version: "v1alpha1"
18
        kind: "GPUReset"
19
        scope: "Cluster"
20
        completeConditionType: "Complete"
21
        templateFileName: "gpureset-template.yaml"
22
        equivalenceGroup: "reset"
23
        impactedEntityScope: "GPU_UUID"
24
        supersedingEquivalenceGroups: ["restart"]
25
26
    templates:
27
      "rebootnode-template.yaml": |
28
        apiVersion: \{\{ .ApiGroup \}\}/\{\{ .Version \}\}
29
        kind: RebootNode
30
        metadata:
31
          name: maintenance-\{\{ .HealthEvent.NodeName \}\}-\{\{ .HealthEventID \}\}
32
        spec:
33
          nodeName: \{\{ .HealthEvent.NodeName \}\}
34
      "gpureset-template.yaml": |
35
        apiVersion: \{\{.ApiGroup\}\}/\{\{.Version\}\}
36
        kind: GPUReset
37
        metadata:
38
          name: maintenance-\{\{ .HealthEvent.NodeName \}\}-\{\{ .HealthEventID \}\}
39
        spec:
40
          nodeName: \{\{ .HealthEvent.NodeName \}\}
41
          selector:
42
            uuids:
43
              - \{\{ .ImpactedEntityScopeValue \}\}
44
  
45
  logCollector:
46
    enabled: false       # Enable log collection before remediation
47
    uploadURL: "http://nvsentinel-incluster-file-server.nvsentinel.svc.cluster.local/upload"
48
    timeout: "10m"

Configuration Options

• Dry Run: Test CRD creation without creating maintenance requests
• Maintenance CRD: Define the Custom Resource to create (apiGroup, version, kind, namespace)
• Template: Go template for generating CRDs
• Log Collection: Optionally collect diagnostic logs before remediation (syslog, GPU logs, driver information)

Key Features

Template-Based CRD Generation

Flexible Go template system to match your maintenance operator:

• Customize CRD structure
• Access node name, the impacted GPU UUID, event ID, and other properties
• Support different remediation types (reboot, terminate, replace)

Intelligent Filtering

Only creates requests when needed:

• Skips NONE and UNKNOWN actions
• Checks for existing maintenance CRs
• Prevents duplicate requests

State Tracking

Updates node labels throughout remediation lifecycle:

• remediating: Maintenance request created
• remediation-succeeded: Maintenance completed
• remediation-failed: Maintenance encountered errors

Optional Log Collection

Gather diagnostics before remediation for troubleshooting and root cause analysis.

Integration Patterns

The Fault Remediation module creates CRDs consumed by external operators:

Janitor Operator: Watches for maintenance CRDs and performs cloud provider API calls to reboot/terminate nodes. Custom Break-Fix Systems: Define custom CRD schemas and deploy operators to integrate with your own maintenance systems. Manual Workflow Systems: Deploy a controller that creates tickets from CRs for manual processing in your ticketing system.