RAPI: Document all feature strings

- Use constants and an assertion
- Update documentation for node migration

Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>

diff --git a/doc/rapi.rst b/doc/rapi.rst
index e1ee709..7ba3360 100644 (file)
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -330,10 +330,23 @@ Redistribute configuration to all nodes. The result will be a job id.
 Returns a list of features supported by the RAPI server. Available
 features:
 
-``instance-create-reqv1``
+.. pyassert::
+
+  rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1,
+                             rlib2._INST_REINSTALL_REQV1,
+                             rlib2._NODE_MIGRATE_REQV1,
+                             rlib2._NODE_EVAC_RES1])
+
+:pyeval:`rlib2._INST_CREATE_REQV1`
   Instance creation request data version 1 supported.
-``instance-reinstall-reqv1``
+:pyeval:`rlib2._INST_REINSTALL_REQV1`
   Instance reinstall supports body parameters.
+:pyeval:`rlib2._NODE_MIGRATE_REQV1`
+  Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
+  request body parameters.
+:pyeval:`rlib2._NODE_EVAC_RES1`
+  Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
+  a new-style result (see resource description)
 
 
 ``/2/modify``
@@ -1192,13 +1205,14 @@ It supports the following commands: ``POST``.
 ~~~~~~~~
 
 If no mode is explicitly specified, each instances' hypervisor default
-migration mode will be used. Query parameters:
+migration mode will be used. Body parameters:
+
+.. opcode_params:: OP_NODE_MIGRATE
+   :exclude: node_name
 
-``live`` (bool)
-  If set, use live migration if available.
-``mode`` (string)
-  Sets migration mode, ``live`` for live migration and ``non-live`` for
-  non-live migration. Supported by Ganeti 2.2 and above.
+The query arguments used up to and including Ganeti 2.4 are deprecated
+and should no longer be used. The new request format can be detected by
+the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.
 
 
 ``/2/nodes/[node_name]/role``

diff --git a/lib/build/sphinx_ext.py b/lib/build/sphinx_ext.py
index cc601bb..cceb9b8 100644 (file)
--- a/lib/build/sphinx_ext.py
+++ b/lib/build/sphinx_ext.py
@@ -39,12 +39,16 @@ from ganeti import errors
 from ganeti import utils
 from ganeti import opcodes
 from ganeti import ht
+from ganeti import rapi
+
+import ganeti.rapi.rlib2
 
 
 COMMON_PARAM_NAMES = map(operator.itemgetter(0), opcodes.OpCode.OP_PARAMS)
 
 #: Namespace for evaluating expressions
-EVAL_NS = dict(compat=compat, constants=constants, utils=utils, errors=errors)
+EVAL_NS = dict(compat=compat, constants=constants, utils=utils, errors=errors,
+               rlib2=rapi.rlib2)
 
 
 class OpcodeError(sphinx.errors.SphinxError):

diff --git a/lib/rapi/rlib2.py b/lib/rapi/rlib2.py
index 6494170..8d14ae4 100644 (file)
--- a/lib/rapi/rlib2.py
+++ b/lib/rapi/rlib2.py
@@ -110,6 +110,13 @@ _NODE_MIGRATE_REQV1 = "node-migrate-reqv1"
 # Feature string for node evacuation with LU-generated jobs
 _NODE_EVAC_RES1 = "node-evac-res1"
 
+ALL_FEATURES = frozenset([
+  _INST_CREATE_REQV1,
+  _INST_REINSTALL_REQV1,
+  _NODE_MIGRATE_REQV1,
+  _NODE_EVAC_RES1,
+  ])
+
 # Timeout for /2/jobs/[job_id]/wait. Gives job up to 10 seconds to change.
 _WFJC_TIMEOUT = 10
 
@@ -151,8 +158,7 @@ class R_2_features(baserlib.R_Generic):
     """Returns list of optional RAPI features implemented.
 
     """
-    return [_INST_CREATE_REQV1, _INST_REINSTALL_REQV1, _NODE_MIGRATE_REQV1,
-            _NODE_EVAC_RES1]
+    return list(ALL_FEATURES)
 
 
 class R_2_os(baserlib.R_Generic):