placement

func (*Shim) Collect ¶

func (s *Shim) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector.

func (*Shim) Describe ¶

func (s *Shim) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

func (*Shim) HandleCreateResourceClass ¶

func (s *Shim) HandleCreateResourceClass(w http.ResponseWriter, r *http.Request)

HandleCreateResourceClass handles POST /resource_classes requests.

See: https://docs.openstack.org/api-ref/placement/#create-resource-class

func (*Shim) HandleCreateResourceProvider ¶

func (s *Shim) HandleCreateResourceProvider(w http.ResponseWriter, r *http.Request)

HandleCreateResourceProvider handles POST /resource_providers requests.

Creates a new resource provider. The request must include a name and may optionally specify a UUID and a parent_provider_uuid (since 1.14) to place the provider in a hierarchical tree. If no UUID is supplied, one is generated. Returns 409 Conflict if a provider with the same name or UUID already exists.

See: https://docs.openstack.org/api-ref/placement/#create-resource-provider

func (*Shim) HandleDeleteAllocations ¶

func (s *Shim) HandleDeleteAllocations(w http.ResponseWriter, r *http.Request)

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 (*Shim) HandleDeleteResourceClass ¶

func (s *Shim) HandleDeleteResourceClass(w http.ResponseWriter, r *http.Request)

HandleDeleteResourceClass handles DELETE /resource_classes/{name} requests.

See: https://docs.openstack.org/api-ref/placement/#delete-resource-class

func (*Shim) HandleDeleteResourceProvider ¶

func (s *Shim) HandleDeleteResourceProvider(w http.ResponseWriter, r *http.Request)

HandleDeleteResourceProvider handles DELETE /resource_providers/{uuid} requests.

Deletes a resource provider and disassociates all its aggregates and inventories. The operation fails with 409 Conflict if there are any allocations against the provider's inventories or if the provider has child providers in a tree hierarchy. Returns 204 No Content on success.

See: https://docs.openstack.org/api-ref/placement/#delete-resource-provider

func (*Shim) HandleDeleteResourceProviderInventories ¶

func (s *Shim) HandleDeleteResourceProviderInventories(w http.ResponseWriter, r *http.Request)

HandleDeleteResourceProviderInventories handles DELETE /resource_providers/{uuid}/inventories requests.

Deletes all inventory records for a resource provider. This operation is not safe for concurrent use; the recommended alternative for concurrent environments is PUT with an empty inventories dictionary. Returns 409 Conflict if allocations exist against any of the provider's inventories. Returns 404 if the provider does not exist. Available since microversion 1.5.

func (*Shim) HandleDeleteResourceProviderInventory ¶

func (s *Shim) HandleDeleteResourceProviderInventory(w http.ResponseWriter, r *http.Request)

HandleDeleteResourceProviderInventory handles DELETE /resource_providers/{uuid}/inventories/{resource_class} requests.

Deletes the inventory record for a specific resource class on the provider. Returns 409 Conflict if allocations exist against this provider and resource class combination, or if a concurrent update has occurred. Returns 404 if the provider or inventory does not exist. Returns 204 No Content on success.

func (*Shim) HandleDeleteResourceProviderTraits ¶

func (s *Shim) HandleDeleteResourceProviderTraits(w http.ResponseWriter, r *http.Request)

HandleDeleteResourceProviderTraits handles DELETE /resource_providers/{uuid}/traits requests.

Removes all trait associations from a resource provider. Because this endpoint does not accept a resource_provider_generation, it is not safe for concurrent use. In environments where multiple clients manage traits for the same provider, prefer PUT with an empty traits list instead. Returns 404 if the provider does not exist. Returns 409 Conflict on concurrent modification. Returns 204 No Content on success.

https://docs.openstack.org/api-ref/placement/#delete-resource-provider-traits

func (*Shim) HandleDeleteTrait ¶

func (s *Shim) HandleDeleteTrait(w http.ResponseWriter, r *http.Request)

HandleDeleteTrait handles DELETE /traits/{name} requests.

See: https://docs.openstack.org/api-ref/placement/#delete-traits

func (*Shim) HandleGetRoot ¶

func (s *Shim) HandleGetRoot(w http.ResponseWriter, r *http.Request)

HandleGetRoot handles GET / requests.

