Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (76 loc) · 3.56 KB

AGENTS.md

File metadata and controls

108 lines (76 loc) · 3.56 KB

Cluster API Provider Metal3 (CAPM3) - AI Agent Instructions

Instructions for AI coding agents. For project overview, see README.md. For contribution guidelines, see CONTRIBUTING.md.

Repository Structure

Directory Purpose
api/v1beta1/ CRD types (Metal3Cluster, Metal3Machine, Metal3Data, etc.) - separate Go module
controllers/ Reconciliation logic
baremetal/ BareMetalHost integration logic
internal/webhooks/ Validation/defaulting webhooks
config/ Kustomize manifests (CRDs, RBAC, webhooks) - auto-generated by make generate, rarely edit directly
hack/ CI scripts (prefer Make targets locally)
test/e2e/ E2E test suite (central for Metal3 ecosystem)

Testing Standards

CI is managed by Prow. Run these locally before submitting PRs:

Make targets:

Command Purpose
make test Full verification (generate + lint + unit)
make generate Regenerate code (DeepCopy, CRDs, RBAC, mocks)
make unit Unit tests (requires envtest - do not use go test directly)
make lint Go linting via golangci-lint (all modules)
make verify-boilerplate Check license headers
make modules Verify go.mod is tidy

Hack scripts (auto-containerized, match CI exactly):

Script Purpose
./hack/shellcheck.sh Shell script linting (shellcheck)
./hack/markdownlint.sh Markdown linting (config: .markdownlint-cli2.yaml)
./hack/manifestlint.sh Kubernetes manifest validation (kubeconform)

Code Conventions

  • Go: Linting rules in .golangci.yaml, license headers in hack/boilerplate/
  • Shell: Use set -o errexit -o nounset -o pipefail
  • Markdown: 3-space indent for lists (.markdownlint-cli2.yaml)

Key Workflows

Modifying APIs

  1. Edit api/v1beta1/*_types.go
  2. Run make generate
  3. Update webhooks in internal/webhooks/ if validation changes
  4. Run make test

E2E Testing

CAPM3 is the central E2E test hub for the Metal3 ecosystem (validates CAPM3, IPAM, BMO, Ironic).

Command Purpose
make test-e2e Run E2E tests (requires metal3-dev-env)
GINKGO_FOCUS="basic" ./scripts/ci-e2e.sh Run specific scenario

Key files:

  • test/e2e/config/e2e_conf.yaml - Provider versions and test config
  • test/e2e/data/infrastructure-metal3/ - Cluster templates per version
  • scripts/ci-e2e.sh - Main orchestration script

Code Review Guidelines

When reviewing pull requests:

  1. Security - Hardcoded secrets, unpinned dependencies, missing input validation
  2. Test coverage - New functionality should have tests
  3. Consistency - Match existing patterns in the codebase
  4. Breaking changes - Flag API/behavior changes affecting users

Focus on: controllers/, baremetal/, api/, internal/webhooks/.

AI Agent Guidelines

Before Changes

  1. Run make unit to verify baseline
  2. Check patterns in similar existing files

When Making Changes

  1. Make minimal, surgical edits
  2. Run make generate after API changes
  3. Run make test before committing
  4. Add tests for new functionality

Security Requirements

  • Pin external dependencies by SHA (containers, GitHub Actions, binaries)
  • No hardcoded credentials
  • Validate all inputs

Related Documentation