Skip to content

AGENTS.md

Latest commit

 

History

History
179 lines (131 loc) · 6.28 KB

AGENTS.md

File metadata and controls

179 lines (131 loc) · 6.28 KB

TopoLVM AI Assistant Context

This file configures AI assistants to work effectively with the TopoLVM codebase.

How This Works

When you use AI assistance on this project, the AI reads this file to understand:

  • Where to find documentation
  • Which files are auto-generated (do not edit)
  • Common development workflows
  • Testing requirements and conventions

Quick Reference - Where to Find Information

Before making changes, always reference the canonical documentation:

Project Overview

  • Language: Go 1.24.0
  • Framework: Kubernetes controller-runtime
  • Type: CSI (Container Storage Interface) plugin for Kubernetes using LVM
  • License: LICENSE

Development Commands

Essential Commands

# Setup development environment (run once)
make setup

# Run tests and linting before committing
make test

# Fix linting issues automatically
make lint-fix

# Generate code after modifying API types or protobuf
make generate

# Verify no uncommitted generated files (CI check)
make check-uncommitted

# Build binaries
make build

# Build Docker images
make image

E2E Testing

See test/e2e/README.md for detailed E2E testing instructions.

AI-Specific Guidance

DO NOT Edit These Auto-Generated Files

These files are generated by make generate - NEVER edit manually:

  • api/v1/zz_generated.deepcopy.go (generated from API types)
  • api/legacy/v1/* (generated from api/v1)
  • pkg/lvmd/proto/lvmd.pb.go (generated from .proto)
  • pkg/lvmd/proto/lvmd_grpc.pb.go (generated from .proto)
  • docs/lvmd-protocol.md (generated from .proto)
  • config/**/*.yaml (generated controller gen)
  • charts/topolvm/templates/crds/*.yaml (generated from API types)
  • charts/topolvm/README.md (generated by make generate-helm-docs)

Always run make generate after modifying:

  • API types in api/v1/*_types.go
  • Protobuf definitions in pkg/lvmd/proto/lvmd.proto
  • Helm chart values or templates

Code Generation Workflow

# 1. Edit source files (API types or protobuf)
vim api/v1/logicalvolume_types.go

# 2. Generate derived code
make generate

# 3. Verify changes
git diff

# 4. Commit both source and generated files
git add api/v1/logicalvolume_types.go api/v1/zz_generated.deepcopy.go config/crd/
git commit -s -m "Add new field to LogicalVolume CRD"

Common Pitfalls for AI Assistants

  1. Don't guess file locations: Use Grep/Glob tools to find files rather than assuming paths
  2. Read design.md first: Before implementing features, understand the architecture in docs/design.md
  3. Check existing tests: Look at *_test.go files for patterns before writing new tests
  4. Follow gRPC patterns: When modifying lvmd protocol, study existing RPC patterns in pkg/lvmd/proto/lvmd.proto
  5. Kubernetes controller patterns: This project uses controller-runtime - study existing controllers in internal/

Testing Requirements

  • Add tests for new features (use Ginkgo/Gomega framework)
  • Ensure tests pass with -race flag (checked by CI)
  • Update e2e tests for user-facing changes
  • Test both thin and thick provisioning modes when relevant

Git Workflow

  • Sign all commits: Use git commit -s (DCO requirement)
  • PR checklist:
    1. Run make test locally
    2. Run make generate if you modified API types or protobuf
    3. Run make check-uncommitted to verify generated files are committed
    4. Ensure all commits are signed

Project Structure

topolvm/
├── api/v1/              # Kubernetes API types (source of truth for CRDs)
├── cmd/                 # Main binaries (hypertopolvm, lvmd)
├── internal/            # Internal packages (controllers, drivers)
├── pkg/lvmd/proto/      # gRPC protocol definitions
├── charts/topolvm/      # Helm chart
├── docs/                # Documentation (READ THESE FIRST)
├── test/e2e/           # End-to-end test suite
└── Makefile            # Build automation

Security Considerations

When implementing features, avoid:

  • Command injection (sanitize inputs to LVM commands)
  • Path traversal (validate volume names, device paths)
  • Privilege escalation (lvmd runs privileged - be extra careful)
  • Resource exhaustion (validate size limits, quota enforcement)

Understanding Key Flows

Before diving into TopoLVM-specific operations, refer to the mechanism and spec of the Kubernetes CSI driver.

For implementation tasks, study these workflows in docs/design.md:

  1. Dynamic Provisioning (11 steps): PVC → LogicalVolume CRD → LVM volume creation
  2. Volume Expansion (9 steps): PVC resize → LV resize → filesystem resize
  3. Snapshot Creation: Only works with thin provisioning (see docs/snapshot-and-restore.md)

When Stuck

  1. Search existing code: grep -r "pattern" . or use Grep tool
  2. Check docs/faq.md for common issues
  3. Look at test files for usage examples: find . -name "*_test.go" -exec grep -l "pattern" {} \;
  4. Review recent PRs for similar changes: gh pr list --state merged --limit 20

Contributing

See CONTRIBUTING.md for full contribution guidelines.

Key points:

  • All commits must be signed with DCO (git commit -s)
  • Follow Go code style (gofmt -s)
  • Pass all linters (golangci-lint, go vet)
  • Add tests for new functionality