feat: add GET tenant capabilities endpoint to read per-site TargetedInstanceCreation scoping

Author: hwadekar-nv

rest-api/api/pkg/api/handler/tenantcapability.go

@@ -320,3 +320,121 @@ func resolveTargetSites(requestedSites []string, providerFilter *uuid.UUID, elig
 
 	return targets, nil
 }
+
+// ~~~~~ Get Handler ~~~~~ //
+
+// GetTenantCapabilityHandler is the API Handler for reading a Tenant's current scoped
+// capability configuration (e.g. which Sites have TargetedInstanceCreation enabled).
+type GetTenantCapabilityHandler struct {
+	dbSession  *cdb.Session
+	cfg        *config.Config
+	tracerSpan *cutil.TracerSpan
+}
+
+// NewGetTenantCapabilityHandler initializes and returns a new handler for reading tenant capabilities
+func NewGetTenantCapabilityHandler(dbSession *cdb.Session, cfg *config.Config) GetTenantCapabilityHandler {
+	return GetTenantCapabilityHandler{
+		dbSession:  dbSession,
+		cfg:        cfg,
+		tracerSpan: cutil.NewTracerSpan(),
+	}
+}
+
+// Handle godoc
+// @Summary Read scoped tenant capabilities
+// @Description Read the current scoping of tenant capabilities (e.g. the Sites TargetedInstanceCreation is enabled for)
+// @Tags tenant
+// @Produce json
+// @Security ApiKeyAuth
+// @Param org path string true "Name of NGC organization"
+// @Param tenantId path string true "ID of Tenant"
+// @Param infrastructureProviderId query string false "Restrict the reported Sites to those owned by this Infrastructure Provider"
+// @Success 200 {object} model.APITenantCapabilityListResponse
+// @Router /v2/org/{org}/nico/tenant/{tenantId}/capabilities [get]
+func (gtch GetTenantCapabilityHandler) Handle(c echo.Context) error {
+	org, dbUser, ctx, logger, handlerSpan := common.SetupHandler("TenantCapability", "Get", c, gtch.tracerSpan)
+	if handlerSpan != nil {
+		defer handlerSpan.End()
+	}
+	if dbUser == nil {
+		return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve current user", nil)
+	}
+
+	// Validate org
+	ok, err := auth.ValidateOrgMembership(dbUser, org)
+	if !ok {
+		if err != nil {
+			logger.Error().Err(err).Msg("error validating org membership for User in request")
+		} else {
+			logger.Warn().Msg("could not validate org membership for user, access denied")
+		}
+		return cutil.NewAPIErrorResponse(c, http.StatusForbidden, fmt.Sprintf("Failed to validate membership for org: %s", org), nil)
+	}
+
+	// Validate role, only Tenant Admins may read scoped capabilities for their tenant
+	ok = auth.ValidateUserRoles(dbUser, org, nil, auth.TenantAdminRole)
+	if !ok {
+		logger.Warn().Msg("user does not have Tenant Admin role with org, access denied")
+		return cutil.NewAPIErrorResponse(c, http.StatusForbidden, "User does not have Tenant Admin role with org", nil)
+	}
+
+	// Get tenant ID from URL param
+	tenantStrID := c.Param("tenantId")
+
+	gtch.tracerSpan.SetAttribute(handlerSpan, attribute.String("tenant_id", tenantStrID), logger)
+
+	tenantID, err := uuid.Parse(tenantStrID)
+	if err != nil {
+		logger.Warn().Err(err).Msg("error parsing tenantId in url into uuid")
+		return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid Tenant ID in URL", nil)
+	}
+
+	// Resolve the tenant for this org and ensure it matches the tenant in the URL.
+	tenant, err := common.GetTenantForOrg(ctx, nil, gtch.dbSession, org)
+	if err != nil {
+		logger.Warn().Err(err).Msg("tenant does not exist for org")
+		return cutil.NewAPIErrorResponse(c, http.StatusNotFound, "Org does not have a tenant", nil)
+	}
+	if tenant.ID != tenantID {
+		logger.Warn().Msg("tenant in URL does not match tenant for org")
+		return cutil.NewAPIErrorResponse(c, http.StatusForbidden, "Tenant in URL does not belong to org", nil)
+	}
+
+	// Optional provider filter passed as a query parameter.
+	filter := cdbm.TenantSiteCapabilityAssociationFilterInput{TenantIDs: []uuid.UUID{tenant.ID}}
+	if rawProvider := c.QueryParam("infrastructureProviderId"); rawProvider != "" {
+		pid, perr := uuid.Parse(rawProvider)
+		if perr != nil {
+			return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid Infrastructure Provider ID in query", nil)
+		}
+		filter.InfrastructureProviderIDs = []uuid.UUID{pid}
+	}
+
+	tscaDAO := cdbm.NewTenantSiteCapabilityAssociationDAO(gtch.dbSession)
+	tscas, _, err := tscaDAO.GetAll(ctx, nil, filter, cdbp.PageInput{Limit: cdb.GetIntPtr(cdbp.TotalLimit)}, nil)
+	if err != nil {
+		logger.Error().Err(err).Msg("error retrieving capability associations for tenant")
+		return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Tenant capabilities", nil)
+	}
+
+	enabledSiteIDs := []string{}
+	for _, tsca := range tscas {
+		if tsca.TargetedInstanceCreation {
+			enabledSiteIDs = append(enabledSiteIDs, tsca.SiteID.String())
+		}
+	}
+
+	apiResponse := model.APITenantCapabilityListResponse{
+		Capabilities: []model.APITenantCapabilityStatus{
+			{
+				CapabilityName: model.CapabilityNameTargetedInstanceCreation,
+				CeilingEnabled: common.TenantHasTargetedInstanceCreation(tenant),
+				SiteIDs:        enabledSiteIDs,
+			},
+		},
+	}
+
+	logger.Info().Msg("finishing API handler")
+
+	return c.JSON(http.StatusOK, apiResponse)
+}

