Skip to content

CLAUDE.md

Latest commit

 

History

History
257 lines (205 loc) · 11.4 KB

CLAUDE.md

File metadata and controls

257 lines (205 loc) · 11.4 KB
Raw

CLAUDE.md

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

Development Commands

Building

# Build for current platform
go build -tags containers_image_openpgp -ldflags="-w -s" ./...

# Build for specific platforms (as used in CI)
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -tags containers_image_openpgp -ldflags="-w -s" -o linux-amd64/ ./...
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -tags containers_image_openpgp -ldflags="-w -s" -o darwin-apple-silicon/ ./...

Testing

# Run full test suite (requires podman/docker and Kubernetes cluster)
# Note: CGO_ENABLED=0 to avoid NVML deprecation warnings breaking test formatters
CGO_ENABLED=0 go test -tags containers_image_openpgp -json -v -coverprofile=coverage.out ./...

# Generate coverage report
go tool cover -func coverage.out

Code Quality

# Run security scanner
gosec --exclude G402 ./...

# Run static code analyzer  
staticcheck -checks all ./...

Dependencies

  • Requires Go 1.23.3+
  • Requires either Podman or Docker runtime installed
  • Tests require a Kubernetes cluster (kind is used in CI)
  • On Ubuntu: sudo apt-get install podman libbtrfs-dev nodejs wamerican libgpgme-dev

Architecture Overview

Core Components

Entry Point (main.go)

  • Initializes configuration from pkg/config/config.json
  • Detects container runtime (Podman/Docker) via utils.DetectContainerRuntime
  • Creates scenario orchestrator and provider factory instances
  • Delegates to Cobra CLI commands in cmd/

Configuration System (pkg/config/)

  • config.json: Central configuration with container registries, API endpoints, paths
  • config.go: Configuration struct and loading logic with embedded JSON file

CLI Commands (cmd/)

  • root.go: Main command structure with subcommands and global flags
  • Individual command files: run.go, list.go, describe.go, clean.go, etc.
  • Support for private registry authentication via flags or environment variables

Provider System (pkg/provider/)

  • factory/: Factory pattern for different container registry providers
  • quay/: Quay.io registry implementation
  • registryv2/: Generic Docker Registry v2 API support
  • models/: Data structures for registry interactions

Scenario Orchestrator (pkg/scenarioorchestrator/)

  • Abstracts container runtime operations (Podman/Docker)
  • podman/: Podman-specific implementation
  • Manages chaos scenario container lifecycle

Utility Packages

  • pkg/utils/: Common utilities and helpers
  • pkg/typing/: Type definitions and validation
  • pkg/dependencygraph/: Dependency graph management for scenario workflows
  • pkg/randomgraph/: Random scenario generation

Key Features

Scenario Management

  • List available chaos scenarios from container registries
  • Describe scenario details and input requirements
  • Run individual scenarios or orchestrated workflows
  • Support for detached execution mode

Graph Workflows

  • Define dependency graphs of chaos scenarios in JSON format
  • Execute scenarios in dependency order
  • Support for parallel execution where dependencies allow
  • Scaffold new workflow templates

Random Testing

  • Generate random scenario execution plans
  • Control parallelism and scenario count
  • Use seed files for template-based random generation

Private Registry Support

  • Basic authentication and token-based authentication
  • Custom domain support beyond quay.io
  • TLS configuration options

Container Runtime Integration

The tool auto-detects and supports both Podman and Docker:

  • Podman: Uses socket communication via unix:// sockets
  • Docker: Standard Docker socket integration
  • Platform detection for Darwin vs Linux socket paths
  • Graceful fallback between runtimes

Configuration Patterns

  • Global configuration embedded in binary via go:embed
  • Runtime configuration via CLI flags and environment variables
  • Kubeconfig path resolution for Kubernetes integration
  • Custom alerts and metrics profile support

Lightspeed AI-Powered Assistance

Overview

Lightspeed is krknctl's AI-powered chaos engineering assistance feature that provides intelligent command suggestions and documentation search using Retrieval-Augmented Generation (RAG) with GPU acceleration.

Major Implementation Tasks Completed

1. GPU Detection System

NVIDIA Compute Capability Detection: Uses NVML (NVIDIA Management Library) to detect GPU type

  • macOS arm64: Automatically uses Apple Silicon GPU support (Metal via libkrun)
  • Linux with NVIDIA GPU: Queries compute capability via NVML to select optimal container
    • Consumer GPUs (compute capability 7.5, 8.6, 8.9): RTX 20xx/30xx/40xx, GTX 1660 series → nvidia-consumer image
    • Datacenter GPUs (compute capability 7.0, 8.0, 9.0): V100, A100, H100, DGX series → nvidia-datacenter image
    • Detection failure: Graceful fallback to cpu image with warning
  • Generic fallback: CPU-only mode for all other platforms
  • Added --no-gpu flag to force CPU-only mode without device mounting

GPU Detection Flow:

  1. Platform detection: macOS arm64 → Apple Silicon
  2. Linux: Check for NVIDIA device files (/dev/nvidia0, /dev/nvidiactl, /dev/nvidia-uvm)
  3. NVML initialization and compute capability query
  4. Map compute capability to consumer/datacenter GPU type
  5. Automatic fallback to CPU mode if NVML unavailable (drivers not installed)

2. Container Runtime Support

  • Cross-Platform Support: Lightspeed supports both Podman and Docker container runtimes
    • macOS arm64: Requires Podman for Apple Silicon GPU support via libkrun/Vulkan
    • Linux: Works with both Podman (CDI) and Docker (--gpus) for NVIDIA GPUs
  • GPU Device Mounting:
    • Podman: Uses CDI (Container Device Interface) nvidia.com/gpu=all specification
    • Docker: Uses DeviceRequest API with --gpus all semantics
  • Unified API: PodmanCreateOptions.GPURequest field works across both runtimes

