placement — Scenarios

sequenceDiagram
  autonumber
  participant NC as nova-compute (resource tracker)
  participant P as placement-api
  participant DB as MariaDB (placement)

  NC->>P: GET /resource_providers?in_tree=<host uuid> (1.14+)
  P->>DB: SELECT resource_providers …
  alt unknown host
    NC->>P: POST /resource_providers {name, uuid}
    P->>DB: INSERT resource_providers (generation = 0, root = itself)
    alt name or uuid already taken
      P-->>NC: 409 placement.duplicate_name
    else
      P-->>NC: 200 {generation: 0, …}
    end
  end
  NC->>P: PUT /resource_providers/{uuid}/inventories {resource_provider_generation: g, inventories: {VCPU, MEMORY_MB, DISK_GB}}
  P->>DB: SELECT inventories; DELETE/INSERT/UPDATE inventories; UPDATE resource_providers SET generation = g+1 WHERE generation = g
  alt stale generation
    P-->>NC: 409 placement.concurrent_update
    Note over NC: Nova re-reads the provider and starts again [inferred]
  else a removed class is still allocated
    P-->>NC: 409 placement.inventory.inuse
  else total reduced below current usage
    P-->>NC: 200, and the Placement log shows WARNING … is now over-capacity
  else
    P-->>NC: 200 {resource_provider_generation: g+1, inventories}
  end
  NC->>P: PUT /resource_providers/{uuid}/traits {resource_provider_generation, traits: [HW_CPU_X86_AVX2, COMPUTE_…]}
  P->>DB: DELETE/INSERT resource_provider_traits; UPDATE generation
  P-->>NC: 200
  NC->>P: PUT /resource_providers/{uuid}/aggregates {aggregates, resource_provider_generation}
  P-->>NC: 200
  loop every ~60 s (Nova's update_available_resource) [inferred]
    NC->>P: PUT …/inventories (only when the inventory changed on the Nova side) [inferred]
  end

sequenceDiagram
  autonumber
  participant S as nova-scheduler
  participant P as placement-api
  participant DB as MariaDB

  S->>P: GET /allocation_candidates?resources=VCPU:2,MEMORY_MB:4096,DISK_GB:20&required=!COMPUTE_STATUS_DISABLED&member_of=…&limit=1000
  P->>DB: providers with free capacity (one query per class) + trait/aggregate filters + usages per tree
  P->>P: per-tree overall capacity pre-check (bug 2160721 fix), then Cartesian product
  alt unknown class or trait, invalid syntax
    P-->>S: 400 (placement.query.bad_value…)
  else no possible host
    P-->>S: 200 {allocation_requests: [], provider_summaries: {}}
    Note over S: NoValidHost on the Nova side [inferred]
  else
    P-->>S: 200 {allocation_requests: [...], provider_summaries: {...}}
  end
  Note over S: Nova filters and weighers, choice of one candidate [inferred]
  S->>P: PUT /allocations/{instance_uuid} {allocations of the candidate, project_id, user_id, consumer_generation: null, consumer_type: INSTANCE}
  P->>DB: INSERT projects/users/consumers if needed
  P->>DB: transaction: DELETE consumer allocations; capacity check; INSERT allocations; UPDATE generation (providers, consumer)
  alt another scheduler took the space meanwhile (provider generation changed)
    P->>P: re-read and retry (up to allocation_conflict_retry_count = 10)
    alt capacity still enough
      P-->>S: 204
    else capacity exhausted
      P-->>S: 409 "… would exceed the capacity"
      Note over S: Nova tries the next candidate [inferred]
    end
  else consumer_generation ≠ null for a new consumer
    P-->>S: 409 placement.concurrent_update (no server-side retry)
  else
    P-->>S: 204
  end

sequenceDiagram
  autonumber
  participant C as nova-conductor
  participant P as placement-api
  participant DB as MariaDB

  C->>P: GET /allocations/{instance}
  P-->>C: 200 {allocations: {source: …}, consumer_generation: 5}
  C->>P: POST /allocations {instance: {allocations: {}, consumer_generation: 5}, migration: {allocations: {source: …}, consumer_generation: null, consumer_type: MIGRATION}}
  Note over P: the source allocations move from the instance to the migration
  P->>DB: one transaction: replacement of both consumers' allocations, generations +1
  alt instance modified meanwhile
    P-->>C: 409 placement.concurrent_update
  else
    P-->>C: 204
  end
  Note over C: scheduling of the target (scenario 2) with PUT /allocations/{instance} on the target [inferred]
  Note over C: on confirm: DELETE /allocations/{migration}; on revert: allocations given back to the instance [inferred]

sequenceDiagram
  autonumber
  participant NC as nova-compute (driver upgrade)
  participant P as placement-api
  participant DB as MariaDB

  NC->>P: POST /resource_providers {name: host_pGPU1, parent_provider_uuid: host} (×N)
  P-->>NC: 200
  NC->>P: POST /reshaper (service role) {inventories: {host: {gen, inventories without VGPU}, pGPU1: {gen, VGPU}}, allocations: {instances: {…on pGPU1…}}}
  alt admin role only
    P-->>NC: 403
  else stale provider generation
    P-->>NC: 409 placement.concurrent_update
  else unknown provider
    P-->>NC: 400 placement.resource_provider.not_found
  else
    P->>DB: one transaction: new inventories, new allocations, generations
    P-->>NC: 204
  end

sequenceDiagram
  autonumber
  participant A as nova-compute / administrator
  participant P as placement-api
  participant DB as MariaDB

  A->>P: DELETE /resource_providers/{host}
  P->>DB: SELECT children; SELECT COUNT allocations
  alt child providers present
    P-->>A: 409 placement.resource_provider.cannot_delete_parent
    Note over A: delete the children first
  else allocations present
    P-->>A: 409 placement.resource_provider.inuse
    Note over A: delete or move the allocations (instances, migrations)
  else
    P->>DB: DELETE inventories, resource_provider_aggregates, resource_provider_traits, resource_providers
    P-->>A: 204
  end