From 428f0367b7acd1624ac42ec6dfa649d3c535ee40 Mon Sep 17 00:00:00 2001
From: Shuichiro MAKIGAKI <shuichiro.makigaki@gmail.com>
Date: Fri, 26 Jun 2015 18:28:19 +0900
Subject: [PATCH] Add sequence diagrams for pxe_ipmi driver

Add sequence diagrams generated by sphinxcontrib-seqdiag
along with the raw text that generated then, so that it can be
updated easily later.

The diagrams were created originally by Devananda van der Veen,
and used in OpenStack Summit YVR.

Ref)
* https://www.openstack.org/summit/vancouver-2015/summit-videos
/presentation/isn-and-039t-it-ironic-the-bare-metal-cloud
* http://devananda.github.io/talks/isnt-it-ironic.html

Change-Id: I47ff02c6cb4764c1740d0924668714ed205b3d9b
---
 doc/source/conf.py               |  5 ++
 doc/source/deploy/user-guide.rst | 91 ++++++++++++++++++++++++++++++++
 test-requirements.txt            |  1 +
 3 files changed, 97 insertions(+)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1209548e56..c823054948 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -9,6 +9,7 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.viewcode',
               'sphinxcontrib.httpdomain',
               'sphinxcontrib.pecanwsme.rest',
+              'sphinxcontrib.seqdiag',
               'wsmeext.sphinxext',
               'oslosphinx',
               ]
@@ -80,3 +81,7 @@ latex_documents = [
         'manual'
     ),
 ]
+
+# -- Options for seqdiag ------------------------------------------------------
+
+seqdiag_html_image_format = "SVG"
diff --git a/doc/source/deploy/user-guide.rst b/doc/source/deploy/user-guide.rst
index 89d0fd2725..0681ef54f7 100644
--- a/doc/source/deploy/user-guide.rst
+++ b/doc/source/deploy/user-guide.rst
@@ -235,3 +235,94 @@ Deploy Process
 
 #. The bare metal node status is updated and the node instance is made
    available.
+
+Example 1: PXE Deploy Process
+--------------------------------
+
+.. seqdiag::
+   :scale: 80
+   :alt: pxe_ipmi
+
+   diagram {
+      Nova; API; Conductor; Neutron; "TFTP/HTTPd"; Node;
+      activation = none;
+      span_height = 1;
+      edge_length = 250;
+      default_note_color = white;
+      default_fontsize = 14;
+
+      Nova -> API [label = "Set instance_info", note = "image_source\n,root_gb,etc."];
+      Nova -> API [label = "Set provision_state"];
+      API -> Conductor [label = "do_node_deploy()"];
+      Conductor -> Conductor [label = "Cache images"];
+      Conductor -> Conductor [label = "Build TFTP config"];
+      Conductor -> Neutron [label = "Update DHCPBOOT"];
+      Conductor -> Node [label = "IPMI power-on"];
+      Node -> Neutron [label = "DHCP request"];
+      Neutron -> Node [label = "next-server = Conductor"];
+      Node -> Conductor [label = "Attempts to tftpboot from Conductor"];
+      "TFTP/HTTPd" -> Node [label = "Send deploy kernel, ramdisk\nand config"];
+      Node -> Node [label = "Runs deploy\nramdisk"];
+      Node -> Node [label = "Exposes disks\nvia iSCSI"];
+      Node -> API [label = "POST /vendor_passthru?method=pass_deploy_info"];
+      API -> Conductor [label = "Continue deploy"];
+      Conductor -> Node [label = "iSCSI attach"];
+      Conductor -> Node [label = "Copies user image"];
+      Conductor -> Node [label = "iSCSI detach"];
+      Conductor -> Node [label = "Sends 'DONE' message"];
+      Conductor -> Conductor [label = "Mark node as\nACTIVE"];
+      Node -> Node [label = "Terminates iSCSI endpoint"];
+      Node -> Node [label = "Reboots into\nuser instance"];
+   }
+
+(From a `talk`_  and `slides`_)
+
+Example 2: Agent Deploy Process
+---------------------------------
+
+.. seqdiag::
+   :scale: 80
+   :alt: pxe_ipmi_agent
+
+   diagram {
+      Nova; API; Conductor; Neutron; "TFTP/HTTPd"; Node;
+      activation = none;
+      edge_length = 250;
+      span_height = 1;
+      default_note_color = white;
+      default_fontsize = 14;
+
+      Nova -> API [label = "Set instance_info", note = "image_source\n,root_gb,etc."];
+      Nova -> API [label = "Set provision_state"];
+      API -> Conductor [label = "do_node_deploy()"];
+      Conductor -> Conductor [label = "Cache images"];
+      Conductor -> Conductor [label = "Update pxe,\ntftp configs"];
+      Conductor -> Neutron [label = "Update DHCPBOOT"];
+      Conductor -> Node [label = "power on"];
+      Node -> Neutron [label = "DHCP request"];
+      Neutron -> Node [label = "next-server = Conductor"];
+      Node -> Conductor [label = "Attempts tftpboot"];
+      "TFTP/HTTPd" -> Node [label = "Send deploy kernel, ramdisk and config"];
+      Node -> Node [label = "Runs agent\nramdisk"];
+      Node -> API [label = "lookup()"];
+      API -> Conductor [label = "..."];
+      Conductor -> Node [label = "Pass UUID"];
+      Node -> API [label = "Heartbeat (UUID)"];
+      API -> Conductor [label = "Heartbeat"];
+      Conductor -> Node [label = "Continue deploy: Pass image, disk info"];
+      === Node downloads image, writes to disk ===
+      Node -> API [label = "Heartbeat periodically"];
+      API -> Conductor [label = "..."];
+      Conductor -> Node [label = "Is deploy done yet?"];
+      Node -> Conductor [label = "Still working..."];
+      === When deploy is done ===
+      Conductor -> Neutron [label = "Clear DHCPBOOT"];
+      Conductor -> Node [label = "Set bootdev HDD"];
+      Conductor -> Node [label = "Reboot"];
+      Node -> Node [label = "Reboots into\nuser instance"];
+   }
+
+(From a `talk`_  and `slides`_)
+
+.. _talk: https://www.openstack.org/summit/vancouver-2015/summit-videos/presentation/isn-and-039t-it-ironic-the-bare-metal-cloud
+.. _slides: http://devananda.github.io/talks/isnt-it-ironic.html
diff --git a/test-requirements.txt b/test-requirements.txt
index 53e0a9191a..26c0c74ea6 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -18,5 +18,6 @@ testtools>=1.4.0
 # Doc requirements
 sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
 sphinxcontrib-pecanwsme>=0.8
+sphinxcontrib-seqdiag
 oslosphinx>=2.5.0 # Apache-2.0