rhaii-cluster-validation: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

kubectl plugin (kubectl rhaii-validate) for validating GPU cluster readiness for AI/ML workloads. Runs hardware and network checks on GPU nodes via privileged Kubernetes Jobs. Auto-detects GPU vendor (NVIDIA/AMD), platform (AKS/EKS/CoreWeave/OCP), and cluster topology.

Binary: rhaii-validator. kubectl plugin name: kubectl-rhaii_validate.

Epic: INFERENG-4707

Build and Test Commands

make build              # CGO_ENABLED=0 go build → bin/rhaii-validator
make install            # Build + install as kubectl plugin to /usr/local/bin
make test               # go test ./... -v
make lint               # golangci-lint run ./...
make fmt                # go fmt ./...
make container          # Build validator container (Dockerfile.dev)
make container-rdma     # Build tools container (tools/Dockerfile.dev)

Run a single test:

go test ./pkg/checks/rdma/ -run TestParseLoopbackBWOutput -v

Architecture

Two Execution Modes

The binary runs in two modes controlled by subcommands:

1. Controller mode (gpu, network, rdma, all, etc.): Runs on the user's machine. Creates K8s namespace, RBAC, deploys Jobs to GPU nodes, collects results from pod logs (JSON), prints report, cleans up. Orchestrated by pkg/controller/controller.go.

2. Agent mode (run — hidden subcommand): Runs inside per-node Job pods. Executes checks directly (nvidia-smi injected by GPU runtime, sysfs read via privileged mode), outputs JSON report to stdout (progress to stderr). The controller parses JSON from pod logs. Orchestrated by pkg/runner/runner.go.

Key Interfaces

• checks.Check (pkg/checks/check.go): Per-node check. Returns checks.Result with Status (PASS/WARN/FAIL/SKIP). Implementations live in pkg/checks/gpu/, pkg/checks/rdma/, pkg/checks/networking/, pkg/checks/crd/, pkg/checks/operator/.