Skip to content

HYPERFLEET-978 - docs: Update docs to reflect POST -> PUT changes #137

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
ma-hill wants to merge 1 commit into
base: main
Choose a base branch
from
Open

HYPERFLEET-978 - docs: Update docs to reflect POST -> PUT changes #137

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
2 changes: 1 addition & 1 deletion hyperfleet/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ Kubernetes resources (Jobs, Secrets, ConfigMaps, Services) created by adapters t
- Fetches cluster details from API
- Evaluates preconditions
- Creates Kubernetes resources if conditions met
- Reports status → POST /clusters/{id}/statuses
- Reports status → PUT /clusters/{id}/statuses
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 15, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Resolve cross-repo contract inconsistency before merge.

The architecture docs now specify PUT for /clusters/{id}/statuses, but the linked hyperfleet-api repository still documents POST for the same endpoint in README.md, docs/api-resources.md, docs/api-operator-guide.md, and docs/hyperfleet-api.http. Meanwhile, hyperfleet-adapter tests and mocks already expect PUT.

This three-way mismatch creates an ambiguous contract that will cause integration failures or force adapters to guess the correct verb.

Coordinate updates across repositories:

  1. If PUT is the agreed contract, update hyperfleet-api documentation and examples to match
  2. If the API implementation still requires POST, revert these architecture changes and update hyperfleet-adapter mocks
  3. If both verbs are supported, explicitly document the compatibility contract and semantics in all three repositories

As per coding guidelines: "Validate changes against HyperFleet architecture standards from the linked architecture repository."

🤖 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 `@hyperfleet/README.md` at line 146, The README shows a mismatch for the HTTP
verb on the /clusters/{id}/statuses endpoint (docs changed to PUT but
hyperfleet-api still documents POST while hyperfleet-adapter tests expect PUT);
resolve the contract by choosing and enforcing a single behavior: if PUT is the
contract, update all hyperfleet-api docs and examples (README.md,
docs/api-resources.md, docs/api-operator-guide.md, docs/hyperfleet-api.http) to
use PUT for /clusters/{id}/statuses; if POST is still required, revert the
architecture change and update hyperfleet-adapter tests/mocks to POST; if both
are supported, add explicit compatibility notes and semantics for
/clusters/{id}/statuses across hyperfleet-api, hyperfleet-adapter, and
architecture docs so tests, examples, and mocks align with the agreed verb.

