feat: REST API should expose targetedInstanceCreation tenant capability toggle

[pmilano-nvidia]

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

TenantCapabilities.targetedInstanceCreation is currently readOnly: true in the API spec. It can only be set via direct DB update on the tenant.config JSONB column.

Infrastructure providers need to enable targeted instance creation for tenants so they can specify machineId when creating instances (e.g., for datahall site controller provisioning where specific machines must map to specific hostnames/roles).

Request:

1. Allow setting targetedInstanceCreation during tenant creation (auto-created via GET /tenant/current. Currently no way to pass capabilities)
2. Add a PATCH endpoint or extend the existing tenant/tenant-account API to allow updating targetedInstanceCreation after creation

Feature Description

As an NCP, I want to be able to toggle/set targetedInstanceCreation so that I can specify machineId when creating Instances for VPCs.

Describe your ideal solution

Direct DB update:
UPDATE tenant SET config = jsonb_set(config, '{targetedInstanceCreation}', 'true') WHERE id = '<tenant_id>';

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

[hwadekar-nv]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Introduce a new PATCH /v2/org/{org}/carbide/tenant/{tenantId}/capabilities endpoint restricted to the FORGE_PROVIDER_ADMIN role
• Authorization boundary enforced by validating a TenantAccount relationship exists between the requesting Infrastructure Provider and the target Tenant
• Leverage existing TenantDAO.UpdateFromParams method for config persistence, requiring no database schema changes
• Follow established patterns for request validation, error handling, and response formatting to maintain codebase consistency

Design Choices

Design Choice 1: Endpoint Design: Provider-Admin Tenant Capabilities Endpoint vs. TenantAccount Extension

Options Considered:

1. Create a new PATCH /v2/org/{org}/carbide/tenant/{tenantId}/capabilities endpoint restricted to Provider Admins, validating the IP-Tenant relationship via TenantAccount
2. Extend CreateTenantAccountHandler and UpdateTenantAccountHandler to accept and propagate capability settings to the linked Tenant

Chosen Option: 1

Rationale: A dedicated capabilities endpoint maintains clean separation of concerns—capabilities belong to Tenant, not TenantAccount—and follows the principle of single responsibility. The TenantAccount relationship serves as the authorization boundary.

💡 User Tips

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

Implementation Steps

Phase 1: OpenAPI Specification Updates

Define the new endpoint contract and request schema in the API specification. This establishes the interface before implementation and ensures the SDK will be generated correctly.

Task 1: Add TenantCapabilitiesUpdateRequest Schema

Introduce a dedicated request schema for updating tenant capabilities, following the existing pattern of TenantAccountUpdateRequest.

• Add TenantCapabilitiesUpdateRequest schema in openapi/spec.yaml under components/schemas
• Define targetedInstanceCreation as an optional boolean field (no readOnly constraint)
• Include appropriate title, description, and example values following existing schema conventions

Task 2: Define PATCH Endpoint for Tenant Capabilities

Add the new endpoint specification that allows Provider Admins to update tenant capabilities.

• Add PATCH /v2/org/{org}/carbide/tenant/{tenantId}/capabilities endpoint in openapi/spec.yaml
• Define path parameter tenantId as required UUID
• Reference TenantCapabilitiesUpdateRequest as request body schema
• Return Tenant schema on success (HTTP 200)
• Document required role as FORGE_PROVIDER_ADMIN in description
• Add standard error responses (400, 403, 404, 500)
• Assign appropriate operationId (e.g., update-tenant-capabilities) and tags

🤖 Prompt for AI agents

Update `openapi/spec.yaml` to define the new schema and endpoint contract for
tenant capabilities mutation.

**Schema addition (`components/schemas`):**
- Add `TenantCapabilitiesUpdateRequest` schema modelled after the existing
`TenantAccountUpdateRequest` pattern
- Include a single optional boolean field `targetedInstanceCreation` — no
`readOnly` constraint
- Provide a title, description, and example values consistent with surrounding
schema conventions

**Endpoint addition:**
- Register `PATCH /v2/org/{org}/carbide/tenant/{tenantId}/capabilities`
- `tenantId` path parameter: required, type UUID
- Request body: `$ref` to `TenantCapabilitiesUpdateRequest`
- Success response: HTTP 200, `$ref` to `Tenant` schema
- Error responses: 400, 403, 404, 500 following established patterns
- `operationId`: `update-tenant-capabilities`
- Description must note that the required role is `FORGE_PROVIDER_ADMIN`
- Apply appropriate tags consistent with other tenant endpoints

Phase 2: API Model Layer

Implement the request struct and validation logic in the API model layer.

Create APITenantCapabilitiesUpdateRequest Struct

Add the Go struct corresponding to the OpenAPI schema with proper validation.

• Create APITenantCapabilitiesUpdateRequest struct in api/pkg/api/model/tenant.go
• Define TargetedInstanceCreation *bool as optional pointer field with JSON tag
• Implement Validate() error method using go-ozzo/ozzo-validation following existing patterns
• Validation should permit empty requests (no fields required, as patch semantics allow partial updates)

