devref: virtual machine states and transitions

The diagrams were hard to read and update. Replaced them with
simplified diagrams and tables. I used the content as is. I looks
inconsistent to me, but should now be easier to change.

Partially implements: blueprint devref-refresh-liberty

Change-Id: I707e1a6ab69ef44448b66e8be007307b5d73eb06

doc/source/conf.py

@@ -35,6 +35,7 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.graphviz',
               'oslosphinx',
               "ext.support_matrix",
+              'sphinxcontrib.seqdiag',
               ]
 
 todo_include_todos = True

doc/source/vmstates.rst

@@ -1,20 +1,25 @@
 Virtual Machine States and Transitions
 =======================================
 
-Preconditions for commands
+The following diagrams and tables show the required virtual machine (VM)
+states and task states for various commands issued by the user.
+
+Allowed State Transitions
 --------------------------
 
-
-The following diagrams show the required virtual machine (VM) states and
-task states for various commands issued by the user:
-
 .. graphviz::
 
   digraph states {
-    node [fontsize=10 fontname="Monospace"]
+    graph [pad=".35", ranksep="0.65", nodesep="0.55", concentrate=true];
+    node [fontsize=10 fontname="Monospace"];
+    edge [arrowhead="normal", arrowsize="0.8"];
+    label="All states are allowed to transition to DELETED and ERROR.";
+    forcelabels=true;
+    labelloc=bottom;
+    labeljust=left;
+
     /* states */
     building [label="BUILDING"]
-
     active [label="ACTIVE"]
     paused [label="PAUSED"]
     suspended [label="SUSPENDED"]
@@ -22,166 +27,143 @@ task states for various commands issued by the user:
     rescued [label="RESCUED"]
     resized [label="RESIZED"]
     soft_deleted [label="SOFT_DELETED"]
-    deleted [label="DELETED"]
-    error [label="ERROR"]
     shelved [label="SHELVED"]
     shelved_offloaded [label="SHELVED_OFFLOADED"]
-        
+    deleted [label="DELETED", color="red"]
-    /* apis */
+    error [label="ERROR", color="red"]
-    create [shape="rectangle"]
-    create -> active
-    create -> error
-    building -> create
 
-    delete [shape="rectangle"]
+    /* transitions [action] */
-    delete -> deleted
+    building -> active
-    building -> delete
-    paused -> delete
-    suspended -> delete
-    stopped -> delete
-    rescued -> delete
-    soft_deleted -> delete
-    error -> delete
 
-    soft_delete [shape="rectangle"]
+    active -> active [headport=nw, tailport=ne]  // manual layout
-    soft_delete -> soft_deleted
+    active -> soft_deleted [tailport=e]  // prevent arrowhead overlap
-    soft_delete -> error
+    active -> suspended
-    active -> soft_delete
+    active -> paused [tailport=w]  // prevent arrowhead overlap
-    stopped -> soft_delete
+    active -> stopped
+    active -> shelved
+    active -> shelved_offloaded
+    active -> rescued
+    active -> resized
 
-    restore [shape="rectangle"]
+    soft_deleted -> active [headport=e]  // prevent arrowhead overlap
-    restore -> active
-    restore -> error
-    soft_deleted -> restore
 
-    pause [shape="rectangle"]
+    suspended -> active
-    pause -> paused
+    suspended -> shelved
-    pause -> error
+    suspended -> shelved_offloaded
-    active -> pause
 
-    unpause [shape="rectangle"]
+    paused -> active
-    unpause -> active
+    paused -> shelved
-    unpause -> error
+    paused -> shelved_offloaded
-    paused -> unpause
 
-    suspend [shape="rectangle"]
+    stopped -> active
-    suspend -> suspended
+    stopped -> stopped [headport=nw, tailport=ne]  // manual layout
-    suspend -> error
+    stopped -> resized
-    active -> suspend
+    stopped -> rescued
+    stopped -> shelved
+    stopped -> shelved_offloaded
 
-    resume [shape="rectangle"]
+    resized -> active
-    resume -> active
-    resume -> error
-    suspended -> resume
 
-    start [shape="rectangle"]
+    rescued -> active
-    start -> active
-    start -> error
-    stopped -> start
 
-    stop [shape="rectangle"]
+    shelved -> shelved_offloaded
-    stop -> stopped
+    shelved ->  active
-    stop -> error
-    active -> stop
-    error -> stop
 
-    rescue [shape="rectangle"]
+    shelved_offloaded -> active
-    rescue -> rescued
-    rescue -> error
-    active -> rescue
-    stopped -> rescue
-    error -> rescue
-
-    unrescue [shape="rectangle"]
-    unrescue -> active
-    rescued -> unrescue
-
-    resize [shape="rectangle"]
-    resize -> resized
-    resize -> error
-    active -> resize
-    stopped -> resize
-
-    confirm_resize [shape="rectangle"]
-    confirm_resize -> active
-    confirm_resize -> error
-    resized -> confirm_resize
-    confirm_resize [shape="rectangle"]
-
-    revert_resize -> active
-    revert_resize -> error
-    resized -> revert_resize
-
-    snapshot [shape="rectangle"]
-    snapshot -> active
-    snapshot -> stopped
-    snapshot -> error
-    active -> snapshot
-    stopped -> snapshot
-
-    backup [shape="rectangle"]
-    backup -> active
-    backup -> stopped
-    backup -> error
-    active -> backup
-    stopped -> backup
-
-    rebuild [shape="rectangle"]
-    rebuild -> active
-    rebuild -> error
-    active -> rebuild
-    stopped -> rebuild
-
-    set_admin_password [shape="rectangle"]
-    set_admin_password -> active
-    set_admin_password -> error
-    active -> set_admin_password
-
-    reboot [shape="rectangle"]
-    reboot -> active
-    reboot -> error
-    active -> reboot
-    stopped -> reboot
-    paused -> reboot
-    suspended -> reboot
-    error -> reboot
-
-    live_migrate [shape="rectangle"]
-    live_migrate -> active
-    live_migrate -> error
-    active -> live_migrate
-
-    shelve [shape="rectangle"]
-    shelve -> shelved
-    shelve -> shelved_offloaded
-    shelve -> error
-    active -> shelve
-    stopped -> shelve
-    paused -> shelve
-    suspended -> shelve
-
-    shelve_offload [shape="rectangle"]
-    shelve_offload -> shelved_offloaded
-    shelve_offload -> error
-    shelved -> shelve_offload
-
-    unshelve [shape="rectangle"]
-    unshelve -> active
-    unshelve -> error
-    shelved -> unshelve
-    shelved_offloaded -> unshelve
   }
 
