Skip to content

HYPERFLEET-1282: Document pageSize→size / orderBy→order breaking change #173

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

Merged
openshift-merge-bot merged 1 commit into from
Jun 26, 2026
+17 −16
Merged

HYPERFLEET-1282: Document pageSize→size / orderBy→order breaking change #173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions hyperfleet/docs/performance-baselines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,8 @@ API read thresholds are consistent across both environments.
| GET /clusters/{id} (large payload) | 4.34ms | 32.61ms | 50ms |
| GET /clusters (no filter) | 5.10ms | 32.63ms | 50ms |
| GET /clusters (search filter) | 4.89ms | 33.03ms | 50ms |
| GET /clusters (pageSize=10) | 4.22ms | 31.42ms | 50ms |
| GET /clusters (page=1, pageSize=10) | 4.23ms | 33.30ms | 50ms |
| GET /clusters (size=10) | 4.22ms | 31.42ms | 50ms |
| GET /clusters (page=1, size=10) | 4.23ms | 33.30ms | 50ms |


API read latencies on Prow are higher than GKE dev (~30ms vs ~3-5ms) but pass comfortably within the 50ms threshold.
Expand Down
29 changes: 15 additions & 14 deletions hyperfleet/docs/release/v1.0.0/breaking-changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
Status: Active
Owner: HyperFleet Team
Last Updated: 2026-06-10
Last Updated: 2026-06-25
---

