From a6fcfb28ae203fdd7b20380c3fb1e0f25ea7e723 Mon Sep 17 00:00:00 2001 From: Matt Riedemann Date: Mon, 30 Oct 2017 16:14:28 -0400 Subject: [PATCH] api-ref: document caveats with scheduler hints I noticed this while working on change I49ffebcd129990f1835f404d98b51732a32171eb and I realized the scheduler_hints in the legacy filter_properties dict is a bit different than what's in the RequestSpec object, namely that the request validation schema is per-hint. Some require a single value, like 'group', and some accept a list of values, like 'different_host'. Given how nebulous scheduler hints are, we should probably note these in the API reference for the parameter, especially because scheduler hints should not be considered interoperable. Change-Id: I74114fc56bee2bebf4a5f5d6823ec968cad9a8e9 --- api-ref/source/parameters.yaml | 14 +++++++++++++- .../openstack/compute/schemas/scheduler_hints.py | 2 +- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 28ce88166e84..ded7a57472e5 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -4436,7 +4436,19 @@ os-stop: os:scheduler_hints: description: | The dictionary of data to send to the scheduler. Alternatively, you can specify - ``OS-SCH-HNT:scheduler_hints`` as the string. + ``OS-SCH-HNT:scheduler_hints`` as the key in the request body. + + There are a few caveats with scheduler hints: + + * The request validation schema is per hint. For example, some require a + single string value, and some accept a list of values. + * Hints are only used based on the cloud scheduler configuration, which + varies per deployment. + * Hints are pluggable per deployment, meaning that a cloud can have custom + hints which may not be available in another cloud. + + For these reasons, it is important to consult each cloud's user + documentation to know what is available for scheduler hints. in: body required: false type: object diff --git a/nova/api/openstack/compute/schemas/scheduler_hints.py b/nova/api/openstack/compute/schemas/scheduler_hints.py index 40aa1f31b170..2994d94d52cc 100644 --- a/nova/api/openstack/compute/schemas/scheduler_hints.py +++ b/nova/api/openstack/compute/schemas/scheduler_hints.py @@ -39,7 +39,7 @@ _hints = { ] }, 'same_host': { - # NOTE: The value of 'different_host' is the set of server + # NOTE: The value of 'same_host' is the set of server # uuids where a new server is scheduled on the same host. 'type': ['string', 'array'], 'items': parameter_types.server_id