Scaffold empty placement api handlers

Author: PhilippMatthes

cmd/shim/main.go

@@ -12,6 +12,7 @@ import (
 	"path/filepath"
 
 	"github.com/cobaltcore-dev/cortex/api/v1alpha1"
+	placementhandlers "github.com/cobaltcore-dev/cortex/internal/shim/placement/handlers"
 	"github.com/cobaltcore-dev/cortex/pkg/conf"
 	"github.com/cobaltcore-dev/cortex/pkg/monitoring"
 	hv1 "github.com/cobaltcore-dev/openstack-hypervisor-operator/api/v1"
@@ -57,6 +58,7 @@ func main() {
 	var probeAddr string
 	var secureMetrics bool
 	var enableHTTP2 bool
+	var enablePlacementShim bool
 	var tlsOpts []func(*tls.Config)
 	flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. "+
 		"Use :8443 for HTTPS or :8080 for HTTP, or leave as 0 to disable the metrics service.")
@@ -75,6 +77,8 @@ func main() {
 	flag.StringVar(&metricsCertKey, "metrics-cert-key", "tls.key", "The name of the metrics server key file.")
 	flag.BoolVar(&enableHTTP2, "enable-http2", false,
 		"If set, HTTP/2 will be enabled for the metrics and webhook servers")
+	flag.BoolVar(&enablePlacementShim, "placement-shim", false,
+		"If set, the placement API shim handlers are registered on the API server.")
 	opts := zap.Options{
 		Development: true,
 	}
@@ -202,6 +206,9 @@ func main() {
 
 	// API endpoint.
 	mux := http.NewServeMux()
+	if enablePlacementShim {
+		placementhandlers.RegisterRoutes(mux)
+	}
 
 	// +kubebuilder:scaffold:builder
 

internal/shim/placement/handlers/allocation_candidates.go

@@ -0,0 +1,40 @@
+// Copyright SAP SE
+// SPDX-License-Identifier: Apache-2.0
+
+package handlers
+
+import (
+	"net/http"
+
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+)
+
+// HandleListAllocationCandidates handles GET /allocation_candidates requests.
+//
+// Returns a collection of allocation requests and resource provider summaries
+// that can satisfy a given set of resource and trait requirements. This is the
+// primary endpoint used by Nova's scheduler to find suitable hosts for
+// instance placement.
+//
+// The resources query parameter specifies required capacity as a comma-
+// separated list (e.g. VCPU:4,MEMORY_MB:2048,DISK_GB:64). The required
+// parameter filters by traits, supporting forbidden traits via ! prefix
+// (since 1.22) and the in: syntax for any-of semantics (since 1.39).
+// The member_of parameter filters by aggregate membership with support for
+// forbidden aggregates via ! prefix (since 1.32).
+//
+// Since microversion 1.25, granular request groups are supported via numbered
+// suffixes (resourcesN, requiredN, member_ofN) to express requirements that
+// may be satisfied by different providers. The group_policy parameter (1.26+)
+// controls whether groups must each be satisfied by a single provider or may
+// span multiple. The in_tree parameter (1.31+) constrains results to a
+// specific provider tree.
+//
+// Each returned allocation request is directly usable as the body for
+// PUT /allocations/{consumer_uuid}. The provider_summaries section includes
+// inventory capacity and usage for informed decision-making. Available since
+// microversion 1.10.
+func HandleListAllocationCandidates(w http.ResponseWriter, r *http.Request) {
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path)
+}

internal/shim/placement/handlers/allocations.go

@@ -0,0 +1,78 @@
+// Copyright SAP SE
+// SPDX-License-Identifier: Apache-2.0
+
+package handlers
+
+import (
+	"net/http"
+
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+)
+
+// HandleManageAllocations handles POST /allocations requests.
+//
+// Atomically creates, updates, or deletes allocations for multiple consumers
+// in a single request. This is the primary mechanism for operations that must
+// modify allocations across several consumers atomically, such as live
+// migrations and move operations where resources are transferred from one
+// consumer to another. Available since microversion 1.13.
+//
+// The request body is keyed by consumer UUID, each containing an allocations
+// dictionary (keyed by resource provider UUID), along with project_id and
+// user_id. Since microversion 1.28, consumer_generation enables consumer-
+// level concurrency control. Since microversion 1.38, a consumer_type field
+// (e.g. INSTANCE, MIGRATION) is supported. Returns 204 No Content on
+// success, or 409 Conflict if inventory is insufficient or a concurrent
+// update is detected (error code: placement.concurrent_update).
+func HandleManageAllocations(w http.ResponseWriter, r *http.Request) {
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path)
+}
+
+// HandleListAllocations handles GET /allocations/{consumer_uuid} requests.
+//
+// Returns all allocation records for the consumer identified by
+// {consumer_uuid}, across all resource providers. The response contains an
+// allocations dictionary keyed by resource provider UUID. If the consumer has
+// no allocations, an empty dictionary is returned.
+//
+// The response has grown across microversions: project_id and user_id were
+// added at 1.12, consumer_generation at 1.28, and consumer_type at 1.38.
+// The consumer_generation and consumer_type fields are absent when the
+// consumer has no allocations.
+func HandleListAllocations(w http.ResponseWriter, r *http.Request) {
+	consumerUUID := r.PathValue("consumer_uuid")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path,
+		"consumer_uuid", consumerUUID)
+}
+
+// HandleUpdateAllocations handles PUT /allocations/{consumer_uuid} requests.
+//
+// Creates or replaces all allocation records for a single consumer. If
+// allocations already exist for this consumer, they are entirely replaced
+// by the new set. The request format changed at microversion 1.12 from an
+// array-based layout to an object keyed by resource provider UUID.
+// Microversion 1.28 added consumer_generation for concurrency control,
+// and 1.38 introduced consumer_type.
+//
+// Returns 204 No Content on success. Returns 409 Conflict if there is
+// insufficient inventory or if a concurrent update was detected.
+func HandleUpdateAllocations(w http.ResponseWriter, r *http.Request) {
+	consumerUUID := r.PathValue("consumer_uuid")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path,
+		"consumer_uuid", consumerUUID)
+}
+
+// HandleDeleteAllocations handles DELETE /allocations/{consumer_uuid} requests.
+//
+// Removes all allocation records for the consumer across all resource
+// providers. Returns 204 No Content on success, or 404 Not Found if the
+// consumer has no existing allocations.
+func HandleDeleteAllocations(w http.ResponseWriter, r *http.Request) {
+	consumerUUID := r.PathValue("consumer_uuid")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path,
+		"consumer_uuid", consumerUUID)
+}

