diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6376c13 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,140 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- Aggregation logic for resource data ([#91](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/91)) +- Version subcommand to CLI ([#84](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/84)) +- Condition subfield queries for selective Sentinel polling ([#71](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/71)) +- Slice field validation in SliceFilter ([#78](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/78), [#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- Connection retry logic for database sidecar startup coordination ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- pgbouncer sidecar to Helm chart for connection pooling ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- Health check ping timeout configuration ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- Request-level context timeout to transaction middleware ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- Connection pool timeout configuration ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- PostgreSQL advisory locks for migration coordination in multi-replica deployments ([#72](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/72)) +- Search and filtering documentation ([#63](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/63)) +- Connection pool and pgbouncer documentation ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- HyperFleet API operator guide ([#76](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/76)) + +### Changed + +- Standardized appVersion and image.tag handling in Helm chart ([#90](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/90)) +- Aligned Helm chart with conventions standard ([#87](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/87)) +- Streamlined configuration system with Viper, removed getters and _FILE suffix pattern ([#75](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/75)) +- Used CHANGE_ME placeholder for image registry ([#83](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/83)) + +### Fixed + +- Validated adapter status conditions in handler layer ([#88](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/88)) +- Removed org prefix from image.repository default ([#86](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/86)) +- Addressed revive linter violations from enabled linting standard ([#85](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/85)) +- Truncated migrations table in CleanDB to ensure migrations re-run ([#72](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/72)) +- Added fallback default for AdvisoryLockTimeout ([#72](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/72)) +- Rejected not operator for condition queries ([#80](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/80)) +- SliceFilter star propagation in query processing ([#79](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/79)) +- Used 0.0.0-dev version for dev image builds ([#77](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/77)) +- Aligned health ping timeout with K8s probe timeout ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- Hardened pgbouncer config and health check responses ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) +- pgbouncer secret handling, connection leak, and lint ([#69](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/69)) + +## [0.1.1](https://github.com/openshift-hyperfleet/hyperfleet-api/compare/v0.1.0...v0.1.1) - 2026-03-09 + +### Added + +- Test suite for presenter package ([#64](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/64)) +- DatabaseConfig test coverage and improved advisory lock tests ([#72](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/72)) +- Prometheus metrics with `hyperfleet_db_` prefix to database layer ([#58](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/58)) + +### Changed + +- Updated copyright year to 2026 ([#58](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/58)) +- Renamed metrics to use `hyperfleet_api_` prefix for consistency ([#57](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/57)) +- Standardized Dockerfiles and Makefile for building images ([#59](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/59)) + +### Fixed + +- CA certificates missing in ubi9-micro runtime image ([#74](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/74)) +- VERSION collision with go-toolset base image ([#70](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/70)) +- Config file resolution broken by -trimpath build flag ([#66](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/66)) +- Enforced mandatory conditions in adapter status ([#60](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/60)) +- SliceFilter usage in handlers and time field handling ([#64](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/64)) +- Helm chart testing and default image registry ([#62](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/62)) +- Reset and re-seed buildInfoMetric in ResetMetricCollectors ([#57](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/57)) +- Rejected creation requests with missing spec field ([#56](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/56)) + +## [0.1.0](https://github.com/openshift-hyperfleet/hyperfleet-api/compare/c33867f...v0.1.0) - 2026-02-16 + +### Added + +- PodDisruptionBudget to Helm chart ([#44](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/44)) +- ServiceMonitor to Helm chart for Prometheus Operator integration ([#43](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/43)) +- YAML table format for adapter requirements ([#41](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/41)) +- Configurable adapter requirements ([#40](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/40)) +- Condition-based search with GIN index for improved query performance ([#39](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/39)) +- Health endpoints (`/healthz`, `/readyz`) and graceful shutdown ([#34](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/34)) +- User-friendly search syntax with lowercase Base32 ID encoding ([#16](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/16)) +- Schema validation for cluster and nodepool specifications ([#12](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/12)) +- Generation field for NodePool management ([#22](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/22)) +- OpenAPI schema embedded in Docker image for runtime validation ([#14](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/14)) +- Helm chart for Kubernetes deployment ([#16](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/16)) +- gomock/mockgen infrastructure for service mocks ([#10](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/10)) +- Bingo for Go tool dependency management ([#9](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/9)) +- Linux/amd64 platform support for container builds ([#17](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/17)) +- Integration tests for conditions ([#39](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/39)) +- Dynamic table discovery for test cleanup ([#32](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/32)) +- Operational runbook and metrics documentation ([#45](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/45)) +- ServiceMonitor configuration documentation ([#43](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/43)) +- Params constraints documentation ([#55](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/55)) + +### Changed + +- BREAKING CHANGE: Updated OpenAPI spec for conditions-based status model ([#39](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/39)) +- Aligned cluster and nodepool name validation with CS rules ([#48](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/48)) +- Implemented RFC 9457 Problem Details error model for standardized error responses ([#37](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/37)) +- Migrated to oapi-codegen for OpenAPI code generation ([#33](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/33)) +- Aligned logging with HyperFleet structured logging specification ([#31](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/31)) +- Integrated database logging with LOG_LEVEL ([#35](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/35)) +- Renamed Makefile binary target to build with output to bin/ ([#30](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/30)) +- Consolidated and streamlined documentation structure ([#21](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/21)) +- Configured rh-hooks-ai for AI-readiness and security compliance ([#18](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/18)) +- Migrated to HyperFleet v2 architecture ([#3](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/3)) + +### Removed + +- Phase validation from status types in favor of conditions-based model ([#39](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/39)) +- Generated mock files from git tracking ([#10](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/10)) +- Generated OpenAPI code from git tracking ([#3](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/3)) +- .claude directory from git tracking ([#45](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/45)) + +### Fixed + +- Prevented duplicate nodepool names within a cluster ([#53](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/53)) +- Returned 404 for non-existent cluster statuses ([#54](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/54)) +- First adapter status report now correctly initializes with Available=Unknown ([#52](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/52)) +- Integration tests updated to match new first-report behavior ([#52](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/52)) +- Added timeout to testcontainer teardown to prevent Prow hang ([#52](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/52)) +- Centralized adapter config to avoid duplicate logs ([#46](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/46)) +- Avoided exposing secret values in runbook ([#45](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/45)) +- Made adapter configuration mandatory ([#46](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/46)) +- Used explicit nil checks for PDB values ([#44](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/44)) +- Fixed goconst, gocritic, gosec, unparam and lll lint issues ([#42](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/42)) +- Prevented fmt.Sprintf panic when reason contains % without values ([#37](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/37)) +- Avoided leaking database error details to API clients ([#37](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/37)) +- Omitted empty Instance and TraceId from Problem Details JSON ([#37](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/37)) +- Added missing error codes to errorDefinitions map ([#37](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/37)) +- MVP phase logic to only return Ready or NotReady ([#9](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/9)) +- Cluster and nodepool name validation ([#16](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/16)) +- Silent error suppression ([#26](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/26)) +- Propagated JSON unmarshal errors ([#26](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/26)) +- Lint failures in presubmit jobs ([#12](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/12), [#6](https://github.com/openshift-hyperfleet/hyperfleet-api/pull/6)) + +### Security + +[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api/compare/v0.1.1...HEAD diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bdc54c6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,261 @@ +# Contributing to HyperFleet API + +## Development Setup + +Complete local environment setup for the HyperFleet API. + +```bash +# 1. Clone the repository +git clone https://github.com/openshift-hyperfleet/hyperfleet-api.git +cd hyperfleet-api + +# 2. Install prerequisites +# See PREREQUISITES.md for detailed installation instructions +# Required: Go 1.24+, Podman, PostgreSQL 13+, Make + +# 3. Generate OpenAPI code and mocks (REQUIRED FIRST STEP) +# Generated code is not checked into git +make generate-all + +# 4. Install dependencies +go mod download + +# 5. Initialize secrets directory +make secrets + +# 6. Setup local PostgreSQL database +make db/setup + +# 7. Build the project +make build + +# 8. Run database migrations +./bin/hyperfleet-api migrate + +# 9. Verify setup works +make test + +# 10. Start the server (without authentication for local development) +make run-no-auth +``` + +**First-time setup notes:** +- **Critical**: Run `make generate-all` before any other commands. Generated code is not in git. +- Tool versions are pinned using [Bingo](https://github.com/bwplotka/bingo) in the `.bingo/` directory +- The build uses FIPS-compliant crypto: `CGO_ENABLED=1 GOEXPERIMENT=boringcrypto` +- Local development runs without authentication by default (`make run-no-auth`) +- Integration tests automatically create isolated PostgreSQL containers via testcontainers + +## Repository Structure + +Overview of key directories and their purpose. + +``` +hyperfleet-api/ +├── cmd/hyperfleet-api/ # Application entry point and CLI commands +│ └── main.go # Server start, migrate, version commands +├── pkg/ +│ ├── api/ # Generated OpenAPI types (DO NOT EDIT) +│ │ └── openapi/ # Generated from openapi/openapi.yaml +│ ├── dao/ # Data access layer (database interactions) +│ ├── db/ # Database session factory, migrations, transaction middleware +│ ├── errors/ # RFC 9457 Problem Details error model +│ ├── handlers/ # HTTP request handlers using handlerConfig pipeline +│ ├── logger/ # Structured logging (slog-based) +│ ├── presenters/ # Response presenters (DAO models → API responses) +│ └── services/ # Business logic layer (status aggregation, validation) +├── plugins/ # Plugin-based route registration (clusters, nodepools) +│ ├── clusters/ # Cluster resource plugin +│ └── nodepools/ # NodePool resource plugin +├── openapi/ # API specification source +│ ├── openapi.yaml # Source spec (TypeSpec output, has $ref) +│ └── oapi-codegen.yaml # Code generation configuration +├── test/ +│ ├── factories/ # Test data factories +│ └── integration/ # Integration tests (testcontainers) +├── charts/ # Helm chart for Kubernetes deployment +├── docs/ # Detailed documentation +├── .bingo/ # Pinned tool versions (managed by Bingo) +├── Makefile # Build automation and common commands +└── CLAUDE.md # AI agent context (see also subdirectory CLAUDE.md files) +``` + +## Testing + +How to run unit tests, integration tests, linting, and validation. + +### Unit Tests +```bash +# Run all unit tests +make test + +# Run tests with coverage report +make test + +# Run unit tests in CI mode (JSON output) +make ci-test-unit +``` + +Unit tests run with `OCM_ENV=unit_testing` and do not require a running database. + +### Integration Tests +```bash +# Run integration tests +# These automatically create isolated PostgreSQL containers via testcontainers +make test-integration + +# Run integration tests in CI mode (JSON output) +make ci-test-integration +``` + +Integration tests use testcontainers to create isolated PostgreSQL instances. No manual database setup required. + +### Linting and Quality Checks +```bash +# Run all quality checks (fast - no database required) +make verify-all + +# Run only static analysis +make verify + +# Run golangci-lint +make lint + +# Run Helm chart linting +make test-helm + +# Run ALL checks (lint + unit + integration + helm) +make test-all +``` + +**Recommended workflow:** +- Use `make verify-all` for fast feedback during development (no database) +- Use `make test-all` for full validation before pushing + +## Common Development Tasks + +Build commands, running locally, generating code, and database operations. + +### Building +```bash +# Clean build (generates code, builds binary) +make build + +# Build all commands under cmd/ +make cmds + +# Clean temporary files +make clean + +# Install binary to GOPATH/bin +make install +``` + +### Running Locally +```bash +# Run with authentication disabled (local development) +make run-no-auth + +# Run with full authentication +make run + +# Access the API +curl http://localhost:8000/api/hyperfleet/v1/clusters | jq + +# Available endpoints: +# - REST API: http://localhost:8000/api/hyperfleet/v1/ +# - OpenAPI spec: http://localhost:8000/api/hyperfleet/v1/openapi +# - Swagger UI: http://localhost:8000/api/hyperfleet/v1/openapi.html +# - Health checks: http://localhost:8080/healthz, http://localhost:8080/readyz +# - Metrics: http://localhost:9090/metrics +``` + +### Code Generation +```bash +# Generate OpenAPI types from openapi/openapi.yaml +make generate + +# Generate mock implementations for services +make generate-mocks + +# Generate all code (OpenAPI + mocks) - REQUIRED after fresh clone +make generate-all + +# Update vendor directory (if using vendoring) +make generate-vendor +``` + +**Important:** Never edit files in `pkg/api/openapi/` or `*_mock.go` files. They are auto-generated. + +### Database Operations +```bash +# Setup local PostgreSQL container +make db/setup + +# Login to local PostgreSQL (psql) +make db/login + +# Run migrations +./bin/hyperfleet-api migrate + +# Teardown local PostgreSQL container +make db/teardown +``` + +### Container Images +```bash +# Build container image +make image + +# Build and push container image +make image-push + +# Build and push to personal Quay registry (requires QUAY_USER env var) +make image-dev +``` + +## Commit Standards + +Follow the HyperFleet commit message format and refer to the [architecture repository commit standards](https://github.com/openshift-hyperfleet/architecture). + +**Format:** `HYPERFLEET-### - type: description` + +**Example:** +``` +HYPERFLEET-123 - fix: handle nil pointer in status aggregation + +Add null check before accessing adapter status conditions. + +Co-Authored-By: Claude Sonnet 4.5 +``` + +**Types:** `feat`, `fix`, `docs`, `chore`, `test`, `refactor` + +**Co-author line:** Always include when pair programming or using AI assistance. + +## Release Process + +HyperFleet API uses semantic versioning and automated releases. + +### Versioning +- Version tags follow semver: `v0.1.0`, `v0.1.1`, `v0.2.0` +- See [CHANGELOG.md](CHANGELOG.md) for release history +- Helm chart version is independent from app version + +### Release Workflow +1. Version tags are created on `main` branch +2. Release branches follow pattern: `release-X.Y` (e.g., `release-0.1`) +3. Container images are built and pushed automatically by CI/CD +4. Helm chart is versioned independently in `charts/Chart.yaml` + +**Note:** Releases are managed by team leads. Contributors should focus on PRs to `main`. + +--- + +## Additional Resources + +- **Architecture Documentation**: https://github.com/openshift-hyperfleet/architecture +- **API Documentation**: See [docs/api-resources.md](docs/api-resources.md) +- **Development Guide**: See [docs/development.md](docs/development.md) +- **Search & Filtering**: See [docs/search.md](docs/search.md) +- **CLAUDE.md**: AI agent context (main + subdirectories)