# v0.2.0 to v1.0.0 Breaking-Change and Reconfiguration Checklist
Expand All @@ -22,39 +22,40 @@ This document is the deliverable for [HYPERFLEET-1177](https://redhat.atlassian.
| 2 | **Ready condition removed; replaced by Reconciled** | Replace all `Ready` references with `Reconciled` in status queries, scripts, and monitoring | **Silent hang.** API silently accepts `type="Ready"` in status reports but never aggregates it into resource conditions; scripts polling for Ready=True wait forever | Automatable (1178) | [HYPERFLEET-1052](https://redhat.atlassian.net/browse/HYPERFLEET-1052) | [HYPERFLEET-559](https://redhat.atlassian.net/browse/HYPERFLEET-559) |
| 3 | **Aggregated condition Available renamed to LastKnownReconciled** | Replace `Available` with `LastKnownReconciled` in all resource-level condition queries | **Not found.** Aggregation code produces only `Reconciled` and `LastKnownReconciled`; resource-level `Available` is no longer emitted | Automatable (1178) | [HYPERFLEET-1017](https://redhat.atlassian.net/browse/HYPERFLEET-1017) | - |
| 4 | **List responses: kind field removed** | Remove `kind` expectations in list response parsing | **Parse error** if client schema requires `kind`. Confirmed: `kind` removed from `ClusterList`, `NodePoolList`, `ResourceList`, `AdapterStatusList`; test asserts `raw.NotTo(HaveKey("kind"))` | Automatable (1178) | [HYPERFLEET-1143](https://redhat.atlassian.net/browse/HYPERFLEET-1143) | - |
| 5 | **Pagination query parameters renamed: `pageSize` → `size`, `orderBy` → `order`** | Replace `pageSize` with `size` and `orderBy` with `order` in all API list-endpoint calls (`GET /clusters`, `GET /nodepools`, `GET /resources`). For generated clients (e.g. from the OpenAPI spec), regenerate after the spec update in HYPERFLEET-1279 | **Silent incorrect results.** Old parameter names are not recognized; requests silently fall back to defaults (page 1, size 20, no ordering) with no error returned | Manual | [HYPERFLEET-1280](https://redhat.atlassian.net/browse/HYPERFLEET-1280) | [HYPERFLEET-1272](https://redhat.atlassian.net/browse/HYPERFLEET-1272) |

@ldornele ldornele Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Severity: nit

Suggested fix:

Add API: prefix to the title for clarity:

| 5 | **API: Pagination query parameters renamed: `pageSize` → `size`, `orderBy` → `order`** |

This:

  • Makes it explicit this is a REST API contract change
  • Follows the component-prefix pattern of rows 6-9
  • Helps readers quickly scan which changes affect each component

@ldornele ldornele Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Severity: nit

The title uses arrow notation → for parameter renaming, but the document has mixed patterns for expressing transitions

Suggested fix:

For consistency with row 3's "renamed to" pattern:

| 5 | **... query parameters renamed: `pageSize` to `size`, `orderBy` to `order`** |

@ldornele ldornele Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Severity: nit

Inline JIRA reference HYPERFLEET-1279 in the "Partner Action" column is not hyperlinked, while other columns consistently provide clickable links to JIRA tickets.

Hyperlink the inline ticket reference for consistency:

regenerate after the spec update in [HYPERFLEET-1279](https://redhat.atlassian.net/browse/HYPERFLEET-1279)

This maintains the pattern of always providing clickable links for JIRA tickets mentioned in the document.


### Configuration

| # | Change | Partner Action | Impact if Missed | Classification | Ticket | Parent |
|---|--------|---------------|-----------------|----------------|--------|--------|
| 5 | **Sentinel: messaging_system field removed and config parser now strict** | Remove `messaging_system` from all Sentinel configs and `MESSAGING_SYSTEM` env var. Also remove any other unrecognized fields | **Sentinel fails to start.** v0.2.0 used permissive `v.Unmarshal()`; v1.0.0 uses strict `v.UnmarshalExact()` which rejects unknown fields. Any unrecognized field in the config will cause a startup failure | Automatable (1178) | Sentinel CHANGELOG | - |
| 6 | **Sentinel and Adapter CEL: Ready to Reconciled** | Update ALL `message_decision` CEL in Sentinel AND all precondition/capture CEL in Adapter configs | **CRITICAL SILENT FAILURE.** `condition("Ready")` returns a zero-value struct (empty status, generation 0) via fallback in `decision.go`; CEL evaluates to false; Sentinel never publishes events; adapters never fire; clusters stuck in pending. No error logged | Automatable (1178) | [HYPERFLEET-857](https://redhat.atlassian.net/browse/HYPERFLEET-857) | [HYPERFLEET-559](https://redhat.atlassian.net/browse/HYPERFLEET-559) |
| 7 | **Sentinel Helm: config.hyperfleetApi moved to config.clients.hyperfleetApi** | Move API client config from `config.hyperfleetApi.baseUrl` to `config.clients.hyperfleetApi.baseUrl` in Sentinel Helm values | **Sentinel fails to start.** Helm template references `.Values.config.clients.hyperfleetApi.baseUrl`; old path renders empty; validation fails with "clients.hyperfleet_api.base_url required" | Automatable (1178) | [HYPERFLEET-549](https://redhat.atlassian.net/browse/HYPERFLEET-549), [HYPERFLEET-866](https://redhat.atlassian.net/browse/HYPERFLEET-866) | - |
| 8 | **Sentinel Helm: messageDecision params changed from map to list** | Restructure `messageDecision.params` from map format (`key: 'expr'`) to list format (`- name: key, expr: 'expr'`) | **Helm template fails to render.** Template iterates with `.name` and `.expr` fields; old map format has no such fields. Also fixes non-deterministic param ordering | Automatable (1178) | [HYPERFLEET-1011](https://redhat.atlassian.net/browse/HYPERFLEET-1011) | - |
| 9 | **API Helm: jwt.enabled default changed from true to false** | Explicitly set `config.server.jwt.enabled: true` in Helm values if JWT authentication is required | **API accepts unauthenticated requests.** v0.2.0 Helm chart defaulted to `jwt.enabled: true`; v1.0.0 defaults to `false`. Requests that were previously rejected without a valid JWT token are now accepted | Doc-only (1163/1179) | Helm chart values.yaml diff | - |
| 10 | **JWT identity_claim required when JWT enabled** | Add `server.jwt.identity_claim` pointing to JWT claim for caller identity | **API fails to start** if JWT enabled without identity_claim. Config validation: `if c.IdentityClaim == "" { return fmt.Errorf("server.jwt.identity_claim is required") }`. If claim name is set but does not exist in token, mutating requests (POST/PUT/PATCH/DELETE) fail with auth error; GET requests proceed without identity | Doc-only (1163/1179) | [HYPERFLEET-1134](https://redhat.atlassian.net/browse/HYPERFLEET-1134) | [HYPERFLEET-824](https://redhat.atlassian.net/browse/HYPERFLEET-824) |
| 11 | **Default log format changed to JSON (Sentinel and Adapter)** | Update log parsing pipelines if expecting text format from Sentinel or Adapter | **Log parsing breaks** for Sentinel and Adapter output. `DefaultConfig()` changed from `FormatText` to `FormatJSON` in both components (PRs #103 and #109). API was already JSON in v0.2.0 and is unchanged | Doc-only (1163/1179) | [HYPERFLEET-908](https://redhat.atlassian.net/browse/HYPERFLEET-908) | - |
| 6 | **Sentinel: messaging_system field removed and config parser now strict** | Remove `messaging_system` from all Sentinel configs and `MESSAGING_SYSTEM` env var. Also remove any other unrecognized fields | **Sentinel fails to start.** v0.2.0 used permissive `v.Unmarshal()`; v1.0.0 uses strict `v.UnmarshalExact()` which rejects unknown fields. Any unrecognized field in the config will cause a startup failure | Automatable (1178) | Sentinel CHANGELOG | - |
| 7 | **Sentinel and Adapter CEL: Ready to Reconciled** | Update ALL `message_decision` CEL in Sentinel AND all precondition/capture CEL in Adapter configs | **CRITICAL SILENT FAILURE.** `condition("Ready")` returns a zero-value struct (empty status, generation 0) via fallback in `decision.go`; CEL evaluates to false; Sentinel never publishes events; adapters never fire; clusters stuck in pending. No error logged | Automatable (1178) | [HYPERFLEET-857](https://redhat.atlassian.net/browse/HYPERFLEET-857) | [HYPERFLEET-559](https://redhat.atlassian.net/browse/HYPERFLEET-559) |
| 8 | **Sentinel Helm: config.hyperfleetApi moved to config.clients.hyperfleetApi** | Move API client config from `config.hyperfleetApi.baseUrl` to `config.clients.hyperfleetApi.baseUrl` in Sentinel Helm values | **Sentinel fails to start.** Helm template references `.Values.config.clients.hyperfleetApi.baseUrl`; old path renders empty; validation fails with "clients.hyperfleet_api.base_url required" | Automatable (1178) | [HYPERFLEET-549](https://redhat.atlassian.net/browse/HYPERFLEET-549), [HYPERFLEET-866](https://redhat.atlassian.net/browse/HYPERFLEET-866) | - |
| 9 | **Sentinel Helm: messageDecision params changed from map to list** | Restructure `messageDecision.params` from map format (`key: 'expr'`) to list format (`- name: key, expr: 'expr'`) | **Helm template fails to render.** Template iterates with `.name` and `.expr` fields; old map format has no such fields. Also fixes non-deterministic param ordering | Automatable (1178) | [HYPERFLEET-1011](https://redhat.atlassian.net/browse/HYPERFLEET-1011) | - |
| 10 | **API Helm: jwt.enabled default changed from true to false** | Explicitly set `config.server.jwt.enabled: true` in Helm values if JWT authentication is required | **API accepts unauthenticated requests.** v0.2.0 Helm chart defaulted to `jwt.enabled: true`; v1.0.0 defaults to `false`. Requests that were previously rejected without a valid JWT token are now accepted | Doc-only (1163/1179) | Helm chart values.yaml diff | - |
| 11 | **JWT identity_claim required when JWT enabled** | Add `server.jwt.identity_claim` pointing to JWT claim for caller identity | **API fails to start** if JWT enabled without identity_claim. Config validation: `if c.IdentityClaim == "" { return fmt.Errorf("server.jwt.identity_claim is required") }`. If claim name is set but does not exist in token, mutating requests (POST/PUT/PATCH/DELETE) fail with auth error; GET requests proceed without identity | Doc-only (1163/1179) | [HYPERFLEET-1134](https://redhat.atlassian.net/browse/HYPERFLEET-1134) | [HYPERFLEET-824](https://redhat.atlassian.net/browse/HYPERFLEET-824) |
| 12 | **Default log format changed to JSON (Sentinel and Adapter)** | Update log parsing pipelines if expecting text format from Sentinel or Adapter | **Log parsing breaks** for Sentinel and Adapter output. `DefaultConfig()` changed from `FormatText` to `FormatJSON` in both components (PRs #103 and #109). API was already JSON in v0.2.0 and is unchanged | Doc-only (1163/1179) | [HYPERFLEET-908](https://redhat.atlassian.net/browse/HYPERFLEET-908) | - |

### Auth

| # | Change | Partner Action | Impact if Missed | Classification | Ticket | Parent |
|---|--------|---------------|-----------------|----------------|--------|--------|
| 12 | **OCM SDK removed; standalone JWT handler** | Remove OCM-specific auth config (`server.acl`, `server.authz`); switch to JWT config (issuer_url, audience, identity_claim) | **Old auth config silently has no effect.** Entire `pkg/client/ocm/` and `pkg/config/ocm.go` removed. Old `server.acl` and `server.authz` Helm values are silently ignored. Combined with #9 (jwt.enabled defaults to false), the API may start with no authentication unless JWT is explicitly configured | Doc-only (1163/1179) | [HYPERFLEET-492](https://redhat.atlassian.net/browse/HYPERFLEET-492) | - |
| 13 | **OCM SDK removed; standalone JWT handler** | Remove OCM-specific auth config (`server.acl`, `server.authz`); switch to JWT config (issuer_url, audience, identity_claim) | **Old auth config silently has no effect.** Entire `pkg/client/ocm/` and `pkg/config/ocm.go` removed. Old `server.acl` and `server.authz` Helm values are silently ignored. Combined with #10 (jwt.enabled defaults to false), the API may start with no authentication unless JWT is explicitly configured | Doc-only (1163/1179) | [HYPERFLEET-492](https://redhat.atlassian.net/browse/HYPERFLEET-492) | - |

### Helm Charts

| # | Change | Partner Action | Impact if Missed | Classification | Ticket | Parent |
|---|--------|---------------|-----------------|----------------|--------|--------|
| 13 | **PgBouncer sidecar replaced by generic sidecars** | Rewrite PgBouncer config as generic sidecar entry in `sidecars` list | **No DB proxy sidecar.** Entire `database.pgbouncer.*` Helm values tree removed (not deprecated); old values silently ignored; pod starts without proxy | Doc-only (1163/1179) | [HYPERFLEET-937](https://redhat.atlassian.net/browse/HYPERFLEET-937) | - |
| 14 | **Sentinel config mount paths changed** | Update any custom scripts, init containers, or sidecar configs referencing `/etc/sentinel/config.yaml` or `/etc/sentinel/broker.yaml` to `/etc/hyperfleet/config.yaml` and `/etc/hyperfleet/broker.yaml` | **Config not found.** Custom scripts or containers referencing old path fail | Doc-only (1163/1179) | [HYPERFLEET-549](https://redhat.atlassian.net/browse/HYPERFLEET-549) | - |
| 15 | **Sentinel BROKER_TOPIC env var removed** | Remove `BROKER_TOPIC` env var overrides; use `broker.topic` in Helm values instead | **Topic override ignored.** Env var no longer injected by deployment template; partners overriding topic via env var will have it silently ignored, falling back to Helm value | Doc-only (1163/1179) | [HYPERFLEET-549](https://redhat.atlassian.net/browse/HYPERFLEET-549) | - |
| 16 | **Adapter Helm: broker.type now explicitly required; RabbitMQ fields validated** | Add explicit `broker.type: rabbitmq` or `broker.type: googlepubsub` to adapter Helm values. For RabbitMQ: `url`, `queue`, `exchange`, and `routingKey` are now required | **Helm rendering fails.** `_helpers.tpl` `brokerType` function now uses `required` instead of inference; missing `broker.type` fails at render time. Additionally, `validateBrokerConfig` template requires `url`, `queue`, `exchange`, `routingKey` for RabbitMQ | Automatable (1178) | Adapter Helm chart `_helpers.tpl` | - |
| 14 | **PgBouncer sidecar replaced by generic sidecars** | Rewrite PgBouncer config as generic sidecar entry in `sidecars` list | **No DB proxy sidecar.** Entire `database.pgbouncer.*` Helm values tree removed (not deprecated); old values silently ignored; pod starts without proxy | Doc-only (1163/1179) | [HYPERFLEET-937](https://redhat.atlassian.net/browse/HYPERFLEET-937) | - |
| 15 | **Sentinel config mount paths changed** | Update any custom scripts, init containers, or sidecar configs referencing `/etc/sentinel/config.yaml` or `/etc/sentinel/broker.yaml` to `/etc/hyperfleet/config.yaml` and `/etc/hyperfleet/broker.yaml` | **Config not found.** Custom scripts or containers referencing old path fail | Doc-only (1163/1179) | [HYPERFLEET-549](https://redhat.atlassian.net/browse/HYPERFLEET-549) | - |
| 16 | **Sentinel BROKER_TOPIC env var removed** | Remove `BROKER_TOPIC` env var overrides; use `broker.topic` in Helm values instead | **Topic override ignored.** Env var no longer injected by deployment template; partners overriding topic via env var will have it silently ignored, falling back to Helm value | Doc-only (1163/1179) | [HYPERFLEET-549](https://redhat.atlassian.net/browse/HYPERFLEET-549) | - |
| 17 | **Adapter Helm: broker.type now explicitly required; RabbitMQ fields validated** | Add explicit `broker.type: rabbitmq` or `broker.type: googlepubsub` to adapter Helm values. For RabbitMQ: `url`, `queue`, `exchange`, and `routingKey` are now required | **Helm rendering fails.** `_helpers.tpl` `brokerType` function now uses `required` instead of inference; missing `broker.type` fails at render time. Additionally, `validateBrokerConfig` template requires `url`, `queue`, `exchange`, `routingKey` for RabbitMQ | Automatable (1178) | Adapter Helm chart `_helpers.tpl` | - |

### Database

| # | Change | Partner Action | Impact if Missed | Classification | Ticket | Parent |
|---|--------|---------------|-----------------|----------------|--------|--------|
| 17 | **Fresh database required** | Deploy a completely fresh database. Do not reuse v0.2.0 database | **Policy, not technical limitation.** Migrations technically CAN run on v0.2.0 schema (RENAME COLUMN works), but the project explicitly states "fresh DB, no migration." Reusing old DB risks table locks on rename and untested migration paths | Doc-only (1163/1179) | Epic description | [HYPERFLEET-1176](https://redhat.atlassian.net/browse/HYPERFLEET-1176) |
| 18 | **Fresh database required** | Deploy a completely fresh database. Do not reuse v0.2.0 database | **Policy, not technical limitation.** Migrations technically CAN run on v0.2.0 schema (RENAME COLUMN works), but the project explicitly states "fresh DB, no migration." Reusing old DB risks table locks on rename and untested migration paths | Doc-only (1163/1179) | Epic description | [HYPERFLEET-1176](https://redhat.atlassian.net/browse/HYPERFLEET-1176) |

## Open Actions

Expand Down