Draft: HYPERFLEET-732 - feat: add UUID field to Cluster and NodePool resources

[86254860]

Summary

Add optional RFC4122 UUID identifier field to Cluster and NodePool models to support platform integrations requiring UUID format (e.g., Hypershift spec.clusterID). The UUID is immutable and assigned at creation time, providing a stable, standards-compliant identifier alongside the existing ID field. Updated TypeSpec models, examples, and regenerated OpenAPI/Swagger schemas.

Summary by CodeRabbit

• New Features

  • Cluster and NodePool resources now expose an RFC4122-format UUID, immutable and assigned at creation; create responses include the uuid.

• Documentation

  • API schemas, examples, and documentation updated to surface the new uuid fields across core and GCP specs; API version bumped to 1.0.5.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign vkareh for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

Walkthrough

This PR introduces a new optional uuid field (annotated with @format("uuid") and examples) to Cluster and NodePool models and example objects across core and GCP modules. OpenAPI/Swagger documents and example payloads are updated to include uuid, and the service OpenAPI version is bumped to 1.0.5. No control flow, validation rules, or other fields were changed; uuid is described as an immutable identifier assigned at creation.

Sequence Diagram(s)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly summarizes the main change: adding a UUID field to Cluster and NodePool resources, which aligns with the comprehensive changeset modifications across all model and schema files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

schemas/core/openapi.yaml (1)

832-839: Clarify create-time ownership semantics for uuid.

The field is documented as “immutable, assigned at creation,” but create payloads also accept caller-provided uuid. Please explicitly define behavior (service-generated when omitted vs caller-supplied allowed, and duplicate conflict behavior such as 409) to avoid integration ambiguity.

Also applies to: 1112-1119

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@schemas/core/openapi.yaml` around lines 832 - 839, Update the "uuid" schema
description to explicitly state create-time ownership and conflict behavior:
indicate that the service will generate a RFC4122 UUID when the client omits the
"uuid", that clients are allowed to supply their own "uuid" on create
(caller-supplied accepted), and define the conflict semantics (e.g., a 409
Conflict is returned if a supplied UUID already exists). Apply the same
clarification to the duplicate "uuid" occurrences noted (the block at 1112-1119)
and ensure the wording mentions immutability after creation and that updates to
"uuid" are rejected.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@schemas/core/openapi.yaml`:
- Around line 832-839: Update the "uuid" schema description to explicitly state
create-time ownership and conflict behavior: indicate that the service will
generate a RFC4122 UUID when the client omits the "uuid", that clients are
allowed to supply their own "uuid" on create (caller-supplied accepted), and
define the conflict semantics (e.g., a 409 Conflict is returned if a supplied
UUID already exists). Apply the same clarification to the duplicate "uuid"
occurrences noted (the block at 1112-1119) and ensure the wording mentions
immutability after creation and that updates to "uuid" are rejected.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5b765f25-8c3d-444b-961b-b36adb12dd99

📥 Commits

Reviewing files that changed from the base of the PR and between ebeb009 and ee46936.

📒 Files selected for processing (10)

• models-core/cluster/example_cluster.tsp
• models-core/nodepool/example_nodepool.tsp
• models-gcp/cluster/example_cluster.tsp
• models-gcp/nodepool/example_nodepool.tsp
• models/clusters/model.tsp
• models/nodepools/model.tsp
• schemas/core/openapi.yaml
• schemas/core/swagger.yaml
• schemas/gcp/openapi.yaml
• schemas/gcp/swagger.yaml

[86254860]

/hold This method might be replaced by the method that change the existing ID field to RFC4122.