Imported from metal3-io/ironic-standalone-operator (
AGENTS.md). Install upstream withnpx skills add metal3-io/ironic-standalone-operator. Copyright stays with the author.
Ironic Standalone Operator (IrSO) - 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 (Ironic) - separate Go module |
internal/controller/ |
Reconciliation logic |
internal/webhook/ |
Validation webhooks |
pkg/ironic/ |
Core Ironic deployment logic |
config/ |
Kustomize manifests (CRDs, RBAC, webhooks) - auto-generated by make manifests, rarely edit directly |
hack/ |
CI scripts (prefer Make targets locally) |
test/ |
Functional tests - separate Go module |
Testing Standards
CI uses GitHub Actions (.github/workflows/).
Run these locally before submitting PRs:
Make targets:
| Command | Purpose |
|---|---|
make test |
Full verification (generate + fmt + vet + unit) |
make generate |
Regenerate DeepCopy methods |
make manifests |
Regenerate CRDs, RBAC, webhooks, API docs |
make lint |
Go linting via golangci-lint (all modules) |
make lint-fix |
Run golangci-lint auto-fixers (all modules) |
make modules |
Verify go.mod is tidy (all 3 modules) |
Hack scripts (auto-containerized, match CI exactly):
| Script | Purpose |
|---|---|
./hack/markdownlint.sh |
Markdown linting (config: .markdownlint-cli2.yaml) |
./hack/manifestlint.sh |
Kubernetes manifest validation (kubeconform) |
./hack/shellcheck.sh |
Shell script linting (shellcheck) |
Container runtime: Scripts and make targets that uses a container runtime can be configured to use either podman or docker by setting
CONTAINER_RUNTIME. Check what is available in your environment and setCONTAINER_RUNTIMEaccordingly (e.g.make manifests CONTAINER_RUNTIME=docker).
Code Conventions
- Go: Linting rules in
.golangci.yaml, license headers inhack/boilerplate.go.txt - Shell: Use
set -eux - Markdown: Config in
.markdownlint-cli2.yaml
Key Workflows
Modifying APIs
- Edit
api/v1alpha1/*_types.go - Run
make generate manifests - Update webhooks in
internal/webhook/if validation changes - Run
make test
Functional Testing
IrSO has self-contained functional tests on Minikube/Kind:
| Command | Purpose |
|---|---|
./test/prepare.sh |
Prepare test environment |
./test/run.sh |
Run all functional tests |
LABEL_FILTER="tls" ./test/run.sh |
Run specific tests by label |
Test labels: no-params, tls, upgrade, ha, database, keepalived-dnsmasq
Code Review Guidelines
When reviewing pull requests:
- Security - Hardcoded secrets, unpinned dependencies, missing input validation
- Test coverage - New functionality should have tests
- Consistency - Match existing patterns in the codebase
- Breaking changes - Flag API/behavior changes affecting users
Focus on: internal/controller/, pkg/ironic/, api/, internal/webhook/.
AI Agent Guidelines
Before Changes
- Run
make testto verify baseline - Check patterns in similar existing files
When Making Changes
- Make minimal, surgical edits
- Run
make generate manifestsafter API changes - Add tests for new functionality
- Run
make lintandmake testbefore committing
Security Requirements
- Pin external dependencies by SHA (containers, GitHub Actions, binaries)
- No hardcoded credentials
- Validate all inputs