Skip to content

HYPERFLEET-1186 - fix: align documentation with codebase and fix pageSize default #211

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 5 commits into from
Jun 15, 2026
Merged

HYPERFLEET-1186 - fix: align documentation with codebase and fix pageSize default #211

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5243d53
HYPERFLEET-1186 - docs: align documentation with codebase
sherine-k Jun 10, 2026
d2d1e75
HYPERFLEET-1186 - fix: align pageSize default with TypeSpec contract
sherine-k Jun 10, 2026
bdb9bed
HYPERFLEET-1168 - docs: consolidate documentation with v1.0.0 features
sherine-k Jun 11, 2026
83ff866
HYPERFLEET-1168 - docs: streamline docs and take various reviews into…
sherine-k Jun 12, 2026
bcf3896
HYPERFLEET-1168 - docs: fix review findings and reorganize delete lif…
sherine-k 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
60 changes: 46 additions & 14 deletions README.md
View file
Open in desktop

@rh-amarin rh-amarin Jun 15, 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.

I personally would go for a simpler README
e.g. the Architecture section is a list of features, with different abstraction/detail level.
Also the endpoints list could be stripped away since we have a doc for that

Regarding the definition of the API, now that I read it again I find it to be misleading...

I am thinking on something like:

The HyperFleet API is the data storage and status aggregation layer of the HyperFleet platform. It exposes a REST API for CRUD operations on customizable entities (e.g. Cluster, NodePool) backed by PostgreSQL.

The API is the source of truth for desired state of resources that live in remote clusters. It persists resource specs, increments generation on spec changes, and aggregates adapter-reported conditions into Kubernetes-style status.

It does not reconcile infrastructure or publish events itself. For that it collaborates with other HyperFleet components:

  • Sentinel component polls the API for unreconciled resources and publishes a message for reconciliation actions
  • Adapters components listen to events, perform actions needed to reconcile a resource and report the status to the API.

Stateless design enables horizontal scaling. Adapters fetch full resource state from the API after receiving minimal CloudEvents (anemic events pattern).

Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ HyperFleet API - Simple REST API for cluster lifecycle management. Provides CRUD

### Technology Stack

- **Language**: Go 1.24+
- **Language**: Go 1.25+
- **API Definition**: OpenAPI 3.0
- **Code Generation**: oapi-codegen
- **Database**: PostgreSQL with GORM ORM
Expand All @@ -17,11 +17,17 @@ HyperFleet API - Simple REST API for cluster lifecycle management. Provides CRUD

* OpenAPI 3.0 specification
* Automated Go code generation from OpenAPI
* Cluster and NodePool lifecycle management
* Cluster and NodePool lifecycle management (create, patch, delete, force-delete)
* Generic resource types (WifConfigs, Channels, Versions) via plugin-based registration
* Adapter-based status reporting with Kubernetes-style conditions
* Soft-delete with adapter finalization and force-delete for stuck resources
* Descriptor-driven delete policies (restrict/cascade) for generic resources
* RFC 9457 Problem Details error responses
* Configurable caller identity for audit fields (HTTP header or JWT claim)
* Runtime spec validation against custom OpenAPI schemas
* Pagination and search capabilities
* Complete integration test coverage
* Database migrations with GORM
* Database migrations with gormigrate
* Embedded OpenAPI specification using `//go:embed`

### Project Structure
Expand All @@ -30,11 +36,18 @@ HyperFleet API - Simple REST API for cluster lifecycle management. Provides CRUD
hyperfleet-api/
├── cmd/hyperfleet-api/ # Application entry point
├── pkg/
│ ├── api/ # API models and handlers
│ ├── api/ # API models and type definitions
│ ├── dao/ # Data access layer
│ ├── db/ # Database setup and migrations
│ ├── db/ # Database setup, migrations, and session management
│ ├── handlers/ # HTTP request handlers
│ └── services/ # Business logic
│ └── services/ # Service layer (status aggregation, CRUD)
├── plugins/ # Plugin-based resource registration
│ ├── clusters/ # Cluster resource plugin
│ ├── nodePools/ # NodePool resource plugin
│ ├── wifconfigs/ # WifConfig resource plugin
│ ├── channels/ # Channel resource plugin
│ ├── versions/ # Version resource plugin (child of Channel)
│ └── generic/ # Generic resource framework
├── openapi/ # Generated artifacts from hyperfleet-api-spec module
├── test/ # Integration tests and factories
├── docs/ # Detailed documentation
Expand All @@ -45,7 +58,7 @@ hyperfleet-api/

