Placement API¶

References¶

For an overview of some of the features provided by placement, see Placement Usage.

For a command line reference, see Command-line Utilities.

For installation, see the installation reference.

See the Configuration Guide for information on configuring the system, including role-based access control policy rules.

See the Contributor Guide for information on how to contribute to the placement project and development processes and guidelines.

Significant feature developments are tracked in documents called specifications. From the Train cycle onward, those documents are kept at Placement Specifications. Prior to that, Placement specifications were a part of the Nova Specs.

The following specifications represent the stages of design and development of resource providers and the Placement service. Implementation details may have changed or be partially complete at this time.

• Generic Resource Pools

• Compute Node Inventory

• Resource Provider Allocations

• Resource Provider Base Models

• Nested Resource Providers

• Custom Resource Classes

• Scheduler Filters in DB

• Scheduler claiming resources to the Placement API

• The Traits API - Manage Traits with ResourceProvider

• Request Traits During Scheduling

• filter allocation candidates by aggregate membership

• perform granular allocation candidate requests

• inventory and allocation data migration (reshaping provider trees)

• handle allocation updates in a safe way

Steps¶

1. Deploy the API service

Placement provides a placement-api WSGI script for running the service with Apache, nginx or other WSGI-capable web servers. Depending on what packaging solution is used to deploy OpenStack, the WSGI script may be in /usr/bin or /usr/local/bin.

placement-api, as a standard WSGI script, provides a module level application attribute that most WSGI servers expect to find. This means it is possible to run it with lots of different servers, providing flexibility in the face of different deployment scenarios. Common scenarios include:

• apache2 with mod_wsgi

• apache2 with mod_proxy_uwsgi

• nginx with uwsgi

• nginx with gunicorn

In all of these scenarios the host, port and mounting path (or prefix) of the application is controlled in the web server’s configuration, not in the configuration (placement.conf) of the placement application.

When placement was first added to DevStack it used the mod_wsgi style. Later it was updated to use mod_proxy_uwsgi. Looking at those changes can be useful for understanding the relevant options.

DevStack is configured to host placement at /placement on either the default port for http or for https (80 or 443) depending on whether TLS is being used. Using a default port is desirable.

By default, the placement application will get its configuration for settings such as the database connection URL from /etc/placement/placement.conf. The directory the configuration file will be found in can be changed by setting OS_PLACEMENT_CONFIG_DIR in the environment of the process that starts the application. With recent releases of oslo.config, configuration options may also be set in the environment.

This document refrains from declaring a set of installation instructions for the placement service. This is because a major point of having a WSGI application is to make the deployment as flexible as possible. Because the placement API service is itself stateless (all state is in the database), it is possible to deploy as many servers as desired behind a load balancing solution for robust and simple scaling. If you familiarize yourself with installing generic WSGI applications (using the links in the common scenarios list, above), those techniques will be applicable here.

2. Synchronize the database

The placement service uses its own database, defined in the placement_database section of configuration. The placement_database.connection option must be set or the service will not start. The command line tool placement-manage can be used to migrate the database tables to their correct form, including creating them. The database described by the connection option must already exist and have appropriate access controls defined.

Another option for synchronization is to set placement_database.sync_on_startup to True in configuration. This will perform any missing database migrations as the placement web service starts. Whether you choose to sync automaticaly or use the command line tool depends on the constraints of your environment and deployment tooling.

3. Create accounts and update the service catalog

Create a placement service user with an admin role in Keystone.

The placement API is a separate service and thus should be registered under a placement service type in the service catalog. Clients of placement, such as the resource tracker in the nova-compute node, will use the service catalog to find the placement endpoint.

See Configure User and Endpoints for examples of creating the service user and catalog entries.

Devstack sets up the placement service on the default HTTP port (80) with a /placement prefix instead of using an independent port.

Stein (1.0.0)¶

If you are upgrading an existing OpenStack installation from Rocky to Stein, and wish to use the newly extracted placement, you will need to copy some data and configuration settings from nova. See Upgrading from Nova to Placement for details of one way to manage this. The overview is:

• Configuration and policy files are, by default, located in /etc/placement.

• The placement server side settings in nova.conf should be moved to a separate placement configuration file placement.conf.

• The default configuration value of [placement]/policy_file is changed from placement-policy.yaml to policy.yaml

• Several tables in the nova_api database need to be migrated to a new placement database.

Following these steps will ensure that future changes to placement configuration and code will not conflict with your setup.

As stated above, using the extracted placement code is not required in Stein, there is a copy in the Stein release of Nova. However that code will be deleted in the Train cycle so you must upgrade to external Placement prior to upgrading to Train.

Microversions¶

The placement API uses microversions for making incremental changes to the API which client requests must opt into.

It is especially important to keep in mind that nova-compute is a client of the placement REST API and based on how Nova supports rolling upgrades the nova-compute service could be Newton level code making requests to an Ocata placement API, and vice-versa, an Ocata compute service in a cells v2 cell could be making requests to a Newton placement API.

This history of placement microversions may be found in REST API Version History.