HYPERFLEET-114: Add the hyperfleet api journey #3
Conversation
yingzhanredhat
force-pushed
the
ying-cuj
branch
from
4c91b94 to
4a4cb21
Compare
yingzhanredhat
force-pushed
the
ying-cuj
branch
5 times, most recently
from
12da68f to
bbea23e
Compare
yingzhanredhat
force-pushed
the
ying-cuj
branch
from
bbea23e to
f557145
Compare
| "region": "us-east1", | ||
| "nodeCount": 3 | ||
| }, | ||
| "status": { |
There was a problem hiding this comment.
I would just add a comment that the status has more information as defined here: https://github.com/openshift-hyperfleet/architecture/pull/15/files#diff-68f9f8913b8bb6ffd0831939a808049c6972f7e4b634cf76283580c77362ee94R707
Example:
"status": {
"phase": ""
"phaseDescription": ""
"conditions": {...}
"adapters": {...}
}There was a problem hiding this comment.
@rafabene The logic should be like: create cluster with request body --> the return response has all the fileds,right ? What are the init values? (If the logic is right. and the init status si still in design progress, I can don't add the detailed content in the journey doc)
"status": {
"phase": ""
"phaseDescription": ""
"conditions": {...}
"adapters": {...}
}
| HTTP 200 OK | ||
| { | ||
| "cluster_id": "550e8400-e29b-41d4-a716-446655440000", | ||
| "statuses": [ |
There was a problem hiding this comment.
Align with ClusterStatus Object Structure https://github.com/openshift-hyperfleet/architecture/blob/main/hyperfleet/docs/status-guide.md#clusterstatus-object-structure
| "region": "us-east1", | ||
| "nodeCount": 3 | ||
| }, | ||
| "status": { |
| "region": "us-east1", | ||
| "nodeCount": 3 | ||
| }, | ||
| "status": { |
| "nodeCount": 3 | ||
| }, | ||
| "status": { | ||
| "phase": "Ready", |
| "nodeCount": 3 | ||
| }, | ||
| "status": { | ||
| "phase": "Ready", |
| "nodeCount": 2 | ||
| }, | ||
| "status": { | ||
| "phase": "Not Ready", |
| "nodeCount": 2 | ||
| }, | ||
| "status": { | ||
| "phase": "Not Ready", |
| "region": "us-east1", | ||
| "nodeCount": 3 | ||
| }, | ||
| "status": { |
| "region": "us-east1", | ||
| "nodeCount": 3 | ||
| }, | ||
| "status": { |
| "nodeCount": 5 | ||
| }, | ||
| "status": { | ||
| "phase": "Not Ready", |
| HTTP 200 OK | ||
| { | ||
| "cluster_id": "550e8400-e29b-41d4-a716-446655440000", | ||
| "statuses": [ |
There was a problem hiding this comment.
Align with ClusterStatus Object Structure https://github.com/openshift-hyperfleet/architecture/blob/main/hyperfleet/docs/status-guide.md#clusterstatus-object-structure
| "machineType": "n1-standard-4" | ||
| }, | ||
| "status": { | ||
| "phase": "Pending", |
There was a problem hiding this comment.
nodepools will also have aggregated status return
| "machineType": "n1-standard-4" | ||
| }, | ||
| "status": { | ||
| "phase": "Not Ready", |
| "machineType": "n1-standard-4" | ||
| }, | ||
| "status": { | ||
| "phase": "Ready", |
| "machineType": "n1-standard-4" | ||
| }, | ||
| "status": { | ||
| "phase": "Ready", |
| "machineType": "n1-highmem-8" | ||
| }, | ||
| "status": { | ||
| "phase": "Not Ready", |
| "machineType": "n1-highmem-8" | ||
| }, | ||
| "status": { | ||
| "phase": "Not Ready", |
| "nodeCount": 8, | ||
| "machineType": "n1-standard-8" | ||
| }, | ||
| "status": { |
| "machineType": "n1-standard-8" | ||
| }, | ||
| "status": { | ||
| "phase": "Terminating", |
|
After reviewing the status guide documentation, I've confirmed the ✅ GET/POST
|
| Endpoint | Field Name | Content |
|---|---|---|
/clusters/{id}/statuses |
adapterStatuses |
Detailed adapter statuses (full conditions, data, metadata) |
/clusters/{id} |
status.adapters |
Aggregated summary (name, available, observedGeneration) |
Key Points:
/statusesendpoint provides the detailed status resource with all
adapter information/clustersand/nodepoolsendpoint provides the cluster resource and nodepools resource with aggregated
status summary
|
|
||
| --- | ||
|
|
||
| ## Journey 5: Delete Cluster (Deprovisioning) (Post-MVP) |
There was a problem hiding this comment.
Is this really a post MVP journey? Deleting a cluster seems like a critical path to prevent excessive resource accumulation during testing/development.
There was a problem hiding this comment.
It seems yes. I got the information from the Jira description. https://issues.redhat.com/browse/HYPERFLEET-120
|
|
||
| **System Response / User Sees:** | ||
| ```json | ||
| HTTP 202 Accepted |
There was a problem hiding this comment.
Does a 204 make more sense here? I'm not sure we need to return the whole cluster object on a successful delete.
| @@ -0,0 +1,1277 @@ | |||
| # HyperFleet API - Customer Critical Journey | |||
|
|
|||
| ## Overview | |||
There was a problem hiding this comment.
It'd be nice if either in this section or an executive summary, we outlined at the top which user journeys are in scope and which are out of scope for MVP. That way we'll prevent people from scrolling down through all 10.
|
|
||
| This document maps the critical user journeys for internal users interacting with the HyperFleet API. Each journey includes user actions, system responses, and the architectural components involved in processing the request. | ||
|
|
||
| > **Note:** All API request/response payloads shown in this document are still in design progress and not the final version. They will be updated once the API specification is published. |
There was a problem hiding this comment.
I'd recommend either removing this if our payloads are finalized, or simplifying the sample responses in this document to be less specific if they're truly still in design.
There was a problem hiding this comment.
will simplify the request and response body
|
|
||
| ## Persona | ||
|
|
||
| **Internal Platform Engineer** |
There was a problem hiding this comment.
Can we expand a bit on this persona? I think we can add more depth for a CUJ here -
- What is this person trying to achieve? ("provision clusters in <10 minutes with zero manual intervention")
- What are their pain points? ("Managing multi-cloud clusters requires different tools/APIs for each provider")
- What are their current tools/workflow? ("Uses cloud CLIs and terraform, takes 2 hours per cluster")
- What is their success criteria? ("95% of clusters reach ready without manual intervention")
|
|
||
| --- | ||
|
|
||
| # Cluster Journeys |
There was a problem hiding this comment.
I think it could help to have a "pre-requisites" section here for things that happen before the user journey starts. For example, maybe things like "cloud provider credentials configured, HyperFleet deployed, API access set up", etc.
There was a problem hiding this comment.
Agree that.I will get more detailed inforamtion from team member to know which sectors are required in MVP phase.
| GET /api/hyperfleet/v1/clusters/550e8400-e29b-41d4-a716-446655440000/statuses | ||
| ``` | ||
|
|
||
| **System Response / User Sees (DNS Failure Example):** |
There was a problem hiding this comment.
It looks like both adapters completed successfully with all conditions showing "True". Let's update this to show the journey a bit more accurately.
|
|
||
| --- | ||
|
|
||
| ## Journey 6: Cluster Access Control and Permissions(Out of MVP) |
There was a problem hiding this comment.
Can we make this "Post-MVP" to match the others?
|
|
||
| --- | ||
|
|
||
| ## Journey 6: Cluster Access Control and Permissions(Out of MVP) |
There was a problem hiding this comment.
Can we elaborate a bit more on this journey? It does a good job of showing the access denial, but it'd be nice to have a complete workflow like the other journeys in this document. I'm thinking things like
- How User A sets up or configures permissions
- How user A would grant access to another user
- How the newly-granted user can successfully access the cluster
- The denial case
|
This is a comprehensive document with great detail, but it reads more like API specifications than a true CUJ document to me. It's also not immediately clear what's in scope for MVP vs Post-MVP, which I believe could be addressed with a quick summary up front. Overall I think we could add more information about user goals, context, and expected outcomes. I'd like to see more narrative context (why is the user doing this? what problem are they solving?) - maybe some diagrams or flow charts could help there. We may even want to consider moving the detailed JSON payloads out to a separate API spec to really show an emphasis on the user journey overall. |
|
|
||
| ## Overview | ||
|
|
||
| This document maps the critical user journeys for internal users interacting with the HyperFleet API. Each journey includes user actions, system responses, and the architectural components involved in processing the request. |
There was a problem hiding this comment.
Can we define what is an "internal user" ?
|
|
||
| **Note on Cluster Phase Values:** | ||
| The HyperFleet API uses the following cluster phase values in `status.phase`: | ||
| - **`Pending`** - Cluster created, waiting for initial adapter processing |
There was a problem hiding this comment.
I think pending and not ready are really the same
I don't think the subtle difference of "waiting for initial adapter processing" is meaningful for the user
There was a problem hiding this comment.
Will update it according to the latest status here https://github.com/openshift-hyperfleet/architecture/blob/main/hyperfleet/docs/status-guide.md#status-phases
| - **`Terminating`** - Cluster deletion initiated, cleanup in progress | ||
|
|
||
| Adapter phase values (in `statuses` table): | ||
| - **`Pending`** - Adapter hasn't started processing yet |
There was a problem hiding this comment.
I think is not yet decided if creating a cluster will create "empty" statuses for all adapters in "pending" state.
IMO most probable, creating a cluster will have an empty array of statuses and it will be populated as these start reporting back the state.
The API, needs to know at least "how many adapters need to be complete to consider the cluste ready" ?
| "spec": { | ||
| "provider": "gcp", | ||
| "region": "us-east1", | ||
| "nodeCount": 3 |
There was a problem hiding this comment.
NodePools will be created in a different API request.
We can create clusters with zero nodes.
So, the process will be:
- Make a cluster request -> will return a clusterId
- Make a nodepool request -> node creation will wait until cluster is
ready
There was a problem hiding this comment.
- Will remove all the node related configures from the cluster request body.
- Does it allow to create a nodepool to a not ready cluster ?
| "status": { | ||
| "phase": "Not Ready", | ||
| "lastTransitionTime": "2025-10-28T12:00:15Z" |
There was a problem hiding this comment.
The cluster.status will contain also an array of adapter conditions.
BUT not all adapter conditions, only the one named available
Why is this?
If cluster response contains this info, we can reduce the number of API calls from adapters to know the individual state of each adapter available, which is used in their pre-conditions to know if they have to do some work.
If we don't send this info in the cluste response, the adapters have to fetch both the cluster and the statuses.
well, writing this I realize that the adapters may not even require the cluster info after all, but only the /clusters/{cluster_id}/statuses ..... mmm... we need to confirm this
| @@ -0,0 +1,1277 @@ | |||
| # HyperFleet API - Customer Critical Journey | |||
There was a problem hiding this comment.
I have one suggestion for the document format.
As it is so big due to the many json examples, I tend to get lost into the details
It may be a good idea to use collapsed sections for the examples. wdyt?
(tip: you can ask cursor/claude to create the details and also the summary automatically 😉)
There was a problem hiding this comment.
Good idea.Let me update it
|
|
||
| ## Journey 3: List and Filter Clusters | ||
|
|
||
| ### Step 1: List All Clusters |
There was a problem hiding this comment.
Results will be paginated, here it shows the total property, but there will be also size and page
|
|
||
| **User Action:** | ||
| ```bash | ||
| GET /api/hyperfleet/v1/clusters?phase=Not%20Ready |
There was a problem hiding this comment.
Should the query be referring to the full property path? status.phase="Not%20Ready"
| ```json | ||
| HTTP 201 Created | ||
| { | ||
| "id": "my-nodepool", |
There was a problem hiding this comment.
I guess that my-nodepool will be the name, and the id will be a UUID?
5 participants
Add hyperfleet cluster and nodepool API critical user journey