🤖 Prompt for AI agents

Extend `api/pkg/api/model/tenant.go` with the request model for the capabilities
patch operation.

- Add `APITenantCapabilitiesUpdateRequest` struct
  - Field: `TargetedInstanceCreation *bool` with an appropriate JSON tag
- Implement a `Validate() error` method on the struct using
`go-ozzo/ozzo-validation`, consistent with existing model validation patterns
- No fields are required; patch semantics must permit an empty request body
without returning a validation error

Phase 3: API Handler Implementation

Implement the handler with proper authorization, validation, and business logic.

Task 1: Create UpdateTenantCapabilitiesHandler

Implement the HTTP handler for the new endpoint following established handler patterns.

• Create UpdateTenantCapabilitiesHandler struct in api/pkg/api/handler/tenant.go
• Implement Handle(c echo.Context) error method with the following logic flow:
  • Extract org from path parameters via common.SetupHandler
  • Validate org membership via auth.ValidateOrgMembership
  • Validate FORGE_PROVIDER_ADMIN role via auth.ValidateUserRoles
  • Extract and validate tenantId UUID from path parameters
  • Bind and validate request body to APITenantCapabilitiesUpdateRequest
  • Fetch the Infrastructure Provider for the requesting org
  • Validate that a TenantAccount exists linking the IP to the target Tenant (authorization boundary)
  • Fetch the target Tenant by ID
  • Construct updated TenantConfig preserving existing fields, applying requested changes
  • Call TenantDAO.UpdateFromParams with the updated config
  • Return the updated Tenant as APITenant response

Task 2: Add Swagger Documentation Annotations

Add godoc annotations for OpenAPI documentation generation.

• Add standard swagger annotations to UpdateTenantCapabilitiesHandler.Handle method
• Include @Summary, @Description, @Tags, @Accept, @Produce, @Param, @Success, @Failure, and @Router annotations
• Follow existing annotation patterns from other handlers in the file

🤖 Prompt for AI agents

Implement `UpdateTenantCapabilitiesHandler` in `api/pkg/api/handler/tenant.go`,
adhering to the established handler structure and authorization patterns.

**Struct definition:**
- Define `UpdateTenantCapabilitiesHandler` with the required dependencies
(logger, dbSession)

**`Handle(c echo.Context) error` logic — execute in the following order:**
1. Extract org from path parameters via `common.SetupHandler`
2. Validate org membership via `auth.ValidateOrgMembership`
3. Enforce `FORGE_PROVIDER_ADMIN` role via `auth.ValidateUserRoles`
4. Parse and validate `tenantId` as a UUID from path parameters; return 400 on
failure
5. Bind and validate request body to `APITenantCapabilitiesUpdateRequest`;
return 400 on validation error
6. Fetch the Infrastructure Provider for the requesting org
7. Assert a `TenantAccount` record exists linking that IP to the target
`tenantId`; return 403/404 as appropriate if absent
8. Fetch the target `Tenant` by ID
9. Construct an updated `TenantConfig` — preserve all existing fields and apply
only the requested changes
10. Persist via `TenantDAO.UpdateFromParams`
11. Return the updated tenant serialised as `APITenant` with HTTP 200

**Swagger annotations:**
- Annotate the `Handle` method with `@Summary`, `@Description`, `@Tags`,
`@Accept`, `@Produce`, `@Param`, `@Success`, `@Failure`, and `@Router`
- Mirror the annotation style used by adjacent handlers in the file

Phase 4: Route Registration and Integration

Wire up the new handler to the router and ensure proper integration.

Task 1: Register New Route

Add the route registration for the new endpoint.

• Add route registration in api/pkg/api/routes.go under the tenant route group
• Instantiate UpdateTenantCapabilitiesHandler with required dependencies (logger, dbSession)
• Register PATCH /v2/org/:orgName/carbide/tenant/:tenantId/capabilities mapping to the handler

Task 2: SDK Regeneration

Ensure the SDK is regenerated from the updated OpenAPI specification.

• Run the SDK generation tooling to produce updated client code from openapi/spec.yaml
• Verify TenantCapabilitiesUpdateRequest model is generated in sdk/standard/
• Verify UpdateTenantCapabilities method is added to the appropriate API service

🤖 Prompt for AI agents

Wire the new handler into the routing layer and regenerate the SDK from the
updated specification.

**Route registration in `api/pkg/api/routes.go`:**
- Locate the tenant route group
- Instantiate `UpdateTenantCapabilitiesHandler` with the required dependencies
(logger, dbSession)
- Register: `PATCH /v2/org/:orgName/carbide/tenant/:tenantId/capabilities` →
`UpdateTenantCapabilitiesHandler.Handle`