### Prerequisites

- **Go 1.24+**, **Podman**, **PostgreSQL 13+**, **Make**
- **Go 1.25+**, **Podman**, **PostgreSQL 14+**, **Make**

See [PREREQUISITES.md](PREREQUISITES.md) for installation instructions.

Expand All @@ -61,18 +74,26 @@ go mod download
# 3. Build binary
make build

# 4. Setup database
# 4. Setup database (local PostgreSQL container)
make db/setup

# 5. Run migrations
# 5. Copy config file
cp configs/config.yaml.example configs/config.yaml

# 6. Run migrations
./bin/hyperfleet-api migrate

# 6. Start service (no auth)
# 7. Start service (no auth)
make run-no-auth
```

**Note**: Generated code is not tracked in git. You must run `make generate-all` after cloning.

The `migrate` and `serve` commands require a configuration file. The loader checks `--config` flag, then `HYPERFLEET_CONFIG` env var, then `/etc/hyperfleet/config.yaml`, then `./configs/config.yaml`.
If none are found, the command fails with `failed to load configuration`. Copy the example config or point to your own.

@coderabbitai coderabbitai Bot Jun 11, 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.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify config loader validates file permissions and paths

rg -n -C3 'HYPERFLEET_CONFIG|--config' --type=go --glob '!vendor/**' | head -50

# Check for path validation or permission checks
ast-grep --pattern $'func $_(path string) $_ {
  $$$
  os.Stat($$$)
  $$$
}'

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 3029

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# 1) Inspect config loader path resolution + any permission/ownership checks
echo "=== pkg/config/loader.go: resolveAndReadConfigFile ==="
rg -n "resolveAndReadConfigFile|HYPERFLEET_CONFIG|/etc/hyperfleet/config.yaml|configs/config.yaml|ReadInConfig|os\.Stat|UnmarshalExact" pkg/config/loader.go
echo
sed -n '1,220p' pkg/config/loader.go

# 2) Inspect config validation/unmarshal in loader.go (schema enforcement)
echo
echo "=== pkg/config/loader.go: validation calls ==="
rg -n "UnmarshalExact|validator\.Struct|Validate|identity|JWT|TLS|timeout" pkg/config/loader.go

# 3) Force-delete wiring: handler -> service -> auth/RBAC/owner scoping
echo
echo "=== ForceDelete handlers/services (ownership/RBAC) ==="
rg -n "ForceDelete|force-delete" cmd pkg/handlers pkg/services cmd/hyperfleet-api/server/routes.go
echo
# show key snippets if present
for f in cmd/hyperfleet-api/server/routes.go \
         pkg/handlers/cluster.go \
         pkg/handlers/cluster_nodepools.go \
         pkg/services/cluster.go \
         pkg/services/node_pool.go \
         pkg/services/resource.go
do
  if [ -f "$f" ]; then
    echo
    echo "=== $f (relevant lines) ==="
    rg -n "ForceDelete|force-delete|JWTHandler|PublicPaths|CallerIdentityMiddleware|deleteResourceTree|restrict|cascade" "$f" || true
  fi
done

# 4) deleteResourceTree recursion guards
echo
echo "=== pkg/services/resource.go: deleteResourceTree ==="
rg -n "func .*deleteResourceTree|deleteResourceTree|visited|depth|cycle|restrict|cascade" pkg/services/resource.go || true
if [ -f pkg/services/resource.go ]; then
  sed -n '1,260p' pkg/services/resource.go
fi

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 30155

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Force-delete authN/authZ + middleware wiring
rg -n "PublicPaths|JWTHandler|CallerIdentityMiddleware|force-delete|force delete|ForceDelete" cmd/hyperfleet-api/server/routes.go
echo "----"
sed -n '1,220p' cmd/hyperfleet-api/server/routes.go
echo "----"

rg -n "handleForceDelete|ForceDeleteRequest|jwt|RBAC|authorize|permission|role" pkg/handlers/framework.go pkg/handlers/cluster.go pkg/handlers/cluster_nodepools.go
echo "----"
sed -n '120,230p' pkg/handlers/framework.go
echo "----"
sed -n '140,230p' pkg/handlers/cluster.go
echo "----"
sed -n '120,210p' pkg/handlers/cluster_nodepools.go
echo "----"

# Service-level checks for ForceDelete
rg -n "func \\(s \\*sqlClusterService\\) ForceDelete|func \\(s \\*sqlNodePoolService\\) ForceDelete|DeletedTime|owner|GetBy.*Owner|auth|RBAC|permission" pkg/services/cluster.go pkg/services/node_pool.go
echo "----"
sed -n '450,620p' pkg/services/cluster.go
echo "----"
sed -n '220,360p' pkg/services/node_pool.go
echo "----"

# deleteResourceTree recursion/cycle guards
rg -n "deleteResourceTree\\(|visited|depth|cycle|max depth" pkg/services/resource.go
echo "----"
sed -n '130,260p' pkg/services/resource.go
echo "----"

# Registry descriptor graph validation (cycles, depth limits)
rg -n "cycle|acyclic|topolog|visited|graph|ChildrenOf\\(" pkg/registry
fd . pkg/registry -t f | head -50
for f in $(fd -t f pkg/registry | tr '\n' ' '); do
  # keep output small by only showing likely validation locations
  rg -n "cycle|acyclic|topolog|graph|ChildrenOf\\(" "$f" && echo "---- in $f ----" && break
done

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 28168

README.md: Document the file-path trust boundary for --config / HYPERFLEET_CONFIG

README.md lines 92-93: --config and HYPERFLEET_CONFIG are used as the config file path (only an existence check via os.Stat for explicit sources, then viper.ReadInConfig), with no allowlist/permission/ownership validation—external path control is a CWE-73 risk (path-controlled file read). Document that the path must be operator-trusted and specify expected file permissions/ownership.

Also adjust the wording to reflect that config content is validated in code (viper.UnmarshalExact + validator.Struct + custom TLS/JWT/timeouts/identity checks); the missing gap is path/permission safety, not schema/content enforcement.

🤖 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 `@README.md` around lines 92 - 93, Update README.md to document the trust
boundary for config file paths used by the loader (the --config flag and
HYPERFLEET_CONFIG env var) and explicitly state that these paths must be
operator-trusted; note that the loader only performs an existence check
(os.Stat) for explicit sources and then reads via viper.ReadInConfig, so callers
must ensure the file path, permissions and ownership are secure (suggested
mode/owner and disallow world-writable access). Also change the wording to
clarify that schema/content validation is performed in code
(viper.UnmarshalExact + validator.Struct plus custom TLS/JWT/timeouts/identity
checks), and that the documented gap is path/permission safety rather than
configuration content validation.


For production database setup (external PostgreSQL, Cloud SQL, etc.), see [docs/deployment.md](docs/deployment.md#production-deployment).

### Accessing the API

The service starts on `localhost:8000`:
Expand All @@ -97,7 +118,8 @@ Kubernetes clusters with provider-specific configurations, labels, and adapter-b

**Main endpoints:**
- `GET/POST /api/hyperfleet/v1/clusters`
- `GET /api/hyperfleet/v1/clusters/{id}`
- `GET/PATCH/DELETE /api/hyperfleet/v1/clusters/{id}`
- `POST /api/hyperfleet/v1/clusters/{id}/force-delete`

@coderabbitai coderabbitai Bot Jun 11, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if force-delete handler enforces stricter authz than regular DELETE

rg -n -C5 'force-delete|ForceDelete' --type=go pkg/handlers/ | head -80

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 4993

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# 1) Locate routes/endpoints mentioning force-delete and where authz/middleware is wired.
rg -n --hidden --no-ignore-vcs "force-delete" . || true
rg -n --hidden --no-ignore-vcs "ForceDelete" . || true

# 2) Inspect surrounding handler code for ForceDelete and any normal DELETE methods.
echo "---- cluster.go around ForceDelete and any Delete handlers ----"
sed -n '130,240p' pkg/handlers/cluster.go || true

echo "---- cluster_nodepools.go around ForceDelete and any Delete handlers ----"
sed -n '1,260p' pkg/handlers/cluster_nodepools.go || true

# 3) Inspect framework handler for handleForceDelete / authz-related hooks.
sed -n '1,240p' pkg/handlers/framework.go || true

# 4) README snippet around line ~122 (as referenced by review comment)
ls -la || true
sed -n '90,150p' README.md || true

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 30129

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# 1) Inspect plugin/router wiring around force-delete handlers.
sed -n '1,140p' plugins/clusters/plugin.go

# 2) Find router/middleware/auth wiring keywords.
rg -n --hidden --no-ignore-vcs "middleware|auth|RBAC|Role|scope|Authorize|authorization|Permission|entitle|claims|user|principal" pkg cmd plugins charts configs serve . || true

# 3) Check how handlers get context: ownership/user extracted somewhere.
rg -n --hidden --no-ignore-vcs "GetByIDAndOwner|owner|tenant|project|account|userID|principal|subject" pkg | head -200 || true

# 4) Inspect cluster/node_pool service ForceDelete implementations for any explicit authz checks.
sed -n '450,660p' pkg/services/cluster.go
sed -n '220,380p' pkg/services/node_pool.go

# 5) Inspect regular DELETE handlers to compare logic surface.
# cluster DELETE handler
sed -n '120,220p' pkg/handlers/cluster.go
# nodepool DELETE handler
sed -n '80,200p' pkg/handlers/cluster_nodepools.go

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 50392

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "---- pkg/services/cluster.go: ForceDelete + any SoftDelete/Delete around it ----"
rg -n "func \\(s \\*sqlClusterService\\) (ForceDelete|SoftDelete|Delete)" pkg/services/cluster.go
sed -n '430,620p' pkg/services/cluster.go

echo "---- pkg/services/node_pool.go: ForceDelete + any SoftDelete/Delete around it ----"
rg -n "func \\(s \\*sqlNodePoolService\\) (ForceDelete|SoftDelete|Delete)" pkg/services/node_pool.go
sed -n '180,360p' pkg/services/node_pool.go

echo "---- pkg/dao: ForceDelete-related queries in cluster/node_pool ----"
rg -n "ForceDelete" pkg/dao || true
rg -n "SoftDelete|Soft delete|deleted_time" pkg/dao/cluster*.go pkg/dao/*node*pool*.go || true

echo "---- handler delete endpoints (for comparison): pkg/handlers/cluster.go SoftDelete/DELETE semantics ----"
rg -n "func \\(h ClusterHandler\\) (SoftDelete|Delete|ForceDelete)" pkg/handlers/cluster.go
sed -n '120,220p' pkg/handlers/cluster.go

echo "---- handler delete endpoints (for comparison): pkg/handlers/cluster_nodepools.go SoftDelete/ForceDelete semantics ----"
rg -n "func \\(h ClusterNodePoolsHandler\\) (SoftDelete|ForceDelete)" pkg/handlers/cluster_nodepools.go
sed -n '80,200p' pkg/handlers/cluster_nodepools.go

echo "---- cmd/hyperfleet-api/server: middleware/router auth wiring (targeted) ----"
rg -n "Use\\(|middleware|auth\\.|authz|RBAC|authorize|permission|JWT|Identity" cmd/hyperfleet-api/server cmd/hyperfleet-api/environments cmd/hyperfleet-api/*.go || true

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 22615

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Cluster service: SoftDelete implementation details
echo "---- pkg/services/cluster.go: SoftDelete (and related delete methods) ----"
sed -n '120,260p' pkg/services/cluster.go
sed -n '260,420p' pkg/services/cluster.go
sed -n '420,560p' pkg/services/cluster.go

# Node pool service: see SoftDelete/ Delete / ForceDelete call patterns re owner checks
echo "---- pkg/services/node_pool.go: SoftDelete and Delete ----"
sed -n '150,280p' pkg/services/node_pool.go
sed -n '280,360p' pkg/services/node_pool.go

# DAO cluster: see whether GetForUpdate or SoftDelete uses caller/owner scoping
echo "---- pkg/dao/cluster*.go: search for GetForUpdate / SoftDelete ownership ----"
rg -n "type .*ClusterDao|GetForUpdate|SoftDelete|DeletedTime|ByOwner|Owner" pkg/dao --glob '*cluster*' || true
rg -n "GetForUpdate\\(|SoftDelete\\(|Delete\\(" pkg/dao --glob '*cluster*' || true

# Show cluster dao implementation for GetForUpdate and any owner-filtered queries
# (we don't know filename; use fd-like search with rg results)
echo "---- showing matching cluster dao files with GetForUpdate ----"
rg -n "GetForUpdate\\(" pkg/dao --glob '*cluster*' --files-with-matches || true

# Print relevant sections from all files that define GetForUpdate in cluster dao (limited)
for f in $(rg -n "func \\(.*\\) GetForUpdate\\(" pkg/dao --glob '*cluster*' --files-with-matches); do
  echo "==== $f ===="
  sed -n '1,220p' "$f"
  sed -n '220,420p' "$f"
done || true

# Node pool DAO: GetByIDAndOwner scoping
echo "---- pkg/dao/node*pool*.go: GetByIDAndOwner ----"
rg -n "GetByIDAndOwner\\(" pkg/dao --glob '*node*pool*' || true
for f in $(rg -n "GetByIDAndOwner\\(" pkg/dao --glob '*node*pool*' --files-with-matches || true); do
  echo "==== $f ===="
  sed -n '1,260p' "$f"
done

# Handlers/tests: look for authz expectations for force-delete
echo "---- pkg/handlers/cluster_test.go: search for Unauthorized/Forbidden around ForceDelete ----"
rg -n "ForceDelete|force-delete|401|403|Unauthorized|Forbidden" pkg/handlers/cluster_test.go pkg/handlers/cluster_nodepools_test.go | head -200 || true

echo "---- pkg/handlers/cluster_nodepools_test.go: search for authz around ForceDelete ----"
rg -n "Unauthorized|Forbidden|401|403" pkg/handlers/cluster_nodepools_test.go pkg/handlers/cluster_test.go | head -200 || true

echo "---- integration tests: search for force-delete authz expectations ----"
rg -n "force-delete.*(401|403|Unauthorized|Forbidden)" test/integration -S --glob '*force*' || true
rg -n "Unauthorized|Forbidden|401|403" test/integration/clusters_test.go test/integration/node_pools_test.go | head -200 || true

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 38188

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "---- README.md: search for force-delete auth/RBAC/runbook text ----"
rg -n "force-delete|ForceDelete|RBAC|role|permission|authorize|authorization|runbook|safety|admin" README.md docs/api-resources.md docs/runbook.md docs/database.md || true
echo "---- README.md around line ~100-150 (includes force-delete endpoint list) ----"
sed -n '90,160p' README.md || true

echo "---- docs/api-resources.md: force-delete cluster section ----"
rg -n "POST /api/hyperfleet/v1/clusters/\\{.*\\}/force-delete|force-delete cluster|Force Delete Cluster|Force Delete" docs/api-resources.md || true
# show likely relevant sections by line ranges
sed -n '340,420p' docs/api-resources.md || true

echo "---- docs/api-resources.md: force-delete nodepool section ----"
sed -n '520,600p' docs/api-resources.md || true

echo "---- cmd/hyperfleet-api/server/routes.go: full to see if authz is wired ----"
sed -n '1,200p' cmd/hyperfleet-api/server/routes.go || true
sed -n '200,420p' cmd/hyperfleet-api/server/routes.go || true

echo "---- search cmd/hyperfleet-api/server for authorize/authz/RBAC names ----"
rg -n --no-ignore-vcs "authorize|authorization|authz|RBAC|role|permission|Scope" cmd/hyperfleet-api/server pkg/middleware pkg/auth || true

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 16418

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "---- Find Cluster model struct in pkg/api ----"
rg -n "type Cluster struct" pkg/api || true
# show likely file
f=$(rg -n "type Cluster struct" pkg/api --files-with-matches | head -n 1 || true)
echo "cluster struct file: $f"
if [ -n "${f:-}" ]; then
  sed -n '1,220p' "$f"
fi

echo "---- Search for owner_id / OwnerID in Cluster struct or fields ----"
rg -n "OwnerID|owner_id|owner" "$f" || true

echo "---- Confirm cluster handler SoftDelete (regular DELETE) calls service without ownership scoping ----"
sed -n '130,220p' pkg/handlers/cluster.go

echo "---- docs/api-resources.md force-delete cluster section for any RBAC/access control text ----"
# narrow by lines around "Force Delete Cluster"
rg -n "### Force Delete Cluster|Force Delete Cluster|force-delete cluster" docs/api-resources.md
# print a chunk around those lines
sed -n '350,410p' docs/api-resources.md
echo "---- docs/api-resources.md force-delete nodepool section for RBAC/access control text ----"
sed -n '540,590p' docs/api-resources.md

Repository: openshift-hyperfleet/hyperfleet-api

Length of output: 7568

Enforce authorization for force-delete endpoints (CWE-285).

  • Cluster POST /api/hyperfleet/v1/clusters/{id}/force-delete has no caller authorization scoping: pkg/handlers/cluster.go forwards directly to pkg/services/cluster.go where clusterDao.GetForUpdate selects by id = ? and then hard-deletes cluster + adapter statuses + child nodepools.
  • NodePool POST /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/force-delete only scopes by path relationship (GetByIDAndOwner filters id = ? AND owner_id = ? with owner_id = cluster_id), not by caller identity/permissions.
  • Docs describe the operational safety conditions for force-delete, but do not document any RBAC/permission requirements for invoking it.
🤖 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 `@README.md` at line 122, The force-delete endpoints lack caller authorization
checks; update the handlers and service layer to enforce RBAC by validating the
calling principal before performing destructive operations: in
pkg/handlers/cluster.go add an authorization check that extracts caller
identity/roles from the request and denies access if not permitted, then pass an
authorized context/principal into pkg/services/cluster.go; in
pkg/services/cluster.go verify the principal's permission prior to calling
clusterDao.GetForUpdate and before deleting adapter statuses/child nodepools;
also tighten NodePool logic where GetByIDAndOwner is used to ensure it validates
caller identity/permissions (not just path ownership) and finally update
README.md to document the required RBAC/permission prerequisites for invoking
the force-delete endpoints.

@sherine-k sherine-k Jun 12, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

We're just listing the endpoints in the README.md. I think we can talk about authorization verification in a later section, with a reminder in api-resources for example, pointing to the authentication.md ?

@coderabbitai coderabbitai Bot Jun 12, 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.

@sherine-k — Agreed, the endpoint listing section isn't the place for auth docs. A note in docs/api-resources.md under the Force Delete sections (cluster + nodepool) pointing to docs/authentication.md for access-control requirements is the right structure.

That said, the documentation concern is separate from the underlying code issue (CWE-285): pkg/handlers/cluster.go and pkg/handlers/cluster_nodepools.go currently forward ForceDelete calls straight to the service/DAO layer with no caller-identity authorization check — only path-parameter ownership (id / owner_id) is validated. That's a live security gap independent of what the docs say.

Would you like me to open a follow-up GitHub issue to track the missing authorization enforcement in the force-delete handlers?

- `GET/PUT /api/hyperfleet/v1/clusters/{id}/statuses`

### NodePools
Expand All @@ -107,10 +129,19 @@ Groups of compute nodes within clusters.
**Main endpoints:**
- `GET /api/hyperfleet/v1/nodepools`
- `GET/POST /api/hyperfleet/v1/clusters/{cluster_id}/nodepools`
- `GET /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}`
- `GET/PATCH/DELETE /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}`
- `POST /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/force-delete`
- `GET/PUT /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses`

Both resources support pagination, label-based search, and adapter status reporting. See [docs/api-resources.md](docs/api-resources.md) for complete API documentation.
### Generic Resources

The API also supports generic resource types registered via the plugin system. Currently available:

- **WifConfigs** — `GET/POST /api/hyperfleet/v1/wifconfigs`, `GET/PATCH/DELETE .../wifconfigs/{id}`
- **Channels** — `GET/POST /api/hyperfleet/v1/channels`, `GET/PATCH/DELETE .../channels/{id}`
- **Versions** — `GET/POST /api/hyperfleet/v1/channels/{parent_id}/versions`, `GET/PATCH/DELETE .../versions/{id}` (child of Channel)

All resources support pagination, label-based search, and spec validation. Clusters and NodePools additionally support adapter status reporting. See [docs/api-resources.md](docs/api-resources.md) for complete API documentation.

## Example Usage

Expand Down Expand Up @@ -169,6 +200,7 @@ This project uses [pre-commit](https://pre-commit.io/) for code quality checks.
- **[Development Guide](docs/development.md)** - Local setup, testing, code generation, and workflows
- **[Database](docs/database.md)** - Schema, migrations, and data model
- **[Deployment](docs/deployment.md)** - Container images, Kubernetes deployment, and configuration
- **[Configuration](docs/config.md)** - Complete configuration reference (database, server, caller identity, adapters)
- **[Authentication](docs/authentication.md)** - Development and production auth
- **[Logging](docs/logging.md)** - Structured logging, OpenTelemetry integration, and data masking
- **[Validation Schema](openapi/README.md#validation-schema)** - How to supply a custom OpenAPI schema for runtime `spec` field validation
Expand All @@ -183,4 +215,4 @@ This project uses [pre-commit](https://pre-commit.io/) for code quality checks.

## License

[License information to be added]
This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.
Loading