diff --git a/docs/architecture/at-a-glance.md b/docs/architecture/at-a-glance.md new file mode 100644 index 00000000..cd3dcb8b --- /dev/null +++ b/docs/architecture/at-a-glance.md @@ -0,0 +1,84 @@ +# Workflow Orchestrator At A Glance + +!!! info + This article is for potential adopters considering Workflow Orchestrator (WFO) for their organization. + + Without going into implementation details, this highlights the experience of a user (a network operator) as they set up a core link between two nodes. + This guide also favors high-level terminology over the finer semantics of WFO's database models. + + All screenshots are from the [example-orchestrator][example-orchestrator] project, which you can set up yourself to explore the product further. + + +Workflow Orchestrator is an open-source software framework written in Python. +In organizations using WFO, software teams define **products** using the framework, along with **workflows** that network operators then use to manage each product's lifecycle. + +When an operator subscribes a customer to a product, they run a **create** workflow, which produces a **subscription** to that product. +That subscription can then orchestrated by the other workflows associated with its product. +For example, **validate** workflows ensure WFO's database is kept in sync with any external resources allocated to a subscription, and **terminate** workflows deprovision the subscription along with those external resources. + +# Scenario: Adding a Link + +Suppose that we have nodes in Amsterdam and London, and we want to establish a core link between them. + +On the Subscriptions page, we can see that we already have a subscription for each node, so we create a link via the New Subscription dropdown. +![Create Core Link dropdown](../img/at-a-glance/create_core_link_dropdown.png) + +We're then taken to a form for creating the new core link. +As seen below, the form is multi-part with choices pregenerated for the fields. + +In this case, the choices are generated dynamically from a Netbox inventory, and all of this is easily implemented via backend Python code. No front-end form templates were required. + +![Create Core Link form A](../img/at-a-glance/create_core_link_form_a.png) +![Create Core Link form B](../img/at-a-glance/create_core_link_form_b.png) + +After submitting each part of the form, the Create workflow is started. +A workflow is composed of multiple steps, and the status of each step is visible in the UI as it completes. +Any step that generates data can be expanded in the UI to view its output. +Below, we can see the output of the Assign IPv6 Prefix step. + +![Create Core Link workflow output](../img/at-a-glance/create_core_link_output.png) + +A link in the upper-right corner of the workflow output (above) takes us to the subscription we created (below.) + +On the left, we can see various details about both the Core Link subscription, the ports on either end, and the nodes (also subscriptions) each port resides on. + +On the right, the Actions dropdown lists the workflows available to us for further managing the subscription's lifecycle. + +![Core Link subscription page](../img/at-a-glance/core_link_sub.png) + +The General tab provides more extensive information about the subscription. + +![Core Link subscription page general tab](../img/at-a-glance/core_link_sub_general.png) + +# Additional Actions +Above, we saw the Actions available to manage a Core Link subscription after it was created. + +`Modify core_link`: Users can define modify workflows to update the subscription database and/or an orchestrated external resource. Users define modify workflows for each subscription to facilitate changes mid-lifecycle. + +`Validate core_link`: Users can define validation workflows to verify the data in the WFO database against the external systems it manages. An error in a validation workflow places the corresponding subscription in an Out of Sync state, which flags it for remediation and blocks its workflows. For example, if WFO manages a resource in Netbox and that resource is then edited directly in Netbox, this could be detected with a validation workflow. + +Validation workflows are commonly run overnight using WFO's [scheduling](../../orchestrator-core/guides/tasks/) features. + +`Terminate core_link`: Users can define terminate workflows in order to deprovision a subscription and any resources orchestrated on its behalf. Terminated subscriptions are still accessible for reference. + +Users aren't limited to these workflows. +For example, it can be helpful to create distinct modify workflows for the same product to make unrelated changes. + +# Behind the Scenes + +So what's actually happening behind the scenes when we run these workflows? + +WFO provides none of the facilities for talking to Netbox, NSO, Ansible, etc. +These features are implemented by other packages or by the software team leveraging the framework. + +If you want to see the code for yourself, the above example came from the [example-orchestrator][example-orchestrator] repo. +The Core Link producted is defined by a [Product][example-core-link-product-type] and its constituent [Product Blocks][example-core-link-product-blocks], along with its [workflows][example-core-link-workflows]. + + + + +[nren-wikipedia]: https://en.wikipedia.org/wiki/National_research_and_education_network +[example-orchestrator]: https://github.com/workfloworchestrator/example-orchestrator +[example-core-link-product-type]: https://github.com/workfloworchestrator/example-orchestrator/blob/main/products/product_types/core_link.py +[example-core-link-product-blocks]: https://github.com/workfloworchestrator/example-orchestrator/blob/main/products/product_blocks/core_link.py +[example-core-link-workflows]: https://github.com/workfloworchestrator/example-orchestrator/tree/main/workflows/core_link diff --git a/docs/img/at-a-glance/core_link_sub.png b/docs/img/at-a-glance/core_link_sub.png new file mode 100644 index 00000000..28f7cc9a Binary files /dev/null and b/docs/img/at-a-glance/core_link_sub.png differ diff --git a/docs/img/at-a-glance/core_link_sub_general.png b/docs/img/at-a-glance/core_link_sub_general.png new file mode 100644 index 00000000..1feb2a9e Binary files /dev/null and b/docs/img/at-a-glance/core_link_sub_general.png differ diff --git a/docs/img/at-a-glance/create_core_link_dropdown.png b/docs/img/at-a-glance/create_core_link_dropdown.png new file mode 100644 index 00000000..7fdbbd07 Binary files /dev/null and b/docs/img/at-a-glance/create_core_link_dropdown.png differ diff --git a/docs/img/at-a-glance/create_core_link_form_a.png b/docs/img/at-a-glance/create_core_link_form_a.png new file mode 100644 index 00000000..e46cc8c9 Binary files /dev/null and b/docs/img/at-a-glance/create_core_link_form_a.png differ diff --git a/docs/img/at-a-glance/create_core_link_form_b.png b/docs/img/at-a-glance/create_core_link_form_b.png new file mode 100644 index 00000000..a461d8e5 Binary files /dev/null and b/docs/img/at-a-glance/create_core_link_form_b.png differ diff --git a/docs/img/at-a-glance/create_core_link_output.png b/docs/img/at-a-glance/create_core_link_output.png new file mode 100644 index 00000000..05860ec9 Binary files /dev/null and b/docs/img/at-a-glance/create_core_link_output.png differ diff --git a/mkdocs.yml b/mkdocs.yml index bbaec0b9..548172a2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ nav: - Contact: contact.md - Leadership: leadership.md - Architecture: + - At A Glance: architecture/at-a-glance.md - The Framework: architecture/framework.md - Orchestrator UI: architecture/orchestrator-ui.md - Input Forms: architecture/input-forms.md