Update api-guide and api-ref to be clear about forced-down

Closes-Bug: #1691871
Related-Bug: #1784826

Change-Id: Ifc6f1549d88a1b7d9f6e25c962c8a15dd8e180fb

api-guide/source/general_info.rst

@@ -182,6 +182,10 @@ on compute hosts rather than servers.
 
 -  **Services Actions**
 
+   .. note::
+      The services actions described in this section apply only to
+      **nova-compute** services.
+
    - **enable, disable, disable-log-reason**
 
      The service can be disabled to indicate the service is not available anymore.
@@ -196,13 +200,24 @@ on compute hosts rather than servers.
      .. note::
        This action is enabled in microversion 2.11.
 
-     This action allows you set the state of service down immediately. Actually
-     Nova only provides the health monitor of service status, there isn't any
-     guarantee about health status of other parts of infrastructure, like the
-     health status of data network, storage network and other components. The
-     more complete health monitor of infrastructure is provided by external
-     system normally. An external health monitor system can mark the service
-     down for notifying the fault.
+     This action allows you set the state of service down immediately. Nova
+     only provides a very basic health monitor of service status, there isn't
+     any guarantee about health status of other parts of infrastructure, like
+     the health status of data network, storage network and other
+     components.
+
+     If you have a more extensive health monitoring system external to Nova,
+     and know that the service in question is dead (and disconnected from the
+     network), this can be used to tell the rest of Nova it can trust that this
+     service is never coming back, and allow actions such as evacuate.
+
+     .. warning::
+
+        This must *only* be used if you have fully fenced the service in
+        question, and that it can never send updates to the rest of the
+        system. This can be done by powering off the node or completely
+        isolating its networking. If you force-down a service that is not
+        fenced you can corrupt the VMs that were running on that host.
 
 -  **Hosts**
 

api-ref/source/os-services.inc

@@ -195,7 +195,16 @@ Update Forced Down
 
 .. rest_method:: PUT /os-services/force-down
 
-Set or unset ``forced_down`` flag for the service.
+Set or unset ``forced_down`` flag for the service. ``forced_down`` is a manual
+override to tell nova that the service in question has been fenced manually by
+the operations team (either hard powered off, or network unplugged). That
+signals that it is safe to proceed with ``evacuate`` or other operations that
+nova has safety checks to prevent for hosts that are up.
+
+.. warning::
+
+   Setting a service forced down without completely fencing it will likely
+   result in the corruption of VMs on that host.
 
 Action ``force-down`` available as of microversion 2.11.
 

api-ref/source/parameters.yaml

@@ -3085,8 +3085,9 @@ force_snapshot:
 forced_down_2_11:
   description: |
     Whether or not this service was forced down manually by an
-    administrator. This value is useful to know that some 3rd party has
-    verified the service should be marked down.
+    administrator after the service was fenced. This value is useful
+    to know that some 3rd party has verified the service should be
+    marked down.
   in: body
   required: true
   type: boolean
@@ -3095,9 +3096,17 @@ forced_down_2_11:
 # PUT /os-services/{service_id} added in 2.53.
 forced_down_2_53_in:
   description: |
-    Whether or not this service was forced down manually by an
-    administrator. This value is useful to know that some 3rd party has
-    verified the service should be marked down.
+    ``forced_down`` is a manual override to tell nova that the service in
+    question has been fenced manually by the operations team (either hard
+    powered off, or network unplugged). That signals that it is safe to proceed
+    with ``evacuate`` or other operations that nova has safety checks to
+    prevent for hosts that are up.
+
+    .. warning::
+
+       Setting a service forced down without completely fencing it will likely
+       result in the corruption of VMs on that host.
+
   in: body
   required: false
   type: boolean
@@ -3106,8 +3115,9 @@ forced_down_2_53_in:
 forced_down_2_53_out:
   description: |
     Whether or not this service was forced down manually by an
-    administrator. This value is useful to know that some 3rd party has
-    verified the service should be marked down.
+    administrator after the service was fenced. This value is useful
+    to know that some 3rd party has verified the service should be
+    marked down.
   in: body
   required: true
   type: boolean