**SDK regeneration:**
- Execute the SDK generation tooling against `openapi/spec.yaml`
- Confirm `TenantCapabilitiesUpdateRequest` model is present in `sdk/standard/`
- Confirm `UpdateTenantCapabilities` method is present on the appropriate API
service client

Research

The codebase follows a layered architecture with clear separation between OpenAPI specification (openapi/spec.yaml), API models (api/pkg/api/model/), HTTP handlers (api/pkg/api/handler/), and database models (db/pkg/db/model/). Tenant capabilities are stored in a JSONB config column on the tenant table, represented by TenantConfig struct containing TargetedInstanceCreation bool. The TenantDAO.UpdateFromParams method already supports updating this configuration. Authorization is role-based with FORGE_PROVIDER_ADMIN for infrastructure provider operations and FORGE_TENANT_ADMIN for tenant operations. The existing PATCH /tenant/current endpoint is deprecated and returns HTTP 400. The TenantAccount entity serves as the bridge between Infrastructure Providers and Tenants.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Update `openapi/spec.yaml` to define the new schema and endpoint contract for
tenant capabilities mutation.

**Schema addition (`components/schemas`):**
- Add `TenantCapabilitiesUpdateRequest` schema modelled after the existing
`TenantAccountUpdateRequest` pattern
- Include a single optional boolean field `targetedInstanceCreation` — no
`readOnly` constraint
- Provide a title, description, and example values consistent with surrounding
schema conventions

**Endpoint addition:**
- Register `PATCH /v2/org/{org}/carbide/tenant/{tenantId}/capabilities`
- `tenantId` path parameter: required, type UUID
- Request body: `$ref` to `TenantCapabilitiesUpdateRequest`
- Success response: HTTP 200, `$ref` to `Tenant` schema
- Error responses: 400, 403, 404, 500 following established patterns
- `operationId`: `update-tenant-capabilities`
- Description must note that the required role is `FORGE_PROVIDER_ADMIN`
- Apply appropriate tags consistent with other tenant endpoints
===============================================================================

Task: 2

Extend `api/pkg/api/model/tenant.go` with the request model for the capabilities
patch operation.

- Add `APITenantCapabilitiesUpdateRequest` struct
  - Field: `TargetedInstanceCreation *bool` with an appropriate JSON tag
- Implement a `Validate() error` method on the struct using
`go-ozzo/ozzo-validation`, consistent with existing model validation patterns
- No fields are required; patch semantics must permit an empty request body
without returning a validation error
===============================================================================

Task: 3

Implement `UpdateTenantCapabilitiesHandler` in `api/pkg/api/handler/tenant.go`,
adhering to the established handler structure and authorization patterns.

**Struct definition:**
- Define `UpdateTenantCapabilitiesHandler` with the required dependencies
(logger, dbSession)

**`Handle(c echo.Context) error` logic — execute in the following order:**
1. Extract org from path parameters via `common.SetupHandler`
2. Validate org membership via `auth.ValidateOrgMembership`
3. Enforce `FORGE_PROVIDER_ADMIN` role via `auth.ValidateUserRoles`
4. Parse and validate `tenantId` as a UUID from path parameters; return 400 on
failure
5. Bind and validate request body to `APITenantCapabilitiesUpdateRequest`;
return 400 on validation error
6. Fetch the Infrastructure Provider for the requesting org
7. Assert a `TenantAccount` record exists linking that IP to the target
`tenantId`; return 403/404 as appropriate if absent
8. Fetch the target `Tenant` by ID
9. Construct an updated `TenantConfig` — preserve all existing fields and apply
only the requested changes
10. Persist via `TenantDAO.UpdateFromParams`
11. Return the updated tenant serialised as `APITenant` with HTTP 200

**Swagger annotations:**
- Annotate the `Handle` method with `@Summary`, `@Description`, `@Tags`,
`@Accept`, `@Produce`, `@Param`, `@Success`, `@Failure`, and `@Router`
- Mirror the annotation style used by adjacent handlers in the file
===============================================================================

Task: 4

Wire the new handler into the routing layer and regenerate the SDK from the
updated specification.

**Route registration in `api/pkg/api/routes.go`:**
- Locate the tenant route group
- Instantiate `UpdateTenantCapabilitiesHandler` with the required dependencies
(logger, dbSession)
- Register: `PATCH /v2/org/:orgName/carbide/tenant/:tenantId/capabilities` →
`UpdateTenantCapabilitiesHandler.Handle`

**SDK regeneration:**
- Execute the SDK generation tooling against `openapi/spec.yaml`
- Confirm `TenantCapabilitiesUpdateRequest` model is present in `sdk/standard/`
- Confirm `UpdateTenantCapabilities` method is present on the appropriate API
service client

💡 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!

[thossain-nv]

This needs some additional work:

• Tenant capabilities should not span across Providers and moved from Tenant model to TenantAccount model
• We should support limiting Tenant capabilities per Site - TenantAccount capability can be overridden in TenantSite model

[hwadekar-nv]

To address this feature, we have design discussion going on, we will make it progress once we finalized the design