rest-api/api/pkg/api/handler/tenantcapability_test.go

@@ -339,3 +339,174 @@ func TestTenantCapabilityHandler_Update(t *testing.T) {
 		})
 	}
 }
+
+func TestTenantCapabilityHandler_Get(t *testing.T) {
+	ctx := context.Background()
+	dbSession := testTenantCapabilityInitDB(t)
+	defer dbSession.Close()
+
+	testTenantCapabilitySetupSchema(t, dbSession)
+
+	ipOrg := "test-ip-org"
+	tnOrg := "test-tn-org"
+	tnOrgNoCeiling := "test-tn-org-no-ceiling"
+	tnOrgNoTenant := "test-tn-org-no-tenant"
+
+	ipUser := cdbm.TestBuildUser(t, dbSession, uuid.NewString(), ipOrg, []string{authz.ProviderAdminRole})
+	tnUser := cdbm.TestBuildUser(t, dbSession, uuid.NewString(), tnOrg, []string{authz.TenantAdminRole})
+	tnUserNoCeiling := cdbm.TestBuildUser(t, dbSession, uuid.NewString(), tnOrgNoCeiling, []string{authz.TenantAdminRole})
+	tnNonAdminUser := cdbm.TestBuildUser(t, dbSession, uuid.NewString(), tnOrg, []string{authz.ProviderAdminRole})
+	noTenantUser := cdbm.TestBuildUser(t, dbSession, uuid.NewString(), tnOrgNoTenant, []string{authz.TenantAdminRole})
+
+	ip := cdbm.TestBuildInfrastructureProvider(t, dbSession, "Test Provider", ipOrg, ipUser)
+	ip2 := cdbm.TestBuildInfrastructureProvider(t, dbSession, "Test Provider 2", ipOrg+"-2", ipUser)
+
+	tn := testTenantCapabilityBuildTenant(t, dbSession, tnOrg, tnUser, true)
+	tnNoCeiling := testTenantCapabilityBuildTenant(t, dbSession, tnOrgNoCeiling, tnUserNoCeiling, false)
+
+	site1 := cdbm.TestBuildSite(t, dbSession, ip, "Test Site 1", ipUser)
+	site2 := cdbm.TestBuildSite(t, dbSession, ip, "Test Site 2", ipUser)
+	site3 := cdbm.TestBuildSite(t, dbSession, ip2, "Test Site 3", ipUser)
+
+	// site1 enabled, site2 explicitly disabled, site3 (under ip2) enabled.
+	cdbm.TestBuildTenantSiteCapabilityAssociation(t, dbSession, tn, site1, true, tnUser)
+	cdbm.TestBuildTenantSiteCapabilityAssociation(t, dbSession, tn, site2, false, tnUser)
+	cdbm.TestBuildTenantSiteCapabilityAssociation(t, dbSession, tn, site3, true, tnUser)
+
+	cfg := common.GetTestConfig()
+	tracer, _, ctx := common.TestCommonTraceProviderSetup(t, ctx)
+
+	tests := []struct {
+		name               string
+		reqOrgName         string
+		tenantID           string
+		providerFilter     string
+		user               *cdbm.User
+		expectedStatus     int
+		expectedCeiling    bool
+		expectedSiteIDs    []string
+		verifyChildSpanner bool
+	}{
+		{
+			name:           "error when user not found in request context",
+			reqOrgName:     tnOrg,
+			tenantID:       tn.ID.String(),
+			user:           nil,
+			expectedStatus: http.StatusInternalServerError,
+		},
+		{
+			name:           "error when user is not a tenant admin",
+			reqOrgName:     tnOrg,
+			tenantID:       tn.ID.String(),
+			user:           tnNonAdminUser,
+			expectedStatus: http.StatusForbidden,
+		},
+		{
+			name:           "error when tenantId in URL is not a valid uuid",
+			reqOrgName:     tnOrg,
+			tenantID:       "not-a-uuid",
+			user:           tnUser,
+			expectedStatus: http.StatusBadRequest,
+		},
+		{
+			name:           "error when provider filter is not a valid uuid",
+			reqOrgName:     tnOrg,
+			tenantID:       tn.ID.String(),
+			providerFilter: "not-a-uuid",
+			user:           tnUser,
+			expectedStatus: http.StatusBadRequest,
+		},
+		{
+			name:           "error when org has no tenant",
+			reqOrgName:     tnOrgNoTenant,
+			tenantID:       tn.ID.String(),
+			user:           noTenantUser,
+			expectedStatus: http.StatusNotFound,
+		},
+		{
+			name:           "error when tenant in URL does not match org tenant",
+			reqOrgName:     tnOrg,
+			tenantID:       uuid.New().String(),
+			user:           tnUser,
+			expectedStatus: http.StatusForbidden,
+		},
+		{
+			name:               "success lists only enabled sites",
+			reqOrgName:         tnOrg,
+			tenantID:           tn.ID.String(),
+			user:               tnUser,
+			expectedStatus:     http.StatusOK,
+			expectedCeiling:    true,
+			expectedSiteIDs:    []string{site1.ID.String(), site3.ID.String()},
+			verifyChildSpanner: true,
+		},
+		{
+			name:            "success filters enabled sites by provider",
+			reqOrgName:      tnOrg,
+			tenantID:        tn.ID.String(),
+			providerFilter:  ip.ID.String(),
+			user:            tnUser,
+			expectedStatus:  http.StatusOK,
+			expectedCeiling: true,
+			expectedSiteIDs: []string{site1.ID.String()},
+		},
+		{
+			name:            "success reports ceiling disabled and no sites",
+			reqOrgName:      tnOrgNoCeiling,
+			tenantID:        tnNoCeiling.ID.String(),
+			user:            tnUserNoCeiling,
+			expectedStatus:  http.StatusOK,
+			expectedCeiling: false,
+			expectedSiteIDs: []string{},
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			e := echo.New()
+			target := "/"
+			if tc.providerFilter != "" {
+				target = "/?infrastructureProviderId=" + tc.providerFilter
+			}
+			req := httptest.NewRequest(http.MethodGet, target, nil)
+			rec := httptest.NewRecorder()
+
+			ec := e.NewContext(req, rec)
+			ec.SetParamNames("orgName", "tenantId")
+			ec.SetParamValues(tc.reqOrgName, tc.tenantID)
+			if tc.user != nil {
+				ec.Set("user", tc.user)
+			}
+
+			ctx = context.WithValue(ctx, otelecho.TracerKey, tracer)
+			ec.SetRequest(ec.Request().WithContext(ctx))
+
+			h := GetTenantCapabilityHandler{
+				dbSession: dbSession,
+				cfg:       cfg,
+			}
+			err := h.Handle(ec)
+			assert.Nil(t, err)
+
+			if tc.expectedStatus != rec.Code {
+				t.Errorf("response: %v\n", rec.Body.String())
+			}
+			require.Equal(t, tc.expectedStatus, rec.Code)
+
+			if tc.expectedStatus == http.StatusOK {
+				rsp := &model.APITenantCapabilityListResponse{}
+				uerr := json.Unmarshal(rec.Body.Bytes(), rsp)
+				assert.Nil(t, uerr)
+				require.Len(t, rsp.Capabilities, 1)
+				capStatus := rsp.Capabilities[0]
+				assert.Equal(t, model.CapabilityNameTargetedInstanceCreation, capStatus.CapabilityName)
+				assert.Equal(t, tc.expectedCeiling, capStatus.CeilingEnabled)
+				assert.ElementsMatch(t, tc.expectedSiteIDs, capStatus.SiteIDs)
+			}
+
+			if tc.verifyChildSpanner {
+				span := oteltrace.SpanFromContext(ec.Request().Context())
+				assert.True(t, span.SpanContext().IsValid())
+			}
+		})
+	}
+}

