Merge "Add diagram to major upgrade developer docs"

doc/source/install/developer/upgrades/major_upgrade.plantuml

@@ -0,0 +1,188 @@
+' The png image can be generated by running:
+'
+'     plantuml major_upgrade.plantuml
+
+@startuml
+
+actor User
+participant Mistral
+participant Heat
+participant Ansible
+participant Nodes
+' in newer versions of plantuml we should use: collections Nodes
+
+
+' === UPGRADE PREPARE ===
+
+User -> Mistral : openstack overcloud\nupgrade prepare
+activate Mistral
+
+Mistral -> Mistral : plan update
+
+Mistral -> Heat : stack update
+activate Heat
+
+Heat --> Mistral
+deactivate Heat
+
+Mistral --> User
+deactivate Mistral
+
+
+' === UPGRADE RUN ===
+
+User -> Mistral : openstack overcloud\nupgrade run
+activate Mistral
+note right of Heat
+    * Operates on all selected nodes in parallel.
+    * Note the separate ansible-playbook invocations:
+       facts aren't carried over between playbooks.
+end note
+
+Mistral -> Heat : query stack outputs
+activate Heat
+
+Heat --> Mistral : stack outputs
+deactivate Heat
+
+Mistral -> Mistral : generate playbooks
+
+Mistral -> Ansible : upgrade_steps_playbook.yaml
+activate Ansible
+
+Ansible -> Nodes : upgrade_tasks all steps
+activate Nodes
+
+Nodes --> Ansible
+deactivate Nodes
+
+Ansible --> Mistral
+deactivate Ansible
+
+Mistral -> Ansible : deploy_steps_playbook.yaml
+activate Ansible
+
+Ansible -> Nodes : host_prep_tasks
+activate Nodes
+
+Nodes --> Ansible
+deactivate Nodes
+
+Ansible -> Nodes : deploy_tasks all steps
+activate Nodes
+
+Nodes --> Ansible
+deactivate Nodes
+
+Ansible --> Mistral
+deactivate Ansible
+
+Mistral -> Ansible : post_upgrade_steps_playbook.yaml
+activate Ansible
+
+Ansible -> Nodes : post_upgrade_tasks all steps
+activate Nodes
+
+Nodes --> Ansible
+deactivate Nodes
+
+Ansible --> Mistral
+deactivate Ansible
+
+Mistral --> User :
+deactivate Mistral
+
+
+' === EXTERNAL UPGRADE RUN ===
+
+User -> Mistral : openstack overcloud\nexternal-upgrade run
+activate Mistral
+note right of Heat
+    * Executes tasks on undercloud, but can affect
+       overcloud via delegation or nested Ansible process.
+    * Single play: facts are carried over between
+       upgrade and deploy tasks.
+    * Often limited via `--tags` to perform a particular
+       upgrade task or an upgrade of a particular service.
+    * Can be executed before `upgrade run` for some tasks.
+end note
+
+Mistral -> Heat : query stack outputs
+activate Heat
+
+Heat --> Mistral : stack outputs
+deactivate Heat
+
+Mistral -> Mistral : generate playbooks
+
+Mistral -> Ansible : external_upgrade_steps_playbook.yaml
+activate Ansible
+
+Ansible -> Nodes : external_upgrade_tasks all steps
+activate Nodes
+
+Nodes --> Ansible
+deactivate Nodes
+
+Ansible -> Nodes : external_deploy_tasks all steps
+activate Nodes
+
+Nodes --> Ansible
+deactivate Nodes
+
+Ansible --> Mistral
+deactivate Ansible
+
+Mistral --> User :
+deactivate Mistral
+
+
+' === UPGRADE CONVERGE ===
+
+User -> Mistral : openstack overcloud\nupgrade converge
+activate Mistral
+note right of Heat
+    * Essentially the same as `overcloud deploy`,
+       asserts that the state of overcloud matches
+       the latest templates.
+end note
+
+Mistral -> Mistral : plan update
+
+Mistral -> Heat : stack update
+activate Heat
+
+Heat --> Mistral
+deactivate Heat
+
+Mistral -> Heat : query stack outputs
+activate Heat
+
+Heat --> Mistral : stack outputs
+deactivate Heat
+
+Mistral -> Mistral : generate playbooks
+
+Mistral -> Ansible : deploy_steps_playbook.yaml
+activate Ansible
+
+Ansible -> Nodes : host_prep_tasks
+activate Nodes
+
+Nodes --> Ansible
+deactivate Nodes
+
+Ansible -> Nodes : deploy_tasks and external_deploy_tasks\nall steps (interleaved)
+activate Nodes
+
+Nodes --> Ansible
+deactivate Nodes
+
+Ansible --> Mistral
+deactivate Ansible
+
+Mistral --> User :
+deactivate Mistral
+
+
+@enduml

doc/source/install/developer/upgrades/major_upgrade.rst

@@ -13,7 +13,6 @@ and 'converge' command at the end of the upgrade). The
 Queens_upgrade_spec_ may be of interest in describing the design of
 the workflow.
 
-
 CLI code is in python-tripleoclient_, mistral workflows and actions in
 tripleo-common_, and upgrade tasks in tripleo-heat-templates_. The
 following sections dive into the details top-down per individual CLI
@@ -24,6 +23,14 @@ commands which are used to deliver the major upgrade:
 * `openstack overcloud external-upgrade run $ARGS`_
 * `openstack overcloud upgrade converge $ARGS`_
 
+You might also find it helpful to consult this high-level diagram as
+you read the following sections:
+
+.. image:: major_upgrade.png
+   :scale: 20 %
+   :alt: Major upgrade workflow diagram
+   :target: ../../../_images/major_upgrade.png
+
 .. _queens_upgrade_spec: https://github.com/openstack/tripleo-specs/blob/master/specs/queens/tripleo_ansible_upgrades_workflow.rst
 .. _operator_docs: https://docs.openstack.org/tripleo-docs/latest/install/post_deployment/upgrade.html
 .. _python-tripleoclient: https://github.com/openstack/python-tripleoclient/blob/master/tripleoclient/v1/overcloud_upgrade.py