3. Container Architecture

Four Specialized Containers:

  • Apple Silicon (krknctl-assist:apple-silicon): Vulkan backend for Apple M1/M2/M3/M4 GPUs (linux/arm64)
  • NVIDIA Consumer (krknctl-assist:nvidia-consumer): CUDA backend for consumer GPUs - arch 75, 86, 89 (linux/amd64, linux/arm64)
  • NVIDIA Datacenter (krknctl-assist:nvidia-datacenter): CUDA backend for datacenter GPUs - arch 70, 80, 90 (linux/amd64, linux/arm64)
  • CPU (krknctl-assist:cpu): CPU-only fallback for all other platforms (linux/amd64, linux/arm64)

Container Selection Logic:

  • Uses gpudetect.DetectGPU() to query GPU type via NVML
  • Config methods GetAssistImageURI() and GetAssistImageURIWithRegistry() select appropriate tag
  • Device mounting in pkg/assist/assist.go based on detected GPU type

4. Configuration Integration

  • Config-Based Tags: Uses GPU-specific tags from pkg/config/config.json:
    • assist_model_tag_apple: "apple-silicon"
    • assist_model_tag_nvidia_consumer: "nvidia-consumer"
    • assist_model_tag_nvidia_datacenter: "nvidia-datacenter"
    • assist_model_tag_cpu: "cpu"
  • Centralized Settings: All assist service parameters (ports, endpoints, timeouts) in configuration
  • Private Registry Support: Full integration with existing private registry authentication

5. Multi-Stage Container Build Fix

Problem: Documentation indexing failed in builder stage of multi-stage builds

  • Root Cause: Git and Python dependencies not fully available during builder stage
  • Solution: Moved documentation indexing from builder stage to runtime stage
  • Impact: Fixed NVIDIA and Generic containers (Apple single-stage already worked)

Fixed Containers:

  • NVIDIA (Containerfile.nvidia): Multi-stage build with runtime indexing
  • Generic (Containerfile.generic): Multi-stage build with runtime indexing
  • Apple Silicon (Containerfile.apple-silicon): Single-stage build (already working)

6. Documentation Indexing System

Sources Indexed:

  • Local krknctl help documentation
  • Live krkn-chaos/website repository (chaos engineering guides)
  • Live krkn-chaos/krkn-hub repository (scenario definitions)

Indexing Process:

  • Build Time: Creates cached indices for offline/airgapped environments
  • Runtime: Can rebuild indices with fresh documentation or use cached versions
  • Verification: Automatic validation of indexed document sources and counts

7. User Experience Improvements

Progress Feedback:

  • Spinner with dynamic progress messages during container image pulls
  • Real-time feedback during RAG model deployment
  • Health checking with automatic retry and timeout handling

Error Handling:

  • Platform-specific error messages with actionable solutions
  • Automatic fallback from live indexing to cached documentation
  • Container cleanup on deployment failures

Technical Implementation

Core Components

  • pkg/gpudetect/detector.go: NVML-based GPU detection with compute capability mapping
  • cmd/assist.go: Assist commands with GPU-aware container deployment (Podman-only on macOS arm64)
  • pkg/config/config.go: Enhanced with GPU-specific tag selection methods
  • pkg/assist/assist.go: Container deployment with unified GPU device mounting
  • pkg/scenarioorchestrator/scenario_orchestrator.go: Unified PodmanCreateOptions.GPURequest field
  • pkg/scenarioorchestrator/podman/: CDI device support for NVIDIA GPUs
  • pkg/scenarioorchestrator/docker/: DeviceRequest API support for NVIDIA GPUs

Container Files

  • containers/assist/Containerfile.apple-silicon: Single-stage Vulkan build for Apple Silicon
  • containers/assist/Containerfile.nvidia-consumer: Multi-stage CUDA build (arch 75, 86, 89)
  • containers/assist/Containerfile.nvidia-datacenter: Multi-stage CUDA build (arch 70, 80, 90)
  • containers/assist/Containerfile.cpu: Multi-stage CPU-only build

Key Functions

  • gpudetect.DetectGPU(): NVML-based GPU type detection with graceful fallback
  • gpudetect.detectNvidiaGPUType(): CUDA compute capability query and mapping
  • gpudetect.mapComputeCapability(): Maps compute capability to consumer/datacenter
  • config.GetAssistImageURI(): GPU-aware image URI selection
  • assist.DeployAssistModel(): GPU-aware container deployment with unified GPU mounting
  • podmanCreateViaCLI(): Handles both CDI devices and legacy device mounts for Podman
  • docker.Run(): Implements DeviceRequest for Docker --gpus support

NVIDIA Detection Requirements

  • NVIDIA Drivers: Must be installed on host (same requirement as using NVIDIA GPUs)
  • NVML Library: Accessed via github.com/NVIDIA/go-nvml Go bindings
  • No Container Dependencies: Detection runs on host before container launch
  • Graceful Degradation: Falls back to CPU mode if NVML initialization fails

Usage Examples

# Automatic GPU detection and deployment
krknctl assist check

# AI-powered assistance with auto-detected GPU
krknctl assist run

# Force CPU-only mode (no GPU acceleration)
krknctl assist run --no-gpu

# Offline mode for airgapped environments  
krknctl assist run --offline

Development Notes

  • Testing: Updated test suite to use new PlatformGPUDetector API
  • Backwards Compatibility: Maintains existing CLI interface while simplifying internals
  • Build System: All containers build successfully with proper documentation indexing
  • Error Recovery: Graceful degradation when GPU features are unavailable