rest-api/api/pkg/api/model/tenantcapability.go

@@ -64,3 +64,23 @@ type APITenantCapability struct {
 	// SiteIDs are the Site IDs the change was applied to.
 	SiteIDs []string `json:"siteIds"`
 }
+
+// APITenantCapabilityStatus is the API representation of the current scoping of a single
+// capability for a Tenant: whether the tenant-level ceiling is set and the Sites the
+// capability is currently enabled for.
+type APITenantCapabilityStatus struct {
+	// CapabilityName is the capability being reported, e.g. "TargetedInstanceCreation".
+	CapabilityName string `json:"capabilityName"`
+	// CeilingEnabled reflects the tenant-level entitlement (Tenant.Config). A capability
+	// can only be effective on a Site when this is true.
+	CeilingEnabled bool `json:"ceilingEnabled"`
+	// SiteIDs are the Site IDs the capability is currently enabled for.
+	SiteIDs []string `json:"siteIds"`
+}
+
+// APITenantCapabilityListResponse is the response for reading a Tenant's current scoped
+// capabilities. It lists the status of each supported capability.
+type APITenantCapabilityListResponse struct {
+	// Capabilities is the per-capability scoping status for the Tenant.
+	Capabilities []APITenantCapabilityStatus `json:"capabilities"`
+}