internal/shim/placement/handlers/reshaper.go

@@ -0,0 +1,30 @@
+// Copyright SAP SE
+// SPDX-License-Identifier: Apache-2.0
+
+package handlers
+
+import (
+	"net/http"
+
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+)
+
+// HandlePostReshaper handles POST /reshaper requests.
+//
+// Atomically migrates resource provider inventories and associated allocations
+// in a single transaction. This endpoint is used when a provider tree needs to
+// be restructured — for example, moving inventory from a root provider into
+// newly created child providers — without leaving allocations in an
+// inconsistent state during the transition.
+//
+// The request body contains the complete set of inventories (keyed by
+// resource provider UUID) and allocations (keyed by consumer UUID) that
+// should exist after the operation. The Placement service validates all
+// inputs atomically and applies them in a single database transaction.
+// Returns 204 No Content on success. Returns 409 Conflict if any referenced
+// resource provider does not exist or if inventory/allocation constraints
+// would be violated. Available since microversion 1.30.
+func HandlePostReshaper(w http.ResponseWriter, r *http.Request) {
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path)
+}

internal/shim/placement/handlers/resource_classes.go

@@ -0,0 +1,72 @@
+// Copyright SAP SE
+// SPDX-License-Identifier: Apache-2.0
+
+package handlers
+
+import (
+	"net/http"
+
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+)
+
+// HandleListResourceClasses handles GET /resource_classes requests.
+//
+// Returns the complete list of all resource classes, including both standard
+// classes (e.g. VCPU, MEMORY_MB, DISK_GB, PCI_DEVICE, SRIOV_NET_VF) and
+// deployer-defined custom classes prefixed with CUSTOM_. Resource classes
+// categorize the types of resources that resource providers can offer as
+// inventory. Available since microversion 1.2.
+func HandleListResourceClasses(w http.ResponseWriter, r *http.Request) {
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path)
+}
+
+// HandleCreateResourceClass handles POST /resource_classes requests.
+//
+// Creates a new custom resource class. The name must be prefixed with CUSTOM_
+// to distinguish it from standard resource classes. Returns 201 Created with
+// a Location header on success. Returns 400 Bad Request if the CUSTOM_ prefix
+// is missing, and 409 Conflict if a class with the same name already exists.
+// Available since microversion 1.2.
+func HandleCreateResourceClass(w http.ResponseWriter, r *http.Request) {
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path)
+}
+
+// HandleShowResourceClass handles GET /resource_classes/{name} requests.
+//
+// Returns a representation of a single resource class identified by name.
+// This can be used to verify the existence of a resource class. Returns 404
+// if the class does not exist. Available since microversion 1.2.
+func HandleShowResourceClass(w http.ResponseWriter, r *http.Request) {
+	name := r.PathValue("name")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path, "name", name)
+}
+
+// HandleUpdateResourceClass handles PUT /resource_classes/{name} requests.
+//
+// Behavior differs by microversion. Since microversion 1.7, this endpoint
+// creates or validates the existence of a single resource class: it returns
+// 201 Created for a new class or 204 No Content if the class already exists.
+// The name must carry the CUSTOM_ prefix. In earlier versions (1.2-1.6), the
+// endpoint allowed renaming a class via a request body, but this usage is
+// discouraged. Returns 400 Bad Request if the CUSTOM_ prefix is missing.
+func HandleUpdateResourceClass(w http.ResponseWriter, r *http.Request) {
+	name := r.PathValue("name")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path, "name", name)
+}
+
+// HandleDeleteResourceClass handles DELETE /resource_classes/{name} requests.
+//
+// Deletes a custom resource class. Only custom classes (prefixed with CUSTOM_)
+// may be deleted; attempting to delete a standard class returns 400 Bad
+// Request. Returns 409 Conflict if any resource provider has inventory of this
+// class, and 404 if the class does not exist. Returns 204 No Content on
+// success. Available since microversion 1.2.
+func HandleDeleteResourceClass(w http.ResponseWriter, r *http.Request) {
+	name := r.PathValue("name")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path, "name", name)
+}

