Skip to content

NO-ISSUE: Add AGENTS.md and AI convention files #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
amir-yogev-gh wants to merge 2 commits into
base: main
Choose a base branch
from
Open

NO-ISSUE: Add AGENTS.md and AI convention files #14

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea485a6
NO-ISSUE: Add AGENTS.md, CLAUDE.md, and Copilot instructions
amir-yogev-gh Jun 15, 2026
9778370
NO-ISSUE: Remove copilot-instructions.md from this PR
amir-yogev-gh Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 97 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# host-management-openstack

Kubernetes controller that manages bare metal hosts via OpenStack Ironic. Watches HostLease CRs (defined in bare-metal-fulfillment-operator) and reconciles power state with Ironic nodes.

@coderabbitai coderabbitai Bot Jun 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Hyphenate "bare-metal" as compound adjective.

"Bare metal" modifies "hosts" and should be hyphenated: "bare-metal hosts."

🧰 Tools
🪛 LanguageTool

[uncategorized] ~3-~3: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...ack Kubernetes controller that manages bare metal hosts via OpenStack Ironic. Watches Hos...

(EN_COMPOUND_ADJECTIVE_INTERNAL)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` at line 3, Update the short project description to use the
compound adjective “bare-metal hosts” instead of “bare metal hosts.” This is a
wording fix in the AGENTS.md summary text; adjust the description so the
modifier before “hosts” is hyphenated consistently.


## Critical Rules

- **Always `make manifests generate`** after modifying CRD-consuming types
- **Always `make lint`** before committing — fix all golangci-lint issues
- **Never edit** `config/crd/` or `zz_generated.deepcopy.go` — these are generated
- Run `make lint test` before committing

## Dev Environment

```bash
make build # Build manager binary to bin/manager
make test # Unit tests (excludes e2e)
make test-e2e # E2E tests with Kind cluster
make lint # golangci-lint
make lint-fix # Auto-fix lint issues
make fmt # go fmt
make vet # go vet

make manifests # Generate RBAC manifests
make generate # Generate DeepCopy methods

make run # Run controller locally
make install # Install CRDs into cluster
make deploy IMG=<registry>/host-management-openstack:tag
make undeploy

make image-build IMG=<registry>/host-management-openstack:tag
make image-push IMG=<registry>/host-management-openstack:tag

# Pre-commit hooks
pre-commit run --all-files
```

## Repository Structure

```text
host-management-openstack/
├── cmd/
│ └── main.go # Controller entry point
├── internal/
│ ├── controller/ # HostLease reconciliation logic
│ └── management/ # OpenStack Ironic client
├── config/
│ ├── default/ # Kustomize default overlay
│ ├── manager/ # Manager deployment manifest
│ ├── rbac/ # Generated RBAC rules
│ └── samples/ # Example HostLease CRs
├── test/
│ ├── e2e/ # End-to-end tests
│ └── utils/ # Test utilities
├── hack/ # Boilerplate and helper scripts
├── Makefile # Build, test, lint, deploy targets
├── go.mod # Go 1.26, controller-runtime, gophercloud
└── .golangci.yml # Linter configuration
```

## Architecture

Single controller watching HostLease CRs:

```text
HostLease CR (spec.poweredOn: true/false)
↓ (reconcile)
HostLease Controller
↓ (OpenStack API)
Ironic Node (power state)
```

- **HostLease types** are defined in `bare-metal-fulfillment-operator/api/v1alpha1/` — this repo consumes them
- **Management client** (`internal/management/`) abstracts OpenStack Ironic interactions via gophercloud
- Controller syncs `spec.poweredOn` with Ironic node power state, requeues on interval for drift detection
- Handles auth reconnection on token expiry

### Key Files

| File | Purpose |
|------|---------|
| `internal/controller/hostlease_controller.go` | Reconciliation logic |
| `internal/controller/hostlease_names.go` | Naming helpers |
| `internal/management/client.go` | Management client interface |
| `internal/management/openstack.go` | OpenStack Ironic implementation |

## CI

GitHub Actions (`.github/workflows/`):
- **build-image.yaml** — runs tests, builds + pushes container image and manifests
- **pre-commit.yaml** — pre-commit hooks + golangci-lint on PRs

## Code Quality

- **golangci-lint** with dupl, errcheck, ginkgolinter, goconst, gocyclo, revive, staticcheck, and more (see `.golangci.yml`)
- **Pre-commit hooks**: trailing-whitespace, yamllint (strict, excludes `config/`), golangci-lint
- **Tests**: Ginkgo v2 + Gomega with envtest