lvm-operator

Imported from openshift/lvm-operator (AGENTS.md). Install upstream with npx skills add openshift/lvm-operator. Copyright stays with the author.

This file provides guidance to AI agents working with the LVM Operator repository. It is an index into deeper documentation — read the linked files for full details.

Repo Orientation

This is the LVM Operator, part of LVMS (Logical Volume Manager Storage) for OpenShift. It manages LVM volume groups on cluster nodes via a Kubernetes operator and the TopoLVM CSI driver. The operator and TopoLVM are compiled into a single binary for edge/single-node efficiency.

• README.md — what LVMS is, deployment, known limitations
• CONTRIBUTING.md — build commands, testing, commit conventions, AI attribution
• Official product documentation

Build Commands

• make build — compile the operator binary
• make test — run unit tests
• make docker-test — run unit tests inside a Linux container (useful for non-Linux hosts)
• make lint — run linters
• make verify — formatting and generated file checks
• make generate — update deepcopy methods after API type changes
• make manifests — regenerate CRD YAML and RBAC after API type changes
• make bundle — regenerate OLM bundle manifests
• make catalog — regenerate OLM catalog
• make e2e — run end-to-end tests (requires live cluster)

Documentation Index

Modifying CRDs

When changing API types in api/v1alpha1/, follow this sequence:

1. Edit the type definition in api/v1alpha1/*_types.go.
2. Add kubebuilder markers for validation, defaults, and documentation.
3. Run make generate to update deepcopy methods.
4. Run make manifests to regenerate CRD YAML and RBAC manifests.
5. Run make bundle && make catalog to regenerate OLM bundle and catalog.
6. Update or add controller logic to handle the new field.
7. Add unit tests for validation and controller behavior.
8. Add e2e tests if the change affects user workflows.

Validation Markers

Use kubebuilder markers to express validation constraints. All constraints must be documented in the field's godoc comment:

// +optional
// +kubebuilder:validation:Optional
// +kubebuilder:validation:MinItems=1
Paths []string `json:"paths,omitempty"`

API Version Policy

• Current production API: v1alpha1 (the name is historical — treat as stable).
• New fields should be optional to maintain backward compatibility.
• Breaking changes require migration support and careful review.

Boundaries

This operator manages physical storage. Mistakes destroy data. See docs/core-beliefs.md for non-negotiable invariants and docs/conventions/ for implementation patterns.

Always do:

• Run make generate && make manifests after changing api/v1alpha1/ types
• Run make bundle && make catalog after any change that affects CRDs, RBAC, config, or monitoring
• Run make verify before considering work complete
• Use pointer types (*StructType) for optional API fields
• Treat nil as "upgraded from before this field existed"

Ask first:

• Adding new dependencies to go.mod
• Modifying webhook validation logic
• Changing device selector behavior
• Any schema migration or breaking API change

Never do:

• Edit generated files: zz_generated*.go, config/crd/bases/, vendor/
• Run destructive LVM commands: wipefs, vgremove, pvremove, lvremove, mkfs, dd
• Skip finalizer logic — three-level hierarchy prevents orphaned storage. See docs/architecture.md
• Commit secrets, credentials, or personal registry references

Key architecture facts:

• VG Manager runs as a privileged DaemonSet and executes LVM commands (vgcreate, vgextend, lvcreate, wipefs) directly on nodes
• VG Manager requeue interval depends on configuration, in precedence order: RAID: 60s for health monitoring; explicit device paths (any policy) or Static: no periodic requeue; Dynamic discovery without explicit paths: 30s; after VG creation/extension: always requeue (verification step). See determineFinishedRequeue in internal/controllers/vgmanager/controller.go. Controllers must handle partial states and retries safely (idempotency)
• Data loss from incorrect device selection is unrecoverable — verify device selectors carefully in tests

Path-Scoped Guidance

Claude Code loads context-specific rules when you touch files in these areas:

Agent Skills

Reusable multi-step workflows invocable as slash commands:

Cross-Tool Compatibility

This repo provides instruction files for multiple AI coding tools:

• Claude Code: CLAUDE.md → AGENTS.md, .claude/settings.json, .claude/rules/, .claude/commands/
• GitHub Copilot: .github/copilot-instructions.md, .github/instructions/
• Cursor: .cursor/rules/lvms.mdc

Testing

Unit tests use Ginkgo/Gomega and are located alongside source files. E2E tests are in test/e2e/ and require a live cluster with available block devices. See CONTRIBUTING.md for build, deploy, and test commands. See docs/conventions/testing.md for testing conventions.

Key Directories