rest-api/api/pkg/api/routes.go

@@ -83,12 +83,17 @@ func NewAPIRoutes(dbSession *cdb.Session, tc tClient.Client, tnc tClient.Namespa
 			Method:  http.MethodGet,
 			Handler: apiHandler.NewGetCurrentTenantStatsHandler(dbSession, tc, cfg),
 		},
-		// Tenant Capability endpoint
+		// Tenant Capability endpoints
 		{
 			Path:    apiPathPrefix + "/tenant/:tenantId/capabilities",
 			Method:  http.MethodPatch,
 			Handler: apiHandler.NewUpdateTenantCapabilityHandler(dbSession, tc, cfg),
 		},
+		{
+			Path:    apiPathPrefix + "/tenant/:tenantId/capabilities",
+			Method:  http.MethodGet,
+			Handler: apiHandler.NewGetTenantCapabilityHandler(dbSession, cfg),
+		},
 		// Tenant Instance Type Stats endpoint
 		{
 			Path:    apiPathPrefix + "/tenant/instance-type/stats",

rest-api/api/pkg/api/routes_test.go

@@ -37,7 +37,7 @@ func TestNewAPIRoutes(t *testing.T) {
 		"metadata":                  1,
 		"service-account":           1,
 		"infrastructure-provider":   4,
-		"tenant":                    5,
+		"tenant":                    6,
 		"tenant-account":            5,
 		"site":                      6,
 		"vpc":                       6,

rest-api/flow/internal/task/componentmanager/providers/nico/assignment.go

@@ -1,19 +1,5 @@
-/*
- * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
- * SPDX-License-Identifier: Apache-2.0
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package nico
 

rest-api/flow/internal/task/componentmanager/providers/nico/assignment_test.go

@@ -1,19 +1,5 @@
-/*
- * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
- * SPDX-License-Identifier: Apache-2.0
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package nico