feat: Need to be able to update siteconfig from the API

[nvaprado]

Is this a new feature, an enhancement, or a change to existing functionality?

New Feature

How would you describe the priority of this feature request

Medium

Please provide a clear description of problem this feature solves

Needed to go to the database directly

update site set config='{"native_networking": true, "network_security_group": true, "nvlink_partition": true}' where name='xxx-1';

as per @bcavnvidia , we need an API to allow for updating the siteconfig

Feature Description

As an operator of the site I don't want to go to the database to update site configs

Describe your ideal solution

No response

Describe any alternatives you have considered

No response

Additional context

No response

Code of Conduct

• I agree to follow NCX Infra Controller's Code of Conduct
• I have searched the open feature requests and have found no duplicates for this feature request

[bcavnvidia]

I think either we need a way to update this from the API or we need some policy around when things are permanently enabled and how.

[thossain-nv]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Extend the existing PATCH /site/{id} endpoint rather than creating a separate config endpoint, maintaining API simplicity and leveraging existing DB infrastructure
• Add a nested capabilities request model with pointer fields to enable partial/sparse updates via JSON omitempty serialization
• Enforce provider-only access through the existing role-based validation pattern using validation.Nil for tenant callers
• Map API camelCase request fields to DB snake_case fields through a dedicated conversion function, preserving layer separation

Design Choices

Design Choice 1: Should config updates be exposed through the existing PATCH /site/{id} endpoint or a new dedicated endpoint?

Options Considered:

1. Extend existing PATCH /v2/org/{org}/carbide/site/{siteId} to accept capabilities fields alongside other site fields
2. Create new PATCH /v2/org/{org}/carbide/site/{siteId}/config as a separate endpoint

Chosen Option: 1

Rationale: Extending the existing endpoint maintains API consistency (single resource, single update endpoint), avoids route proliferation, and leverages the already-prepared DB layer that expects config as part of SiteUpdateInput.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: API Model Layer Enhancement

Extend the API request model to accept site capabilities for update, maintaining consistency with the existing response model structure and enabling partial updates through pointer-typed fields.

Task 1: Create Capabilities Update Request Model

Define a new request model for accepting capabilities updates with proper JSON serialization for partial update semantics.

• Create APISiteCapabilitiesUpdateRequest struct in api/pkg/api/model/site.go with pointer fields matching APISiteCapabilities semantics: NativeNetworking *bool, NetworkSecurityGroup *bool, NVLinkPartition *bool, RackLevelAdministration *bool, ImageBasedOperatingSystem *bool
• Use omitempty JSON tags on all fields to support sparse/partial updates
• Follow camelCase JSON naming convention consistent with existing API response models

Task 2: Extend APISiteUpdateRequest

Add capabilities field to the existing site update request structure.

• Add Capabilities *APISiteCapabilitiesUpdateRequest field to APISiteUpdateRequest in api/pkg/api/model/site.go
• Use JSON tag json:"capabilities,omitempty" for optional inclusion

Task 3: Implement Validation for Capabilities

Add validation logic to enforce provider-only access for capabilities modification.

• Extend APISiteUpdateRequest.Validate(isProvider, isTenant bool) method in api/pkg/api/model/site.go
• In the non-provider (tenant) validation branch, add validation.Nil rule for Capabilities field with error message "value is not configurable by Tenant"
• No additional validation constraints needed for individual capability boolean fields

🤖 Prompt for AI agents

Extend the API model layer in `api/pkg/api/model/site.go` to introduce
capabilities update support with correct partial-update semantics and role-based
validation.

- Define a new struct `APISiteCapabilitiesUpdateRequest` with the following
pointer-typed fields, each tagged with `omitempty` camelCase JSON keys to enable
sparse updates:
  - `NativeNetworking *bool` → `json:"nativeNetworking,omitempty"`
  - `NetworkSecurityGroup *bool` → `json:"networkSecurityGroup,omitempty"`
  - `NVLinkPartition *bool` → `json:"nvLinkPartition,omitempty"`
  - `RackLevelAdministration *bool` → `json:"rackLevelAdministration,omitempty"`
