fix(rest-api): OS imageUrl/imageSha are immutable on update and change attempt should fail

[pbreton]

The operating-system PATCH validation advertised imageUrl/imageSha as patchable and forced them to be sent together, but site sync forwards those to Core's UpdateOsImage, which rejects any change to source_url/digest as read-only ("os_image update read-only attributes changed"). Callers who only wanted to rotate an image auth token were also blocked, since imageAuthToken could not be sent without imageUrl.

Align the API layer with the immutable-image design: reject changes to imageUrl/imageSha up front with a clear 400 (re-sending the current value stays a no-op), and allow imageAuthType/imageAuthToken to be updated on image-based OS without re-sending imageUrl/imageSha. Update the OpenAPI descriptions and the model/handler tests to match.

Type of Change

• Add - New feature or capability
• Change - Changes in existing functionality
• Fix - Bug fixes
• Remove - Removed features or deprecated functionality
• Internal - Internal changes (refactoring, tests, docs, etc.)

Breaking Changes

• This PR contains breaking changes

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• No testing required (docs, internal refactor, etc.)

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

💤 Files selected but had no reviewable changes (1)

• rest-api/docs/index.html

⛔ Files ignored due to path filters (2)

• rest-api/sdk/standard/client.go is excluded by !rest-api/sdk/standard/client.go
• rest-api/sdk/standard/model_operating_system_update_request.go is excluded by !rest-api/sdk/standard/model_*.go

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 61342595-c1a3-4445-9aea-aea65efb4984

📥 Commits

Reviewing files that changed from the base of the PR and between 6264443 and 4eaca55.

⛔ Files ignored due to path filters (2)

• rest-api/sdk/standard/client.go is excluded by !rest-api/sdk/standard/client.go
• rest-api/sdk/standard/model_operating_system_update_request.go is excluded by !rest-api/sdk/standard/model_*.go

📒 Files selected for processing (1)

• rest-api/docs/index.html

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

OperatingSystem update validation now rejects changes to ImageURL and ImageSHA after creation, while allowing mutable image auth and rootfs fields to be updated. Handler tests, model tests, and OpenAPI descriptions were updated to match.

Changes

Image immutability validation

Layer / File(s)	Summary
Validation logic for image immutability rest-api/api/pkg/api/model/operatingsystem.go	Rejects ImageURL/ImageSHA changes after creation, validates image fields only when present, and forbids ImageURL for non-image-based updates.
Model validation tests rest-api/api/pkg/api/model/operatingsystem_test.go	Covers unchanged and changed image fields, auth-field updates, iPXE auth rejection, and rootfs update requests without unrelated image fields.
Handler update expectations rest-api/api/pkg/api/handler/operatingsystem_test.go	Verifies image SHA fixtures, unchanged ImageURL on success, 400 rejection for ImageURL changes, and 500 on workflow timeout with the immutable-image request shape.
OpenAPI descriptions rest-api/openapi/spec.yaml	Updates request and property descriptions to state immutability after creation and independent auth-field updates.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: OS imageUrl/imageSha are now immutable and change attempts are rejected.
Description check	✅ Passed	The description accurately covers the validation fix, auth-token update allowance, and related OpenAPI and test updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

🔍 Container Scan Summary

Service	Total	Critical	High	Medium	Low	Other
nico-flow	15	1	3	3	0	8
nico-nsm	7	0	1	5	0	1
nico-psm	15	1	3	3	0	8
nico-rest-api	17	1	4	4	0	8
nico-rest-cert-manager	14	1	3	3	0	7
nico-rest-db	15	1	3	3	0	8
nico-rest-site-agent	15	1	3	3	0	8
nico-rest-site-manager	14	1	3	3	0	7
nico-rest-workflow	15	1	3	3	0	8
TOTAL	127	8	26	30	0	63

Per-CVE detail lives in the per-service grype-* artifacts (JSON + SARIF). Severity counts only — no CVE IDs published here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pull-request-3294.docs.buildwithfern.com/infra-controller

[github-actions]

🔐 TruffleHog Secret Scan

✅ No secrets or credentials found!

Your code has been scanned for 700+ types of secrets and credentials. All clear! 🎉

🔗 View scan details

_{🕐 Last updated: 2026-07-09 01:19:36 UTC | Commit: b3eb803}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with 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.

Inline comments:
In `@rest-api/api/pkg/api/handler/operatingsystem_test.go`:
- Around line 1741-1769: The new table-driven cases in operatingsystem_test.go
depend on a valid ImageSHA fixture, but the current test data prevents the
intended update paths from being exercised. Update the relevant OS fixture/setup
used by os5/os9 so the image OS entries have a correct ImageSHA value, and keep
the unchanged-imageURL and change-rejected cases wired through
updReqValidImageUrl, okBodyImageUrl, and errBodyChangeImageUrl so the success,
400, and timeout scenarios reach the expected handlers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 41aa0382-da61-406e-88aa-758fc5b515a2

📥 Commits

Reviewing files that changed from the base of the PR and between 9e512e3 and b3eb803.

📒 Files selected for processing (4)

• rest-api/api/pkg/api/handler/operatingsystem_test.go
• rest-api/api/pkg/api/model/operatingsystem.go
• rest-api/api/pkg/api/model/operatingsystem_test.go
• rest-api/openapi/spec.yaml

[nvlitagaki]

Rather than simply updating the descriptions of the open API spec to tell users that updates to imageUrl and imageSha will be rejected, wouldn't it be more clear if we deprecated those fields on OperaingSystemUpdateRequest?

[nvlitagaki]

It looks like core logic also rejects changes to the rootFsId and rootFsLabel fields, so could we make similar changes to the API for those fields as well?

Edit: Nvm, I just saw your comment about limiting the scope of this work. We should probably make sure that the need to make the fix on those fields too is documented as a separate work item if it isn't already.

[thossain-nv]

Looks good @pbreton, left one suggestion.