internal/shim/placement/handlers/resource_provider_aggregates.go

@@ -0,0 +1,45 @@
+// Copyright SAP SE
+// SPDX-License-Identifier: Apache-2.0
+
+package handlers
+
+import (
+	"net/http"
+
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+)
+
+// HandleListResourceProviderAggregates handles
+// GET /resource_providers/{uuid}/aggregates requests.
+//
+// Returns the list of aggregate UUIDs associated with the resource provider.
+// Aggregates model relationships among providers such as shared storage,
+// affinity/anti-affinity groups, and availability zones. Returns an empty
+// list if the provider has no aggregate associations. Available since
+// microversion 1.1.
+//
+// The response format changed at microversion 1.19: earlier versions return
+// only a flat array of UUIDs, while 1.19+ returns an object that also
+// includes the resource_provider_generation for concurrency tracking. Returns
+// 404 if the provider does not exist.
+func HandleListResourceProviderAggregates(w http.ResponseWriter, r *http.Request) {
+	uuid := r.PathValue("uuid")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path, "uuid", uuid)
+}
+
+// HandleUpdateResourceProviderAggregates handles
+// PUT /resource_providers/{uuid}/aggregates requests.
+//
+// Replaces the complete set of aggregate associations for a resource provider.
+// Any aggregate UUIDs that do not yet exist are created automatically. The
+// request format changed at microversion 1.19: earlier versions accept a
+// plain array of UUIDs, while 1.19+ expects an object containing an
+// aggregates array and a resource_provider_generation for optimistic
+// concurrency control. Returns 409 Conflict if the generation does not match
+// (1.19+). Returns 200 with the updated aggregate list on success.
+func HandleUpdateResourceProviderAggregates(w http.ResponseWriter, r *http.Request) {
+	uuid := r.PathValue("uuid")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path, "uuid", uuid)
+}

internal/shim/placement/handlers/resource_provider_allocations.go

@@ -0,0 +1,24 @@
+// Copyright SAP SE
+// SPDX-License-Identifier: Apache-2.0
+
+package handlers
+
+import (
+	"net/http"
+
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+)
+
+// HandleListResourceProviderAllocations handles
+// GET /resource_providers/{uuid}/allocations requests.
+//
+// Returns all allocations made against the resource provider identified by
+// {uuid}, keyed by consumer UUID. This provides a provider-centric view of
+// consumption, complementing the consumer-centric GET /allocations/{consumer}
+// endpoint. The response includes the resource_provider_generation. Returns
+// 404 if the provider does not exist.
+func HandleListResourceProviderAllocations(w http.ResponseWriter, r *http.Request) {
+	uuid := r.PathValue("uuid")
+	log := logf.FromContext(r.Context())
+	log.Info("placement request", "method", r.Method, "path", r.URL.Path, "uuid", uuid)
+}