client-go2/CLAUDE.md

CLAUDE.md

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

Repository Overview

client-go2 is an experimental Go library that provides type-safe, generic Kubernetes client operations without code generation. It wraps k8s.io/client-go/rest using Go generics to provide strongly-typed CRUD operations and informers.

Commands

Build and Test

# Build all packages
go build ./...

# Run unit tests with race detection
go test ./generic -v -race

# Run a specific test
go test ./generic -v -run TestNewClientGVR

# Run e2e tests (requires Kubernetes cluster)
kind create cluster  # If not already running
go test ./generic -v -tags=e2e

# Run the example/demo
go run ./main.go

Code Quality

# Format code
gofmt -s -w .

# Run go vet
go vet ./...

# Ensure dependencies are tidy
go mod tidy

CI/CD Verification (what runs in GitHub Actions)

go build ./...
go vet ./...
test -z "$(gofmt -l .)" || (gofmt -l . && exit 1)
go mod tidy && git diff --exit-code go.mod go.sum
go test ./generic -v -race
# Then e2e tests with Kind cluster

Architecture

Core Design

The library uses Go generics with type parameter [T runtime.Object] to provide compile-time type safety. There are two ways to create clients:

1. Automatic GVR inference (preferred): generic.NewClient[*corev1.Pod](config)

   • Uses Kubernetes scheme and discovery to infer GroupVersionResource from the Go type
   • Works for all types registered in the global scheme

2. Manual GVR specification: generic.NewClientGVR[*corev1.Pod](gvr, config)

   • For custom resources or when you need explicit control over the GVR

Key Components

• generic/client.go: Core client implementation with CRUD operations (List, Get, Create, Update, Delete, Patch)
• generic/informer.go: Type-safe informer implementation for watching resources
• generic/client_test.go: Unit tests with REST client mocking
• generic/e2e_test.go: Integration tests that require a real Kubernetes cluster

Testing Approach

• Unit tests use a custom mockTransport that implements http.RoundTripper
• Mock responses are set up per HTTP method and path combination
• E2e tests create real resources in a Kind cluster and verify operations

Important Rules

1. NEVER skip tests using t.Skip - If a test is failing, fix it rather than skipping
2. When comparing structs in tests, use github.com/google/go-cmp/cmp.Diff for better error messages
3. Follow the existing code style - inline struct initialization, single-line error checks where appropriate
4. The library requires Go 1.22.0+ due to generic constraints