6. API aggregates adapter statuses → Updates cluster status
7. Cycle repeats until cluster reaches Ready phase
```
Expand Down
2 changes: 1 addition & 1 deletion hyperfleet/components/adapter/framework/adapter-deletion-flow-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -585,7 +585,7 @@ post:
post_actions:
- name: updateStatus
api_call:
method: POST
method: PUT
url: /clusters/{{ .clusterId }}/statuses
body: '{{ .clusterStatusPayload }}'
```
Expand Down
12 changes: 6 additions & 6 deletions hyperfleet/components/adapter/framework/adapter-design-decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ This document captures the key design decisions, trade-offs, and rationale behin
2. [Kubernetes Resource Management](#2-kubernetes-resource-management-vs-in-process-execution)
3. [Anemic Events Pattern](#3-anemic-events-pattern)
4. [Condition-Based Status Reporting](#4-condition-based-status-reporting)
5. [Adapters POST Status Updates](#5-adapters-post-status-updates)
5. [Adapters PUT Status Updates](#5-adapters-put-status-updates)
6. [Helm-Based Deployment](#6-helm-based-deployment)
7. [Layered Configuration Architecture](#7-layered-configuration-architecture)
8. [CEL Expression Language](#8-cel-expression-language)
Expand Down Expand Up @@ -178,20 +178,20 @@ observed_time: "..." # Timestamp when status was reported

---

## 5. Adapters POST Status Updates
## 5. Adapters PUT Status Updates
Comment thread
ma-hill marked this conversation as resolved.

**Decision:** Adapters POST status updates directly to HyperFleet API without checking if status exists first.
**Decision:** Adapters PUT status updates directly to HyperFleet API without checking if status exists first.

**Why:**
- **Simple flow** - single API call per status update
- **API handles create-or-update** - server-side logic determines if creating or updating
- **Idempotent** - same POST multiple times produces same result
- **Less latency** - no GET call before POST
- **Idempotent** - same PUT multiple times produces same result
- **Less latency** - no GET call before PUT
- **Stateless adapter** - adapter doesn't need to track if status exists

**Implementation:**
```
POST /api/hyperfleet/v1/clusters/{clusterId}/statuses
PUT /api/hyperfleet/v1/clusters/{clusterId}/statuses
{
"adapter": "validation",
"observed_generation": 1,
Expand Down
12 changes: 6 additions & 6 deletions hyperfleet/components/adapter/framework/adapter-flow-diagrams.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ sequenceDiagram
alt ClusterStatus exists (200 OK)
A->>API: PATCH /statuses/{statusId}<br/>Applied=False, Available=False, Health=True
else ClusterStatus not found (404)
A->>API: POST /statuses<br/>Applied=False, Available=False, Health=True
A->>API: PUT /statuses<br/>Applied=False, Available=False, Health=True
end

API-->>A: Status updated
Expand All @@ -148,7 +148,7 @@ sequenceDiagram
alt ClusterStatus exists (200 OK)
A->>API: PATCH /statuses/{statusId}<br/>Applied=True, Available=False, Health=True
else ClusterStatus not found (404)
A->>API: POST /statuses<br/>Applied=True, Available=False, Health=True
A->>API: PUT /statuses<br/>Applied=True, Available=False, Health=True
end

API-->>A: Status updated
Expand All @@ -165,7 +165,7 @@ sequenceDiagram
alt ClusterStatus exists (200 OK)
A->>API: PATCH /statuses/{statusId}<br/>Applied=True, Available=False, Health=True
else ClusterStatus not found (404)
A->>API: POST /statuses<br/>Applied=True, Available=False, Health=True
A->>API: PUT /statuses<br/>Applied=True, Available=False, Health=True
end

API-->>A: Status updated
Expand Down Expand Up @@ -396,7 +396,7 @@ sequenceDiagram
rect rgb(240, 255, 240)
Note over Adapter: Post-Processing (always runs)
Adapter->>Adapter: Evaluate conditions (CEL)
Adapter->>API: POST /resources/{id}/statuses (Applied=False)
Adapter->>API: PUT /resources/{id}/statuses (Applied=False)
end

Note over User, K8s: Phase 4 - API Aggregates & Deletes (Hierarchical)
Expand Down Expand Up @@ -524,12 +524,12 @@ sequenceDiagram
Sentinel->>Sub_Adapter: CloudEvent (subresource)
Sub_Adapter->>Sub_Adapter: Capture deleted_time, evaluate lifecycle.delete
Sub_Adapter->>Sub_Adapter: Clean up subresource resources (per-resource ordering)
Sub_Adapter->>API: POST status (Applied=False, Health=True, Finalized=True)
Sub_Adapter->>API: PUT status (Applied=False, Health=True, Finalized=True)
and Resource cleanup (in parallel)
Sentinel->>Res_Adapter: CloudEvent (resource)
Res_Adapter->>Res_Adapter: Capture deleted_time, evaluate lifecycle.delete
Res_Adapter->>Res_Adapter: Clean up resource resources (per-resource ordering)
Res_Adapter->>API: POST status (Applied=False, Health=True, Finalized=True)
Res_Adapter->>API: PUT status (Applied=False, Health=True, Finalized=True)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
end

API->>API: Subresource Reconciled=True?
Expand Down
8 changes: 4 additions & 4 deletions hyperfleet/components/adapter/framework/adapter-frame-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ graph TB
BrokerLib -->|Connects| MessageBroker
K8sClient -->|CRUD Operations| K8sAPI
APIClient -->|REST Calls| HyperFleetAPI
Reporter -->|POST Status| HyperFleetAPI
Reporter -->|PUT Status| HyperFleetAPI

Logger -.->|Used by| Components
Errors -.->|Used by| Components
Expand Down Expand Up @@ -772,7 +772,7 @@ subscriber.Subscribe(ctx, func(ctx context.Context, msg []byte) error {
- Build status payload with evaluated conditions and data
- Execute postActions (from `post.postActions`):
- Evaluate `when` condition (if specified)
- POST status payload to HyperFleet API endpoint
- PUT status payload to HyperFleet API endpoint
Comment thread
coderabbitai[bot] marked this conversation as resolved.
- Execute additional actions (e.g., logging)
- Acknowledge message to broker

Expand Down Expand Up @@ -972,9 +972,9 @@ These patterns align with the workflow described in [Adapter Flow Diagrams](./ad
- Kubernetes standard fields remain unchanged: `metadata.name`, `status.phase`

### Status Upsert Pattern
- Adapters POST status updates to HyperFleet API: `POST /api/hyperfleet/v1/clusters/{resourceId}/statuses`
- Adapters PUT status updates to HyperFleet API: `PUT /api/hyperfleet/v1/clusters/{resourceId}/statuses`
- API handles create-or-update logic server-side (idempotent)
- Same POST multiple times = same result
- Same PUT multiple times = same result
- Prevents race conditions between adapters

### Idempotency Pattern
Expand Down
8 changes: 4 additions & 4 deletions hyperfleet/components/adapter/framework/adapter-integration-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ pubsubContainer, err := testcontainers.GenericContainer(ctx, testcontainers.Gene
apiServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// Handle GET /clusters/{id}
// Handle GET /clusters/{id}/statuses
// Handle POST /clusters/{id}/statuses
// Handle PUT /clusters/{id}/statuses
// Handle PATCH /clusters/{id}/statuses/{statusId}
}))
defer apiServer.Close()
Expand All @@ -104,7 +104,7 @@ defer apiServer.Close()
**API Endpoints to Mock**:
- `GET /api/hyperfleet/v1/clusters/{clusterId}` - Return cluster object
- `GET /api/hyperfleet/v1/clusters/{clusterId}/statuses` - Return existing status or 404
- `POST /api/hyperfleet/v1/clusters/{clusterId}/statuses` - Create/upsert status
- `PUT /api/hyperfleet/v1/clusters/{clusterId}/statuses` - Create/upsert status
- `PATCH /api/hyperfleet/v1/clusters/{clusterId}/statuses/{statusId}` - Update status

**Request/Response Tracking**:
Expand Down Expand Up @@ -391,7 +391,7 @@ spec:
postActions:
- name: "reportStatus"
apiCall:
method: "POST"
method: "PUT"
url: "{{ .hyperfleetApiBaseUrl }}/api/hyperfleet/{{ .hyperfleetApiVersion }}/clusters/{{ .clusterId }}/statuses"
body: "{{ .statusPayload }}"
timeout: 30s
Expand Down Expand Up @@ -513,7 +513,7 @@ spec:
2. Wait for adapter to process event (max 5 seconds)
3. Verify API was called: `GET /clusters/cls-test-001`
4. Verify Job was created in Kubernetes
5. Verify status was reported: `POST /clusters/cls-test-001/statuses`
5. Verify status was reported: `PUT /clusters/cls-test-001/statuses`

**Expected Outcomes**:
- ✅ Event consumed from broker
Expand Down
2 changes: 1 addition & 1 deletion hyperfleet/components/adapter/framework/adapter-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ hyperfleet_adapter_resources_deleted_total{component="adapter-validation",versio
**Example**:
```prometheus
hyperfleet_adapter_api_requests_total{component="adapter-validation",version="v1.0.0",adapter_name="validation",api="hyperfleet",method="GET",endpoint="/clusters/{id}",status_code="200"} 1523
hyperfleet_adapter_api_requests_total{component="adapter-validation",version="v1.0.0",adapter_name="validation",api="hyperfleet",method="POST",endpoint="/statuses",status_code="200"} 1487
hyperfleet_adapter_api_requests_total{component="adapter-validation",version="v1.0.0",adapter_name="validation",api="hyperfleet",method="PUT",endpoint="/statuses",status_code="200"} 1487
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 14, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Method label enum is now inconsistent with the example.

After switching the example to method="PUT" (Line 225), the allowed-method list still omits PUT (Line 218). Update the label definition so instrumentation guidance is internally consistent.

🤖 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 `@hyperfleet/components/adapter/framework/adapter-metrics.md` at line 225, The
example metric hyperfleet_adapter_api_requests_total shows method="PUT" but the
allowed-method enum in the metric label definition omits PUT; update the label
definition for the method enum (the allowed-method list used for the method
label in the metric documentation/instrumentation guidance) to include "PUT"
alongside existing methods so the documentation and example for
hyperfleet_adapter_api_requests_total are consistent.

hyperfleet_adapter_api_requests_total{component="adapter-validation",version="v1.0.0",adapter_name="validation",api="kubernetes",method="POST",endpoint="/namespaces/{ns}/jobs",status_code="201"} 1432
hyperfleet_adapter_api_requests_total{component="adapter-validation",version="v1.0.0",adapter_name="validation",api="kubernetes",method="GET",endpoint="/namespaces/{ns}/jobs/{name}",status_code="200"} 2145
```
Expand Down
24 changes: 12 additions & 12 deletions hyperfleet/components/adapter/framework/adapter-status-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,31 +71,31 @@ This document defines the contract between HyperFleet adapters and the HyperFlee
**Base URL**: `{hyperfleetApiBaseUrl}/api/hyperfleet/{hyperfleetApiVersion}/clusters/{clusterId}/statuses`

**Method**:
- `POST` - Upsert ClusterStatus (create or update)
- `PUT` - Upsert ClusterStatus (create or update)

### Upsert Pattern

Adapters **always use POST** for status reporting:
Adapters **always use PUT** for status reporting:

**API Behavior**:
- The HyperFleet API handles the upsert logic server-side
- If ClusterStatus doesn't exist: API creates it
- If ClusterStatus exists: API updates the adapter's status within it
- Idempotent: Same POST multiple times = same result
- Idempotent: Same PUT multiple times = same result

**Adapter Implementation**:
- No need to GET first to check if status exists
- Always POST to the same endpoint
- Always PUT to the same endpoint
- API handles create-or-update logic automatically
- Simpler adapter code, fewer HTTP requests

---

## Status Payload Structure

### POST Request (Upsert ClusterStatus)
### PUT Request (Upsert ClusterStatus)

Always POST the adapter status in this structure:
Always PUT the adapter status in this structure:
Comment thread
ma-hill marked this conversation as resolved.

```json
{
Expand Down Expand Up @@ -136,7 +136,7 @@ Always POST the adapter status in this structure:

**Notes**:
- The API will upsert this adapter status (create or update based on adapter name)
- Other adapter statuses for this cluster are preserved (not affected by this POST)
- Other adapter statuses for this cluster are preserved (not affected by this PUT)
- API will set `created_time` and `last_report_time` automatically
- API will add `last_transition_time` to each condition automatically

Expand Down Expand Up @@ -637,7 +637,7 @@ post:
description: "Example resource must exist"
postActions:
- type: "api_call"
method: "POST"
method: "PUT"
endpoint: "{{ .hyperfleetApiBaseUrl }}/api/{{ .hyperfleetApiVersion }}/clusters/{{ .clusterId }}/statuses"
headers:
Comment on lines +640 to 642
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 14, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Framework config endpoint path is inconsistent with this document’s own status endpoint contract.

Line 641 uses /api/{{ .hyperfleetApiVersion }}/clusters/.../statuses, but the contract at Line 71 includes /api/hyperfleet/{hyperfleetApiVersion}/.... Please make both path shapes consistent.

As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."

🤖 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 `@hyperfleet/components/adapter/framework/adapter-status-contract.md` around
lines 640 - 642, The endpoint path in the example uses "/api/{{
.hyperfleetApiVersion }}/clusters/{{ .clusterId }}/statuses" which does not
match this doc’s contract that expects
"/api/hyperfleet/{hyperfleetApiVersion}/..."; update the endpoint template (the
endpoint value using .hyperfleetApiBaseUrl and .hyperfleetApiVersion) to include
the "hyperfleet" segment so it reads "/api/hyperfleet/{{ .hyperfleetApiVersion
}}/clusters/{{ .clusterId }}/statuses" (or alternatively change the contract at
its declaration to remove the "hyperfleet" segment) so both the endpoint in this
file and the contract at the earlier declaration are identical.

- name: "Authorization"
Expand All @@ -654,7 +654,7 @@ post:
3. **Evaluate Conditions**: Evaluate CEL expressions for applied, available, health
4. **Evaluate Data**: Evaluate CEL expressions for custom data fields
5. **Build Payload**: Construct status payload with conditions and data
6. **Execute PostActions**: POST to HyperFleet API endpoint
6. **Execute PostActions**: PUT to HyperFleet API endpoint

---

Expand All @@ -675,7 +675,7 @@ Content-Type: application/json
### Example Request

```http
POST /api/v1/clusters/cls-123/statuses HTTP/1.1
PUT /api/v1/clusters/cls-123/statuses HTTP/1.1
Comment thread
ma-hill marked this conversation as resolved.
Host: api.hyperfleet.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Expand Down Expand Up @@ -769,9 +769,9 @@ Use the `data` field for adapter-specific structured data that other components

Report adapter errors with `Health=False` and appropriate error messages.

### 8. Always Use POST
### 8. Always Use PUT

Always POST to the same endpoint - the API handles upsert logic server-side for idempotency.
Always PUT to the same endpoint - the API handles upsert logic server-side for idempotency.

### 9. Conditions: reason and message Are Optional

Expand Down
8 changes: 4 additions & 4 deletions hyperfleet/components/api-service/api-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The API is intentionally simple by design — it stores state and aggregates ada
graph TD
User([User / Operator]) -->|CRUD /clusters /nodepools| API[HyperFleet API\nport :8000]
Sentinel[Sentinel] -->|Poll GET /clusters?labels=...| API
Adapter[Adapters] -->|POST /clusters/:id/statuses| API
Adapter[Adapters] -->|PUT /clusters/:id/statuses| API
API -->|Read/Write| DB[(PostgreSQL)]
API -->|Expose| Health[Health :8080\n/healthz /readyz]
API -->|Expose| Metrics[Metrics :9090\n/metrics]
Expand All @@ -54,7 +54,7 @@ The primary HyperFleet resource. A cluster tracks desired state (`spec`) and cur
| `/api/hyperfleet/v1/clusters/{id}` | GET | Get cluster by ID |
| `/api/hyperfleet/v1/clusters/{id}` | PATCH | Update cluster spec |
| `/api/hyperfleet/v1/clusters/{id}/statuses` | GET | List adapter status reports |
| `/api/hyperfleet/v1/clusters/{id}/statuses` | POST | Report adapter status |
| `/api/hyperfleet/v1/clusters/{id}/statuses` | PUT | Report adapter status |

#### Node Pools

Expand All @@ -66,7 +66,7 @@ Groups of compute nodes nested under a cluster.
| `/api/hyperfleet/v1/clusters/{id}/nodepools` | GET | List node pools for a cluster |
| `/api/hyperfleet/v1/clusters/{id}/nodepools` | POST | Create node pool |
| `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}` | GET | Get node pool |
| `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` | POST | Report adapter status |
| `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` | PUT | Report adapter status |

Both resources support:
- **Pagination**: `page` and `size` query parameters
Expand Down Expand Up @@ -109,7 +109,7 @@ The `Ready` condition determines if the "state of the world" have been reconcile

It is computed out of the different status reports coming from adapters that have to provide information about the their validity at current API resource `generation`

This aggregated `Ready` condition is the primary signal consumed by Sentinel's CEL decision logic. The API performs this aggregation on every `POST /statuses` call so Sentinel always reads current state.
This aggregated `Ready` condition is the primary signal consumed by Sentinel's CEL decision logic. The API performs this aggregation on every `PUT /statuses` call so Sentinel always reads current state.

### Generation Tracking

Expand Down
14 changes: 7 additions & 7 deletions hyperfleet/components/api-service/hard-delete-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,13 @@ Last Updated: 2026-04-23

### Overview

The API hard-deletes DB records within the same `POST /adapter_statuses` request that computes `Reconciled=True`. No new endpoint or component is introduced. The API is the natural owner because it receives every adapter status report, aggregates conditions to compute `Reconciled`, and can hard-delete atomically within the same database transaction.
The API hard-deletes DB records within the same `PUT /api/hyperfleet/v1/clusters/{cluster_id}/statuses` request that computes `Reconciled=True`. No new endpoint or component is introduced. The API is the natural owner because it receives every adapter status report, aggregates conditions to compute `Reconciled`, and can hard-delete atomically within the same database transaction.

### Service-Layer Ordering Enforcement (Primary Control)

The **service layer** is the primary enforcement mechanism for bottom-up deletion ordering. This is a business rule, not a database concern.

When the API receives `POST /clusters/{id}/adapter_statuses` with `Finalized=True`, the service layer:
When the API receives `PUT /api/hyperfleet/v1/clusters/{cluster_id}/statuses` with `Finalized=True`, the service layer:

1. Stores the adapter conditions as reported
2. Computes `Reconciled` by checking **both**:
Expand Down Expand Up @@ -94,13 +94,13 @@ sequenceDiagram
Sentinel-->>NPAdapter: CloudEvent (nodepool)

CLAdapter->>CLAdapter: Clean up cluster-level K8s resources
CLAdapter->>API: POST /clusters/{id}/adapter_statuses (Finalized=True)
CLAdapter->>API: PUT /api/hyperfleet/v1/clusters/{cluster_id}/statuses (Finalized=True)
API->>DB: Store cluster adapter conditions as reported
API->>DB: Reconciled=False (nodepools still exist)
API-->>CLAdapter: 200 OK

NPAdapter->>NPAdapter: Clean up nodepool-level K8s resources
NPAdapter->>API: POST /nodepools/{id}/adapter_statuses (Finalized=True)
NPAdapter->>API: PUT /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses (Finalized=True)
API->>DB: Store nodepool adapter conditions as reported
API->>DB: Nodepool Reconciled=True
API->>DB: DELETE nodepool record and adapter_statuses
Expand All @@ -109,7 +109,7 @@ sequenceDiagram
Sentinel->>API: Poll: cluster Reconciled=False
Sentinel-->>CLAdapter: CloudEvent (cluster)

CLAdapter->>API: POST /clusters/{id}/adapter_statuses (Finalized=True)
CLAdapter->>API: PUT /api/hyperfleet/v1/clusters/{cluster_id}/statuses (Finalized=True)
API->>DB: Store cluster adapter conditions as reported
API->>DB: Reconciled=True (no nodepools remain)
API->>DB: DELETE cluster record and adapter_statuses
Expand All @@ -131,7 +131,7 @@ sequenceDiagram
participant API
participant DB

CLAdapter->>API: POST /clusters/{id}/adapter_statuses (Finalized=True)
CLAdapter->>API: PUT /api/hyperfleet/v1/clusters/{cluster_id}/statuses (Finalized=True)
API->>DB: BEGIN TRANSACTION
API->>DB: Store cluster adapter conditions
API->>DB: Compute Reconciled=True (no nodepools remain)
Expand All @@ -146,7 +146,7 @@ sequenceDiagram
API-->>CLAdapter: 500 Internal Server Error
Note over DB: Cluster remains with deleted_time set, Reconciled=False
Note over CLAdapter: Sentinel will re-trigger on next poll cycle
CLAdapter->>API: POST /clusters/{id}/adapter_statuses (Finalized=True)
CLAdapter->>API: PUT /api/hyperfleet/v1/clusters/{cluster_id}/statuses (Finalized=True)
Note over API: Retry hard-delete logic
end
```
Expand Down
Loading