Returns information about all known major versions of the Placement API, including the minimum and maximum supported microversions for each version. Currently only one major version (v1.0) exists. Each version entry includes its status (e.g. CURRENT), links for discovery, and the microversion range supported by the running service. Clients use this endpoint to discover API capabilities and negotiate microversions before making further requests.

See: https://docs.openstack.org/api-ref/placement/#list-versions

func (*Shim) HandleListAllocationCandidates ¶

func (s *Shim) HandleListAllocationCandidates(w http.ResponseWriter, r *http.Request)

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 (*Shim) HandleListAllocations ¶

func (s *Shim) HandleListAllocations(w http.ResponseWriter, r *http.Request)

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 (*Shim) HandleListResourceClasses ¶

func (s *Shim) HandleListResourceClasses(w http.ResponseWriter, r *http.Request)

HandleListResourceClasses handles GET /resource_classes requests.

See: https://docs.openstack.org/api-ref/placement/#list-resource-classes

func (*Shim) HandleListResourceProviderAggregates ¶

func (s *Shim) HandleListResourceProviderAggregates(w http.ResponseWriter, r *http.Request)

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.

https://docs.openstack.org/api-ref/placement/#list-resource-provider-aggregates

func (*Shim) HandleListResourceProviderAllocations ¶

func (s *Shim) HandleListResourceProviderAllocations(w http.ResponseWriter, r *http.Request)

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 (*Shim) HandleListResourceProviderInventories ¶

func (s *Shim) HandleListResourceProviderInventories(w http.ResponseWriter, r *http.Request)

HandleListResourceProviderInventories handles GET /resource_providers/{uuid}/inventories requests.

Returns all inventory records for the resource provider identified by {uuid}. The response contains an inventories dictionary keyed by resource class, with each entry describing capacity constraints: total, reserved, min_unit, max_unit, step_size, and allocation_ratio. Also returns the resource_provider_generation, which is needed for subsequent update or delete operations. Returns 404 if the provider does not exist.

func (*Shim) HandleListResourceProviderTraits ¶

func (s *Shim) HandleListResourceProviderTraits(w http.ResponseWriter, r *http.Request)

HandleListResourceProviderTraits handles GET /resource_providers/{uuid}/traits requests.

Returns the list of traits associated with the resource provider identified by {uuid}. The response includes an array of trait name strings and the resource_provider_generation for concurrency tracking. Returns 404 if the provider does not exist.

https://docs.openstack.org/api-ref/placement/#list-resource-provider-traits

func (*Shim) HandleListResourceProviderUsages ¶

func (s *Shim) HandleListResourceProviderUsages(w http.ResponseWriter, r *http.Request)

HandleListResourceProviderUsages handles GET /resource_providers/{uuid}/usages requests.

Returns aggregated resource consumption for the resource provider identified by {uuid}. The response contains a usages dictionary keyed by resource class with integer usage amounts, along with the resource_provider_generation. Unlike the provider allocations endpoint, this does not break down usage by individual consumer. Returns 404 if the provider does not exist.

func (*Shim) HandleListResourceProviders ¶

func (s *Shim) HandleListResourceProviders(w http.ResponseWriter, r *http.Request)

HandleListResourceProviders handles GET /resource_providers requests.

Returns a filtered list of resource providers. Resource providers are entities that provide consumable inventory of one or more classes of resources (e.g. a compute node providing VCPU, MEMORY_MB, DISK_GB).

Supports numerous filter parameters including name, uuid, member_of (aggregate membership), resources (capacity filtering), in_tree (provider tree membership), and required (trait filtering).

See: https://docs.openstack.org/api-ref/placement/#list-resource-providers

func (*Shim) HandleListTraits ¶

func (s *Shim) HandleListTraits(w http.ResponseWriter, r *http.Request)

HandleListTraits handles GET /traits requests.

See: https://docs.openstack.org/api-ref/placement/#list-traits

func (*Shim) HandleListUsages ¶

func (s *Shim) HandleListUsages(w http.ResponseWriter, r *http.Request)

HandleListUsages handles GET /usages requests.

Returns a report of aggregated resource usage for a given project, and optionally a specific user within that project. The project_id query parameter is required; user_id is optional.

