Skip to content

AGENTS.md

Latest commit

 

History

History
103 lines (72 loc) · 3.3 KB

AGENTS.md

File metadata and controls

103 lines (72 loc) · 3.3 KB

Metal3 IP Address Manager - 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/v1alpha1/ CRD types (IPPool, IPClaim, IPAddress) - separate Go module
controllers/ Reconciliation logic
ipam/ Core IP allocation algorithms
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)

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)

GitHub Actions (reusable workflows from project-infra):

Workflow Purpose
yamllint YAML linting (config: .yamllint.yaml)

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/v1alpha1/*_types.go
  2. Run make generate
  3. Update webhooks in internal/webhooks/ if validation changes
  4. Run make test

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/, ipam/, 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

E2E Testing

IPAM has no standalone e2e tests. E2E runs through CAPM3.

Related Documentation