Skip to content

AGENTS.md

Latest commit

 

History

History
106 lines (75 loc) · 3.71 KB

AGENTS.md

File metadata and controls

106 lines (75 loc) · 3.71 KB

Metal3 Baremetal Operator (BMO) - AI Agent Instructions

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

Repository Structure

Directory Purpose
apis/metal3.io/v1alpha1/ CRD types (BareMetalHost, HostFirmwareSettings, etc.) - separate Go module
internal/controller/metal3.io/ Reconciliation logic with state machine
internal/webhooks/metal3.io/ Validation/defaulting webhooks
pkg/provisioner/ Provisioner interface (ironic, fixture, demo)
pkg/hardwareutils/ BMC protocol handling - separate Go module
config/ Kustomize manifests (CRDs, RBAC, webhooks) - auto-generated by make manifests, rarely edit directly
hack/ CI scripts (prefer Make targets locally)
test/e2e/ E2E tests with libvirt VMs

Testing Standards

CI uses GitHub Actions (.github/workflows/) and Prow. Run these locally before submitting PRs:

Make targets:

Command Purpose
make test Full verification (generate + lint + unit)
make generate Regenerate Go code (deepcopy functions)
make manifests Regenerate CRDs, RBAC, webhooks
make unit Unit tests (requires envtest - do not use go test directly)
make lint Go linting via golangci-lint (all modules)
make mod 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.go.txt
  • Shell: Use set -o errexit -o nounset -o pipefail
  • Markdown: 3-space indent for lists (.markdownlint-cli2.yaml)

Key Workflows

Modifying APIs

  1. Edit apis/metal3.io/v1alpha1/*_types.go
  2. Run make generate manifests
  3. Update webhooks in internal/webhooks/ if validation changes
  4. Run make test

E2E Testing

BMO has standalone E2E tests using libvirt VMs and BMC emulators:

Command Purpose
./hack/ci-e2e.sh Full E2E suite (requires libvirt, docker)
GINKGO_FOCUS="inspection" ./hack/ci-e2e.sh Run specific test
BMC_PROTOCOL=ipmi ./hack/ci-e2e.sh Test with IPMI protocol

Key files: test/e2e/config/ironic.yaml, test/e2e/config/fixture.yaml

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: internal/controller/, pkg/provisioner/, apis/, 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 manifests 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