The response format changed at microversion 1.38: earlier versions return a flat dictionary of resource class to usage totals, while 1.38+ groups usages by consumer_type (e.g. INSTANCE, MIGRATION, all, unknown), with each group containing resource totals and a consumer_count. Since microversion 1.38, an optional consumer_type query parameter allows filtering the results. Available since microversion 1.9.

func (*Shim) HandleManageAllocations ¶

func (s *Shim) HandleManageAllocations(w http.ResponseWriter, r *http.Request)

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 (*Shim) HandlePostReshaper ¶

func (s *Shim) HandlePostReshaper(w http.ResponseWriter, r *http.Request)

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 (*Shim) HandleShowResourceClass ¶

func (s *Shim) HandleShowResourceClass(w http.ResponseWriter, r *http.Request)

HandleShowResourceClass handles GET /resource_classes/{name} requests.

See: https://docs.openstack.org/api-ref/placement/#show-resource-class

func (*Shim) HandleShowResourceProvider ¶

func (s *Shim) HandleShowResourceProvider(w http.ResponseWriter, r *http.Request)

HandleShowResourceProvider handles GET /resource_providers/{uuid} requests.

Returns a single resource provider identified by its UUID. The response includes the provider's name, generation (used for concurrency control in subsequent updates), and links. Returns 404 if the provider does not exist.

See: https://docs.openstack.org/api-ref/placement/#show-resource-provider

func (*Shim) HandleShowResourceProviderInventory ¶

func (s *Shim) HandleShowResourceProviderInventory(w http.ResponseWriter, r *http.Request)

HandleShowResourceProviderInventory handles GET /resource_providers/{uuid}/inventories/{resource_class} requests.

Returns a single inventory record for one resource class on the specified provider. The response includes total, reserved, min_unit, max_unit, step_size, allocation_ratio, and the resource_provider_generation. Returns 404 if the provider or inventory for that class does not exist.

func (*Shim) HandleShowTrait ¶

func (s *Shim) HandleShowTrait(w http.ResponseWriter, r *http.Request)

HandleShowTrait handles GET /traits/{name} requests.

See: https://docs.openstack.org/api-ref/placement/#show-traits

func (*Shim) HandleUpdateAllocations ¶

func (s *Shim) HandleUpdateAllocations(w http.ResponseWriter, r *http.Request)

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 (*Shim) HandleUpdateResourceClass ¶

func (s *Shim) HandleUpdateResourceClass(w http.ResponseWriter, r *http.Request)

HandleUpdateResourceClass handles PUT /resource_classes/{name} requests.

See: https://docs.openstack.org/api-ref/placement/#update-resource-class

func (*Shim) HandleUpdateResourceProvider ¶

func (s *Shim) HandleUpdateResourceProvider(w http.ResponseWriter, r *http.Request)

HandleUpdateResourceProvider handles PUT /resource_providers/{uuid} requests.

Updates a resource provider's name and, starting at microversion 1.14, its parent_provider_uuid. Returns 409 Conflict if another provider already has the requested name.

See: https://docs.openstack.org/api-ref/placement/#update-resource-provider

func (*Shim) HandleUpdateResourceProviderAggregates ¶

func (s *Shim) HandleUpdateResourceProviderAggregates(w http.ResponseWriter, r *http.Request)

HandleUpdateResourceProviderAggregates handles PUT /resource_providers/{uuid}/aggregates requests.

Replaces the complete set of aggregate associations for a resource provider. The request body must include an aggregates array and a resource_provider_generation for optimistic concurrency control. Returns 409 Conflict if the generation does not match. Returns 200 with the updated aggregate list on success.

https://docs.openstack.org/api-ref/placement/#update-resource-provider-aggregates

func (*Shim) HandleUpdateResourceProviderInventories ¶

func (s *Shim) HandleUpdateResourceProviderInventories(w http.ResponseWriter, r *http.Request)

HandleUpdateResourceProviderInventories handles PUT /resource_providers/{uuid}/inventories requests.

Atomically replaces the entire set of inventory records for a provider. The request must include the resource_provider_generation for optimistic concurrency control — if the generation does not match, the request fails with 409 Conflict. The inventories field is a dictionary keyed by resource class, each specifying at minimum a total value. Omitted inventory classes are deleted. Returns 409 Conflict if allocations exceed the new capacity or if a concurrent update has occurred.