-.. image:: ./images/PowerStates1.png
 
-.. image:: ./images/PowerStates2.png
+Requirements for Commands
+-------------------------
+
+==================  ==================  ====================  ================
+Command             Req'd VM States     Req'd Task States     Target State
+==================  ==================  ====================  ================
+pause               Active, Shutoff,    Resize Verify, unset  Paused
+                    Rescued
+unpause             Paused              N/A                   Active
+suspend             Active, Shutoff     N/A                   Suspended
+resume              Suspended           N/A                   Active
+rescue              Active, Shutoff     Resize Verify, unset  Rescued
+unrescue            Rescued             N/A                   Active
+set admin password  Active              N/A                   Active
+rebuild             Active, Shutoff     Resize Verify, unset  Active
+force delete        Soft Deleted        N/A                   Deleted
+restore             Soft Deleted        N/A                   Active
+soft delete         Active, Shutoff,    N/A                   Soft Deleted
+                    Error
+delete              Active, Shutoff,    N/A                   Deleted
+                    Building, Rescued,
+                    Error
+backup              Active, Shutoff     N/A                   Active, Shutoff
+snapshot            Active, Shutoff     N/A                   Active, Shutoff
+start               Shutoff, Stopped    N/A                   Active
+stop                Active, Shutoff,    Resize Verify, unset  Stopped
+                    Rescued
+reboot              Active, Shutoff,    Resize Verify, unset  Active
+                    Rescued
+resize              Active, Shutoff     Resize Verify, unset  Resized
+revert resize       Active, Shutoff     Resize Verify, unset  Active
+confirm resize      Active, Shutoff     Resize Verify, unset  Active
+==================  ==================  ====================  ================
+
+VM states and Possible Commands
+-------------------------------
+
+============  =================================================================
+VM State      Commands
+============  =================================================================
+Paused        unpause
+Suspended     resume
+Active        set admin password, suspend, pause, rescue, rebuild, soft delete,
+              delete, backup, snapshot, stop, reboot, resize, revert resize,
+              confirm resize
+Shutoff       suspend, pause, rescue, rebuild, soft delete, delete, backup,
+              start, snapshot, stop, reboot, resize, revert resize,
+              confirm resize
+Rescued       unrescue, pause
+Stopped       rescue, delete, start
+Soft Deleted  force delete, restore
+Error         soft delete, delete
+Building      delete
+Rescued       delete, stop, reboot
+============  =================================================================
 
 
-Create instance states
+Create Instance States
 ----------------------
 
 The following diagram shows the sequence of VM states, task states, and
 power states when a new VM instance is created.
 
 
-.. image:: ./images/run_instance_walkthrough.png
+.. seqdiag::
+
+    seqdiag {
+      edge_length = 250;
+      span_height = 40;
+      node_width=200;
+      default_note_color = lightblue;
+
+      // Use note (put note on rightside)
+      api [label="Compute.api"];
+      manager [label="Compute.manager"];
+      api -> manager [label = "create_db_entry_for_new_instance",
+                      note = "VM: Building
+                             Task: Scheduling
+                             Power: No State"];
+      manager -> manager [label="_start_building",
+                          note ="VM: Building
+                                Task: None"];
+      manager -> manager [label="_allocate_network",
+                          note ="VM: Building
+                                Task: Networking"];
+      manager -> manager [label="_prep_block_device",
+                          note ="VM: Building
+                                Task: Block_Device_Mapping"];
+      manager -> manager [label="_spawn",
+                          note ="VM: Building
+                                Task: Spawning"];
+      api <-- manager [note ="VM: Active
+                             Task: None"];
+    }

test-requirements.txt

@@ -16,6 +16,7 @@ python-ironicclient>=0.6.0
 python-subunit>=0.0.18
 requests-mock>=0.6.0 # Apache-2.0
 sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
+sphinxcontrib-seqdiag
 oslosphinx>=2.5.0 # Apache-2.0
 oslotest>=1.5.1 # Apache-2.0
 testrepository>=0.0.18