Document a warning about using the JsonFilter

People hit problems using the JsonFilter from time to time
and at least I always have to re-learn what it does and am
somewhat horrified to find how flexible it is based on using
HostState attributes as filtering variables, not to mention
we don't do any functional testing with it. The docs are also
misleading in stating it only supports a subset of variables
when it's really anything on the HostState object. A common
case is people filtering on the hypervisor_hostname attribute
to schedule directly to a specific baremetal node with ironic.

This change adds a warning recommending to not use the filter
if possible and find alternatives, like traits. It also mentions
the HostState object as defining the variables that can be used
along with adding the commonly-used hypervisor_hostname variable
to the list.

Change-Id: Ib2b1395715b6bdb25f53ee7c68df44e2d84b895b
Related-Bug: #1821764

doc/source/admin/configuration/schedulers.rst

@@ -562,6 +562,14 @@ migrate, rescue or unshelve task states are running on it.
 JsonFilter
 ----------
 
+.. warning:: This filter is not enabled by default and not comprehensively
+    tested, and thus could fail to work as expected in non-obvious ways.
+    Furthermore, the filter variables are based on attributes of the
+    `HostState`_ class which could change from release to release so usage
+    of this filter is generally not recommended. Consider using other filters
+    such as the :ref:`ImagePropertiesFilter` or
+    :ref:`traits-based scheduling <extra-specs-required-traits>`.
+
 The JsonFilter allows a user to construct a custom filter by passing a
 scheduler hint in JSON format. The following operators are supported:
 
@@ -575,10 +583,12 @@ scheduler hint in JSON format. The following operators are supported:
 * or
 * and
 
-The filter supports the following variables:
+The filter supports any attribute in the `HostState`_ class such as the
+following variables:
 
 * ``$free_ram_mb``
 * ``$free_disk_mb``
+* ``$hypervisor_hostname``
 * ``$total_usable_ram_mb``
 * ``$vcpus_total``
 * ``$vcpus_used``
@@ -605,6 +615,8 @@ With the API, use the ``os:scheduler_hints`` key:
        }
    }
 
+.. _HostState: http://git.openstack.org/cgit/openstack/nova/tree/nova/scheduler/host_manager.py
+
 MetricsFilter
 -------------