func (*Shim) HandleUpdateResourceProviderInventory ¶

func (s *Shim) HandleUpdateResourceProviderInventory(w http.ResponseWriter, r *http.Request)

HandleUpdateResourceProviderInventory handles PUT /resource_providers/{uuid}/inventories/{resource_class} requests.

Creates or replaces the inventory record for a single resource class on the provider. The request must include resource_provider_generation for concurrency control and a total value. Optional fields control allocation constraints (allocation_ratio, min_unit, max_unit, step_size, reserved). Since microversion 1.26, the reserved value must not exceed total. Returns 409 Conflict on generation mismatch or if allocations would be violated.

func (*Shim) HandleUpdateResourceProviderTraits ¶

func (s *Shim) HandleUpdateResourceProviderTraits(w http.ResponseWriter, r *http.Request)

HandleUpdateResourceProviderTraits handles PUT /resource_providers/{uuid}/traits requests.

Replaces the complete set of trait associations for a resource provider. The request body must include a traits array and the resource_provider_generation for optimistic concurrency control. All previously associated traits are removed and replaced by the specified set. Returns 409 Conflict if the generation does not match.

https://docs.openstack.org/api-ref/placement/#update-resource-provider-traits

func (*Shim) HandleUpdateTrait ¶

func (s *Shim) HandleUpdateTrait(w http.ResponseWriter, r *http.Request)

HandleUpdateTrait handles PUT /traits/{name} requests.

See: https://docs.openstack.org/api-ref/placement/#update-trait

func (*Shim) Init ¶

func (s *Shim) Init(ctx context.Context) (err error)

Init performs the once-only, manager-independent setup of the shim: it loads and validates the shim config, compiles the auth policies, allocates the Prometheus metric vectors, and initializes the upstream HTTP client and Keystone token introspector. It must be called exactly once per process (before RegisterRoutes and before the metric collectors are registered), because it allocates collectors and the HTTP request path depends on the fields it sets. It is intentionally decoupled from the controller-manager lifecycle so that the HTTP layer survives manager restarts (see pkg/shim/supervisor).

func (*Shim) ManagerReady ¶

func (s *Shim) ManagerReady() bool

ManagerReady reports whether a controller-manager with a synced cache is currently running. Cache-backed handlers should gate on it and return 503 when it is false; passthrough handlers, which never touch the cache, ignore it. It defaults to false until the supervisor brings the first manager up. Safe to call concurrently once Init has allocated the holder (see SetManagerReady).

func (*Shim) Reconcile ¶

func (s *Shim) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

Reconcile is not used by the shim, but must be implemented to satisfy the controller-runtime Reconciler interface.

func (*Shim) RegisterRoutes ¶

func (s *Shim) RegisterRoutes(mux *http.ServeMux)

RegisterRoutes binds all Placement API handlers to the given mux. The route patterns use the Go 1.22+ ServeMux syntax with explicit HTTP methods and path wildcards. The routes mirror the OpenStack Placement API surface as documented at https://docs.openstack.org/api-ref/placement/.

func (*Shim) SetManagerReady ¶

func (s *Shim) SetManagerReady(ready bool)

SetManagerReady records whether a controller-manager with a synced cache is currently running. The self-healing supervisor sets it true once the cache has synced and false when the manager cycle ends (see pkg/shim/supervisor and cmd/shim).

Once Init has run, the holder is allocated and calls to SetManagerReady and ManagerReady are race-free (they only load/store the atomic). The nil guard below is a convenience for shims constructed in tests without Init; in that case the first SetManagerReady is NOT safe to race with a concurrent ManagerReady, since it may write the s.managerReady pointer itself. Production code always goes through Init before serving, so this is not a concern there.

func (*Shim) SetupControllerWithManager ¶

func (s *Shim) SetupControllerWithManager(ctx context.Context, mgr ctrl.Manager, mcl *multicluster.Client) error

SetupControllerWithManager wires the shim's Hypervisor watch into the given manager, backed by the given multicluster client. It sets up the field indexes and registers a watch across all clusters serving the Hypervisor GVK. Unlike Init, this is called once per manager cycle: the self-healing supervisor rebuilds the manager (and its caches) on connectivity failure and calls this again for the fresh manager. It does NOT touch the HTTP layer, metric collectors, or config.