api-ref: Body verification for the lock action

This patch adds more explanations for the lock action
in the Compute API reference and the Compute API guide.

Change-Id: Iae4a42351d11d5caade9a1a299b06fed862a7da4
Partial-Bug: #1793034

api-guide/source/server_concepts.rst

@@ -564,13 +564,61 @@ Server actions
 
 -  **Lock**, **Unlock**
 
-   Lock a server so no further actions are allowed to the server. This can
-   be done by either administrator or the server's owner. By default, only owner
-   or administrator can lock the sever, and administrator can overwrite owner's lock.
+   Lock a server so the following actions by non-admin users are not
+   allowed to the server.
+
+   - Delete Server
+   - Change Administrative Password (changePassword Action)
+   - Confirm Resized Server (confirmResize Action)
+   - Force-Delete Server (forceDelete Action)
+   - Pause Server (pause Action)
+   - Reboot Server (reboot Action)
+   - Rebuild Server (rebuild Action)
+   - Rescue Server (rescue Action)
+   - Resize Server (resize Action)
+   - Restore Soft-Deleted Instance (restore Action)
+   - Resume Suspended Server (resume Action)
+   - Revert Resized Server (revertResize Action)
+   - Shelf-Offload (Remove) Server (shelveOffload Action)
+   - Shelve Server (shelve Action)
+   - Start Server (os-start Action)
+   - Stop Server (os-stop Action)
+   - Suspend Server (suspend Action)
+   - Trigger Crash Dump In Server
+   - Unpause Server (unpause Action)
+   - Unrescue Server (unrescue Action)
+   - Unshelve (Restore) Shelved Server (unshelve Action)
+   - Attach a volume to an instance
+   - Update a volume attachment
+   - Detach a volume from an instance
+   - Create Interface
+   - Detach Interface
+   - Create Or Update Metadata Item
+   - Create or Update Metadata Items
+   - Delete Metadata Item
+   - Replace Metadata Items
+   - Add (Associate) Fixed Ip (addFixedIp Action) (DEPRECATED)
+   - Remove (Disassociate) Fixed Ip (removeFixedIp Action) (DEPRECATED)
+
+   ..
+     NOTE(takashin):
+     The following APIs can be performed by administrators only by default.
+     So they are not listed in the above list.
+
+     - Migrate Server (migrate Action)
+     - Live-Migrate Server (os-migrateLive Action)
+     - Force Migration Complete Action (force_complete Action)
+     - Delete (Abort) Migration
+     - Inject Network Information (injectNetworkInfo Action)
+     - Reset Networking On A Server (resetNetwork Action)
+
+   But administrators can perform the actions on the server
+   even though the server is locked. By default, only owner or administrator
+   can lock the sever, and administrator can overwrite owner's lock.
 
    Unlock will unlock a server in locked state so additional
-   operations can be performed on the server. By default, only owner or
-   administrator can unlock the server.
+   operations can be performed on the server by non-admin users.
+   By default, only owner or administrator can unlock the server.
 
 -  **Rescue**, **Unrescue**
 

api-ref/source/servers-actions.inc

@@ -347,9 +347,30 @@ Locks a server.
 
 Specify the ``lock`` action in the request body.
 
+Most actions by non-admin users are not allowed to the server
+after this operation is successful and the server is locked.
+See the "Lock, Unlock" item in `Server actions
+<https://developer.openstack.org/api-guide/compute/server_concepts.html#server-actions>`_
+for the restricted actions.
+But administrators can perform actions on the server
+even though the server is locked.
+
+The `unlock action
+<https://developer.openstack.org/api-ref/compute/#unlock-server-unlock-action>`_
+will unlock a server in locked state so additional actions can
+be performed on the server by non-admin users.
+
+You can know whether a server is locked or not
+by the `List Servers Detailed API
+<https://developer.openstack.org/api-ref/compute/#list-servers-detailed>`_
+or
+the `Show Server Details API
+<https://developer.openstack.org/api-ref/compute/#show-server-details>`_.
+
 Policy defaults enable only users with the administrative role or
 the owner of the server to perform this operation. Cloud providers
 can change these permissions through the ``policy.json`` file.
+Administrators can overwrite owner's lock.
 
 Normal response codes: 202