Skip to content

CLAUDE.md

Latest commit

 

History

History
103 lines (72 loc) · 3.68 KB

CLAUDE.md

File metadata and controls

103 lines (72 loc) · 3.68 KB

CLAUDE.md

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

Project Overview

This is a Kubernetes operator for the Inference Gateway project, built using Go 1.24+ and the Operator SDK. The operator manages Gateway, A2A (Agent-to-Agent), and MCP (Model Context Protocol) custom resources in Kubernetes clusters.

Development Commands

All commands use the Task runner. Common development tasks:

  • task build - Build the manager binary (includes manifests, generate, fmt, vet)
  • task test - Run unit tests with coverage
  • task test:e2e - Run end-to-end tests (requires k3d cluster)
  • task test:e2e:focus FOCUS="test name" - Run specific e2e test
  • task lint - Run golangci-lint linter
  • task lint-fix - Run linter with automatic fixes
  • task fmt - Format Go code
  • task vet - Run go vet
  • task generate - Generate DeepCopy methods for API types
  • task manifests - Generate CRDs, RBAC, and installation manifests
  • task tidy - Run go mod tidy

Development Workflow

  1. task lint and task lint-fix - Ensure code quality
  2. task generate - Generate types (after schema changes)
  3. task manifests - Update Kubernetes manifests
  4. task fmt - Format code
  5. task build - Verify compilation
  6. task test - Run unit tests
  7. task test:e2e - Run e2e tests if applicable

Architecture

Custom Resources

  • Gateway (api/v1alpha1/gateway_types.go) - Core inference gateway deployment with AI provider integration, authentication, observability, and networking
  • Agent (api/v1alpha1/agent_types.go) - Agent-to-Agent communication servers
  • MCP (api/v1alpha1/mcp_types.go) - Model Context Protocol servers

Controllers

  • Gateway Controller (internal/controller/gateway_controller.go) - Manages Gateway deployments, services, configmaps, and HPA
  • Agent Controller (internal/controller/agent_controller.go) - Manages Agent server deployments
  • MCP Controller (internal/controller/mcp_controller.go) - Manages MCP server deployments

Key Directories

  • api/v1alpha1/ - API type definitions and generated code
  • internal/controller/ - Controller implementations and tests
  • config/ - Kubernetes manifests (CRDs, RBAC, deployments)
  • examples/ - Sample resource configurations
  • manifests/ - Generated installation manifests

Testing

Unit Tests

  • Use table-driven testing pattern
  • Each test case should have isolated mock dependencies
  • Run with task test (requires envtest setup)

E2E Tests

  • Located in test/e2e/
  • Requires k3d cluster managed by ctlptl
  • Uses Ginkgo testing framework
  • Run with task test:e2e or focused tests with task test:e2e:focus

Code Style Guidelines

  • Use early returns to avoid deep nesting
  • Prefer switch statements over if-else chains
  • Use table-driven testing
  • Code to interfaces for easier mocking
  • Use lowercase log messages
  • Maintain type safety with strong typing

Deployment

Local Development

  • task install - Install CRDs to cluster
  • task deploy - Build and deploy operator to k3d cluster
  • task undeploy - Remove operator from cluster
  • task uninstall - Remove CRDs from cluster

Cluster Management

  • task cluster:create - Create local k3d cluster with cert-manager and nginx-ingress
  • task cluster:delete - Delete local cluster

Generated Files

The following files are auto-generated and should not be edited manually:

  • api/v1alpha1/zz_generated.deepcopy.go - Generated by task generate
  • config/crd/bases/*.yaml - Generated by task manifests
  • manifests/*.yaml - Generated by task manifests

Always run task generate and task manifests after modifying API types or controller RBAC annotations.