Conversation
There was a problem hiding this comment.
Pull request overview
Adds documentation diagrams for the ARO-HCP resource creation flow, intended to explain the end-to-end path from ARM request handling in the frontend through async completion via backend controllers and Cluster Service/Maestro.
Changes:
- Add a Mermaid-based diagram document describing creation and async operation processing for HCP resources.
- Add a FreeMind mindmap version of the same flow.
- Link the new resource creation documentation from
docs/README.md.
Reviewed changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| docs/resource-creation.md | New Mermaid diagrams documenting frontend middleware, cluster/nodepool creation, and backend async operation processing. |
| docs/resource-creation.mm | New FreeMind mindmap capturing the same end-to-end creation flow details. |
| docs/README.md | Adds a table-of-contents entry pointing to the new resource creation diagram doc. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: swiencki The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
/retest |
Add comprehensive diagrams documenting the ARO-HCP resource creation flow from API request through async completion. Covers HCPOpenShiftCluster, NodePool, and ExternalAuth resource types. Includes frontend middleware chain, validation, Cluster Service interaction, backend controller architecture, and async operation lifecycle. Both Mermaid (.md for GitHub rendering) and FreeMind (.mm/.png) formats provided.
- Scope ShouldProcess description to operation controllers only - Fix NodePool PUT path to include parent cluster in URL - Fix async state diagram: Accepted->Failed is CS error, not validation - Fix "change feed" references to "periodic relist via expiring watchers" - Clarify ExternalAuth coverage in intro text - Regenerate PNG with white background
swiencki
force-pushed
the
resource-creation-diagram
branch
from
b37ff41 to
4abf5ff
Compare
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds documentation diagrams that explain the end-to-end ARO-HCP resource creation flow from the frontend API request through backend async completion, covering HCPOpenShiftCluster, NodePool, and ExternalAuth.
Changes:
- Added a Mermaid-based markdown document describing the resource creation and async operation flows.
- Added a FreeMind mind-map representation of the same flow.
- Linked the new documentation from
docs/README.md.
Reviewed changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/resource-creation.md | Adds Mermaid diagrams and narrative describing creation + async processing flows. |
| docs/resource-creation.mm | Adds a FreeMind mind-map version of the same flow for alternate viewing/editing. |
| docs/README.md | Adds a docs index entry linking to the new resource creation diagram doc. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Aspect | Classic ARO-RP | ARO-HCP | | ||
| |--------|---------------|---------| | ||
| | Control plane | Runs on dedicated VMs in customer VNet | Hosted on management cluster (HCP) | | ||
| | Backend | Directly installs cluster (phases, bootstrap VM) | Delegates to Cluster Service, polls for status | | ||
| | Install orchestration | RP backend runs install steps (Hive/Podman) | Cluster Service + Maestro + management cluster | | ||
| | Database | CosmosDB (single document per cluster) | CosmosDB (separate operation + resource docs, transactions) | | ||
| | Operation model | Provisioning state on cluster doc, polled via async op record | Dedicated operation documents, periodic relist via expiring watchers triggers controllers | | ||
| | Node pools | Managed by machine-api operator after bootstrap | First-class ARM resource with own lifecycle | | ||
| | Resource types | OpenShiftCluster only | HCPOpenShiftCluster, NodePool, ExternalAuth | |
There was a problem hiding this comment.
The markdown table uses double-leading pipes (|| ...) on each row, which typically renders incorrectly (extra empty column / broken table) in Markdown viewers. Update the table to standard Markdown table syntax using single-leading pipes (| ... | ... | ... |) for all rows including the header and separator.
| - [Resource Creation Diagram](resource-creation.md) | ||
| - Detailed diagram of the resource creation flow (frontend, backend, Cluster Service, Maestro) | ||
| - Covers HCPOpenShiftCluster, NodePool, and ExternalAuth resource types |
There was a problem hiding this comment.
PR description says both FreeMind (.mm/.png) formats are provided, but in the shown diff only the .mm file is added and the README links only the .md. Either add the referenced .png (and/or link to the .mm/.png in the README), or adjust the PR description to match what’s actually included.
| @@ -0,0 +1,192 @@ | |||
| <map version="1.0.1"> | |||
| <!-- To view this file, download free mind mapping software FreeMind from http://freemind.sourceforge.net --> | |||
There was a problem hiding this comment.
This comment points to an http:// URL. Prefer https:// where available to avoid training readers toward insecure links. If the upstream doesn’t support HTTPS, consider updating the comment to a more general pointer (or to a maintained viewer) rather than a direct insecure URL.
| <!-- To view this file, download free mind mapping software FreeMind from http://freemind.sourceforge.net --> | |
| <!-- To view this file, download free mind mapping software FreeMind from https://freemind.sourceforge.net --> |
What
Add comprehensive diagrams documenting the ARO-HCP resource creation flow from API request through async completion. Covers HCPOpenShiftCluster, NodePool, and ExternalAuth resource types. Both Mermaid (.md) and FreeMind (.mm/.png) formats provided. Link added to docs/README.md.
Why
No existing diagram documents the end-to-end resource creation flow through frontend middleware, Cluster Service, and backend controller architecture. This makes onboarding and cross-team understanding harder than it needs to be.
Special notes for your reviewer
frontend/pkg/frontend/routes.go, backend trigger mechanism vsbackend/pkg/informers/, CS state mapping vsbackend/pkg/controllers/operationcontrollers/utils.go