- `ImageBasedOperatingSystem *bool` →
`json:"imageBasedOperatingSystem,omitempty"`
- Add `Capabilities *APISiteCapabilitiesUpdateRequest` to the existing
`APISiteUpdateRequest` struct with tag `json:"capabilities,omitempty"`
- In `APISiteUpdateRequest.Validate(isProvider, isTenant bool)`, within the
non-provider (tenant) validation branch, add a `validation.Nil` rule targeting
the `Capabilities` field with the error message `"value is not configurable by
Tenant"`

Phase 2: Handler Logic Integration

Wire the API request model through the handler to the database layer, leveraging the existing SiteConfigUpdateInput infrastructure.

Task 1: Create Model Conversion Function

Implement a conversion function from API request model to DB input model with proper field mapping.

• Create apiSiteCapabilitiesUpdateRequestToSiteConfigUpdateInput() function in api/pkg/api/handler/site.go
• Map each APISiteCapabilitiesUpdateRequest pointer field to corresponding SiteConfigUpdateInput field (e.g., NativeNetworking → NativeNetworking, NetworkSecurityGroup → NetworkSecurityGroup)
• Return nil if input is nil to preserve existing partial-update semantics

Task 2: Integrate Config into UpdateSiteHandler

Modify the handler to pass capabilities through to the database layer.

• In UpdateSiteHandler.Handle() within api/pkg/api/handler/site.go, after constructing siteUpdateInput (approximately line 473-503)
• Add assignment: siteUpdateInput.Config = apiSiteCapabilitiesUpdateRequestToSiteConfigUpdateInput(apiRequest.Capabilities)
• This leverages the existing DB layer JSONB merge logic without modification

🤖 Prompt for AI agents

Wire the new capabilities request model through the handler layer to the
existing database infrastructure in `api/pkg/api/handler/site.go`.

- Implement a new function
`apiSiteCapabilitiesUpdateRequestToSiteConfigUpdateInput()` that:
  - Accepts a `*APISiteCapabilitiesUpdateRequest` argument
- Returns `nil` immediately if the input is `nil`, preserving partial-update
semantics
- Otherwise, maps each pointer field from `APISiteCapabilitiesUpdateRequest` to
the corresponding field in `SiteConfigUpdateInput` (e.g., `NativeNetworking` →
`NativeNetworking`, `NetworkSecurityGroup` → `NetworkSecurityGroup`, and so on
for all five fields)
- In `UpdateSiteHandler.Handle()`, after the `siteUpdateInput` struct is
constructed (approximately lines 473–503), add the following assignment:
- `siteUpdateInput.Config =
apiSiteCapabilitiesUpdateRequestToSiteConfigUpdateInput(apiRequest.Capabilities)`
- No modifications to the DB layer are required; the existing JSONB merge logic
in `SiteSQLDAO.Update()` handles the rest

Phase 3: OpenAPI Specification Update

Document the new API capability in the OpenAPI specification for client generation and documentation purposes.

Task 1: Define SiteCapabilitiesUpdateRequest Schema

Add the new request schema to the OpenAPI components.

• Add SiteCapabilitiesUpdateRequest schema to components/schemas section in openapi/spec.yaml
• Define all five boolean properties: nativeNetworking, networkSecurityGroup, nvLinkPartition, rackLevelAdministration, imageBasedOperatingSystem
• Mark all properties as optional (no required array) to support partial updates

Task 2: Extend SiteUpdateRequest Schema

Add capabilities reference to the existing update request schema.

• Add capabilities property to SiteUpdateRequest schema in openapi/spec.yaml (approximately line 12560)
• Reference the new schema: $ref: '#/components/schemas/SiteCapabilitiesUpdateRequest'

Task 3: Update Endpoint Documentation

Enhance the PATCH endpoint description to reflect new capabilities.

• Update description for PATCH /v2/org/{org}/carbide/site/{siteId} operation in openapi/spec.yaml
• Add note indicating that capabilities field is configurable by Provider only
• Ensure consistency with existing authorization documentation pattern

🤖 Prompt for AI agents

Update `openapi/spec.yaml` to formally document the new capabilities update
support across schema definitions and endpoint descriptions.

- In the `components/schemas` section, add a new schema named
`SiteCapabilitiesUpdateRequest` with the following five optional boolean
properties (no `required` array):
  - `nativeNetworking`
  - `networkSecurityGroup`
  - `nvLinkPartition`
  - `rackLevelAdministration`
  - `imageBasedOperatingSystem`
