From a4609a834b1eaf5013f7da8580628ecd1d51227d Mon Sep 17 00:00:00 2001
From: Matt Riedemann <mriedem.os@gmail.com>
Date: Thu, 31 Aug 2017 15:50:29 -0400
Subject: [PATCH] api-ref: add warnings about forcing the host for live
 migrate/evacuate

Bypassing the scheduler during a live migration or evacuation
is not something we want people to be doing as it can easily fail
if the specified host is already full or doesn't provide something
required by the instance, plus it's a nightmare for tracking allocations
in the Placement service when we're bypassing the scheduler.

Because of this, we should have some warnings in the API reference
about doing this, which this patch adds.

Change-Id: I85e7c2677f4d5eccc1e7f349de06960b53ef148d
---
 api-ref/source/parameters.yaml | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 3a062e620d3e..ec4b893ab2a1 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -2680,6 +2680,11 @@ force_evacuate:
   description: |
     Force an evacuation by not verifying the provided destination host by the
     scheduler.
+
+    .. warning:: This could result in failures to actually evacuate the
+      instance to the specified host. It is recommended to either not specify
+      a host so that the scheduler will pick one, or specify a host without
+      ``force=True`` set.
   in: body
   required: false
   type: boolean
@@ -2688,6 +2693,11 @@ force_live_migrate:
   description: |
     Force a live-migration by not verifying the provided destination host by
     the scheduler.
+
+    .. warning:: This could result in failures to actually live migrate the
+      instance to the specified host. It is recommended to either not specify
+      a host so that the scheduler will pick one, or specify a host without
+      ``force=True`` set.
   in: body
   required: false
   type: boolean
@@ -2777,6 +2787,13 @@ host:
   description: |
     The name or ID of the host to which the server is evacuated.
     If you omit this parameter, the scheduler chooses a host.
+
+    .. warning:: Prior to microversion 2.29, specifying a host will bypass
+      validation by the scheduler, which could result in failures to actually
+      evacuate the instance to the specified host, or over-subscription of the
+      host. It is recommended to either not specify a host so that the
+      scheduler will pick one, or specify a host with microversion >= 2.29 and
+      without ``force=True`` set.
   in: body
   required: false
   type: string
@@ -2825,8 +2842,15 @@ host_memory_mb:
   type: integer
 host_migration:
   description: |
-    The host to which to migrate the server. If this parameter is ``None``, the scheduler
-    chooses a host.
+    The host to which to migrate the server. If this parameter is ``None``,
+    the scheduler chooses a host.
+
+    .. warning:: Prior to microversion 2.30, specifying a host will bypass
+      validation by the scheduler, which could result in failures to actually
+      migrate the instance to the specified host, or over-subscription of the
+      host. It is recommended to either not specify a host so that the
+      scheduler will pick one, or specify a host with microversion >= 2.30 and
+      without ``force=True`` set.
   in: body
   required: true
   type: string