- In the existing `SiteUpdateRequest` schema (approximately line 12560), add a
`capabilities` property referencing the new schema: `$ref:
'#/components/schemas/SiteCapabilitiesUpdateRequest'`
- In the operation definition for `PATCH /v2/org/{org}/carbide/site/{siteId}`,
update the description to include a note that the `capabilities` field is
configurable by Provider only, consistent with existing authorization
documentation patterns

Research

The codebase follows a clean three-tier architecture with clear separation between API handlers, models, and database layers. The database layer already fully supports site config updates via SiteConfigUpdateInput and JSONB merge operations in SiteSQLDAO.Update(). The API layer exposes site data through APISite with config projected as capabilities via siteConfigToAPISiteCapabilities(). The gap exists solely in the API request path: APISiteUpdateRequest lacks config fields, and UpdateSiteHandler never populates SiteUpdateInput.Config. Authorization follows a consistent pattern using auth.ValidateUserRoles() for provider-only operations.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extend the API model layer in `api/pkg/api/model/site.go` to introduce
capabilities update support with correct partial-update semantics and role-based
validation.

- Define a new struct `APISiteCapabilitiesUpdateRequest` with the following
pointer-typed fields, each tagged with `omitempty` camelCase JSON keys to enable
sparse updates:
  - `NativeNetworking *bool` → `json:"nativeNetworking,omitempty"`
  - `NetworkSecurityGroup *bool` → `json:"networkSecurityGroup,omitempty"`
  - `NVLinkPartition *bool` → `json:"nvLinkPartition,omitempty"`
  - `RackLevelAdministration *bool` → `json:"rackLevelAdministration,omitempty"`
- `ImageBasedOperatingSystem *bool` →
`json:"imageBasedOperatingSystem,omitempty"`
- Add `Capabilities *APISiteCapabilitiesUpdateRequest` to the existing
`APISiteUpdateRequest` struct with tag `json:"capabilities,omitempty"`
- In `APISiteUpdateRequest.Validate(isProvider, isTenant bool)`, within the
non-provider (tenant) validation branch, add a `validation.Nil` rule targeting
the `Capabilities` field with the error message `"value is not configurable by
Tenant"`
===============================================================================

Task: 2

Wire the new capabilities request model through the handler layer to the
existing database infrastructure in `api/pkg/api/handler/site.go`.

- Implement a new function
`apiSiteCapabilitiesUpdateRequestToSiteConfigUpdateInput()` that:
  - Accepts a `*APISiteCapabilitiesUpdateRequest` argument
- Returns `nil` immediately if the input is `nil`, preserving partial-update
semantics
- Otherwise, maps each pointer field from `APISiteCapabilitiesUpdateRequest` to
the corresponding field in `SiteConfigUpdateInput` (e.g., `NativeNetworking` →
`NativeNetworking`, `NetworkSecurityGroup` → `NetworkSecurityGroup`, and so on
for all five fields)
- In `UpdateSiteHandler.Handle()`, after the `siteUpdateInput` struct is
constructed (approximately lines 473–503), add the following assignment:
- `siteUpdateInput.Config =
apiSiteCapabilitiesUpdateRequestToSiteConfigUpdateInput(apiRequest.Capabilities)`
- No modifications to the DB layer are required; the existing JSONB merge logic
in `SiteSQLDAO.Update()` handles the rest
===============================================================================

Task: 3

Update `openapi/spec.yaml` to formally document the new capabilities update
support across schema definitions and endpoint descriptions.

- In the `components/schemas` section, add a new schema named
`SiteCapabilitiesUpdateRequest` with the following five optional boolean
properties (no `required` array):
  - `nativeNetworking`
  - `networkSecurityGroup`
  - `nvLinkPartition`
  - `rackLevelAdministration`
  - `imageBasedOperatingSystem`
- In the existing `SiteUpdateRequest` schema (approximately line 12560), add a
`capabilities` property referencing the new schema: `$ref:
'#/components/schemas/SiteCapabilitiesUpdateRequest'`
- In the operation definition for `PATCH /v2/org/{org}/carbide/site/{siteId}`,
update the description to include a note that the `capabilities` field is
configurable by Provider only, consistent with existing authorization
documentation patterns

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!