From f4238fe5785a95c5e99597a8c69c82c26fd5cf00 Mon Sep 17 00:00:00 2001 From: Mark90 Date: Fri, 3 Jul 2026 14:33:37 +0200 Subject: [PATCH] Fix typos, casing, spacing and reference problems found through tool-assisted review --- .../example-orchestrator/bootstrap.md | 8 +++--- .../example-orchestrator/domain-models.md | 2 +- .../example-orchestrator/execute-workflows.md | 16 ++++++------ .../example-orchestrator/generator.md | 14 +++++----- .../example-orchestrator/node-create.md | 4 ++- .../example-orchestrator/node-modify.md | 4 ++- .../example-orchestrator/node-terminate.md | 4 ++- .../example-orchestrator/node-validate.md | 4 ++- .../example-orchestrator/overview.md | 26 ++++++++++--------- .../example-orchestrator/scenario.md | 10 +++---- .../example-orchestrator/workflow-basics.md | 2 +- 11 files changed, 52 insertions(+), 42 deletions(-) diff --git a/docs/workshops/example-orchestrator/bootstrap.md b/docs/workshops/example-orchestrator/bootstrap.md index 3a0fe3e9..cda56506 100644 --- a/docs/workshops/example-orchestrator/bootstrap.md +++ b/docs/workshops/example-orchestrator/bootstrap.md @@ -94,7 +94,7 @@ maintainers' container — there is no native `containerlab` binary on Apple Sil ## Step 1 - Cloning the repo -The fist step is to clone the Example orchestrator repository using: +The first step is to clone the Example orchestrator repository using: ``` git clone https://github.com/workfloworchestrator/example-orchestrator.git @@ -102,7 +102,7 @@ git clone https://github.com/workfloworchestrator/example-orchestrator.git At this point, you have a functional environment to start play with. This includes: * The orchestrator (core and GUI) -* Netbox (the entire stack including database, workers, etc...) +* NetBox (the entire stack including database, workers, etc...) * LSO (to run ansible playbooks) * An example containerlab topology based on Nokia SRlinux. * Some examples of Ansible playbooks @@ -185,8 +185,8 @@ You should be able to view the applications here: 1. Orchestrator ui: [Frontend: http://localhost:3000](http://localhost:3000) 2. Orchestrator backend: [REST api: http://localhost:8080/api/redoc](http://localhost:8080/api/redoc) and - [Graphql API: http://localbost:8080/api/graphql](http://localhost:8080/api/graphql) -3. Netbox (admin|admin): [Netbox: http://localhost:8000](http://localhost:8000) + [Graphql API: http://localhost:8080/api/graphql](http://localhost:8080/api/graphql) +3. NetBox (admin|admin): [NetBox: http://localhost:8000](http://localhost:8000) !!! note Take your time to familiarise with the applications and make sure they are working correctly. diff --git a/docs/workshops/example-orchestrator/domain-models.md b/docs/workshops/example-orchestrator/domain-models.md index 48e66506..c19d5da7 100644 --- a/docs/workshops/example-orchestrator/domain-models.md +++ b/docs/workshops/example-orchestrator/domain-models.md @@ -6,5 +6,5 @@ First read the [Architecture; TL;DR](../../orchestrator-core/architecture/tldr.m concepts that will be covered. ## Products -{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/master/README.md', +{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/main/README.md', '## Products') }} diff --git a/docs/workshops/example-orchestrator/execute-workflows.md b/docs/workshops/example-orchestrator/execute-workflows.md index 4f451d4d..95f9e6e4 100644 --- a/docs/workshops/example-orchestrator/execute-workflows.md +++ b/docs/workshops/example-orchestrator/execute-workflows.md @@ -4,15 +4,15 @@ using the Workflow Orchestrator. ### Putting initial data in place -The first thing we will do is populate Netbox with some initial data such as Manufacturers and Device types, +The first thing we will do is populate NetBox with some initial data such as Manufacturers and Device types, as well as networks allocated for Loopback and Core-links addressing. -To do this, navigate to the **Tasks** page, click **New task** and then select **Netbox Bootstrap**. +To do this, navigate to the **Tasks** page, click **New task** and then select **NetBox Bootstrap**. An empty form will show where you can click **Start task**. -Once the workflow has successfully run, we can login into netbox (admin/admin) and check the situation: within the **Devices** menu you can see that the **Device Types** and **Manufacturers** now contain some definitions. +Once the workflow has successfully run, we can log in to NetBox (admin/admin) and check the situation: within the **Devices** menu you can see that the **Device Types** and **Manufacturers** now contain some definitions. -In the **IPAM >> Prefixes** menu we are going to reserve the first address of the loopback networks since certain network devices dont like "network addresses" to be used as loopback addresses. +In the **IPAM >> Prefixes** menu we are going to reserve the first address of the loopback networks since certain network devices don't like "network addresses" to be used as loopback addresses. * From the IPv4 prefix `10.0.127.0/24` we allocate the address `10.0.127.0/32` with status `Reserved` and description `RESERVED` * From the IPv6 prefix `fc00:0:0:127::/64` we allocate the address `fc00:0:0:127::/128` with status `Reserved` and description `RESERVED` @@ -22,7 +22,7 @@ In the **IPAM >> Prefixes** menu we are going to reserve the first address of th Now we should be able to deploy our routers using the `create node` workflow in the Orchestrator. To do this, click the **New subscription** button and select **node Nokia**. This is going to create a new subscription of the "node Nokia" product. -We will have to fill an initial form. +We will have to fill in an initial form. * **Customer**: SURF * **Node type**: Select the first option @@ -31,9 +31,9 @@ We will have to fill an initial form. * **Node status**: active * **Node name**: Same as the node name in containerlab: `clab-orch-demo-ams-pe`, `clab-orch-demo-lon-pe` and `clab-orch-demo-par-p` -Click **Next** and, review the summary page, and click **Next** again to start the workflow. +Click **Next**, review the summary page, and click **Next** again to start the workflow. -Once the workflow has successfully ran we can login into the node and take a look at the config: +Once the workflow has successfully run, we can log in to the node and take a look at the config: ``` ssh clab-orch-demo-ams-pe -l admin @@ -49,7 +49,7 @@ We can practice this deploying all the 3 nodes in the topology. Once we have 2 nodes configured, we should be able to deploy a core link between them using the "create core link 10G" workflow. -You can login into the router and check the status of ISIS using: +You can log in to the router and check the status of ISIS using: ``` show network-instance default protocols isis adjacency diff --git a/docs/workshops/example-orchestrator/generator.md b/docs/workshops/example-orchestrator/generator.md index c48509da..602a61e3 100644 --- a/docs/workshops/example-orchestrator/generator.md +++ b/docs/workshops/example-orchestrator/generator.md @@ -64,7 +64,7 @@ reuse as many of the product blocks already existing in the orchestrator as poss values: - protected - unprotected - description: "Level of network redundancany" + description: "Level of network redundancy" product_blocks: - name: l2_p2p_virtual_circuit type: L2P2PVirtualCircuit @@ -79,7 +79,7 @@ reuse as many of the product blocks already existing in the orchestrator as poss max_items: 2 required: provisioning - name: speed - description: "speed of the L2VPN im Mbit/s" + description: "speed of the L2VPN in Mbit/s" type: int required: provisioning modifiable: @@ -133,7 +133,7 @@ domain model, fixed inputs and imported the correct product blocks to be used in #### Workflows Now generate the workflows. This command will always create 4 sets of workflows `create`, `modify`, `terminate` and -`validate`. These can be implemeted as the users sees fit. +`validate`. These can be implemented as the user sees fit. !!! warning There is a bug in `generate workflows` which makes it overwrite the contents of workflows/shared.py. @@ -157,7 +157,7 @@ python main.py generate migration -cf templates/l2-p2p.yaml python main.py db upgrade heads ``` -### Step 4 - Profit +### Step 4 - Profit If this has been executed without errors, you should be able to create a new subscription for the l2-p2p product by running the create workflow through the UI. All it does is create the domain model and fill it in with some rudimentary values from the input form, but it's a starting point. Users can now go into the workflow source code @@ -170,12 +170,12 @@ in the orchestrator UI to see what has been configured. ### Step 5 - Bonus Implement a new step in the create workflow that manipulates the subscription in a certain way. An example could be -to change the subscription description. Or any other value you can think of that exists in the subscription +to change the subscription description, or any other value you can think of that exists in the subscription. -??? example - "Answer" +??? example "Answer" ```python @step("Update Subscription Description") def update(subscription: L2p2pProvisioning) -> State: - subscription.descrtiption = "My Awesome L2P2P" + subscription.description = "My Awesome L2P2P" return state | {"subscription": subscription} ``` diff --git a/docs/workshops/example-orchestrator/node-create.md b/docs/workshops/example-orchestrator/node-create.md index 5b8f50ab..21edbf76 100644 --- a/docs/workshops/example-orchestrator/node-create.md +++ b/docs/workshops/example-orchestrator/node-create.md @@ -1,2 +1,4 @@ -{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/master/README.md', +# Create Workflow + +{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/main/README.md', '### Create workflow') }} diff --git a/docs/workshops/example-orchestrator/node-modify.md b/docs/workshops/example-orchestrator/node-modify.md index bd95cb2c..fb312b89 100644 --- a/docs/workshops/example-orchestrator/node-modify.md +++ b/docs/workshops/example-orchestrator/node-modify.md @@ -1,2 +1,4 @@ -{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/master/README.md', +# Modify Workflow + +{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/main/README.md', '### Modify workflow') }} diff --git a/docs/workshops/example-orchestrator/node-terminate.md b/docs/workshops/example-orchestrator/node-terminate.md index a491eff3..d44daa07 100644 --- a/docs/workshops/example-orchestrator/node-terminate.md +++ b/docs/workshops/example-orchestrator/node-terminate.md @@ -1,2 +1,4 @@ -{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/master/README.md', +# Terminate Workflow + +{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/main/README.md', '### Terminate workflow') }} diff --git a/docs/workshops/example-orchestrator/node-validate.md b/docs/workshops/example-orchestrator/node-validate.md index ebbfb76a..cfb5bbd9 100644 --- a/docs/workshops/example-orchestrator/node-validate.md +++ b/docs/workshops/example-orchestrator/node-validate.md @@ -1,2 +1,4 @@ -{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/master/README.md', +# Validate Workflow + +{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/main/README.md', '### Validate workflow') }} diff --git a/docs/workshops/example-orchestrator/overview.md b/docs/workshops/example-orchestrator/overview.md index 91eeb1cb..44d4e2b4 100644 --- a/docs/workshops/example-orchestrator/overview.md +++ b/docs/workshops/example-orchestrator/overview.md @@ -2,7 +2,7 @@ ## Intended audience -This workshop is intended for those who are interested in using the Workflow Orchestrator as network orchestrator, but +This workshop is intended for those who are interested in using the Workflow Orchestrator as a network orchestrator, but is also accessible to those who are new to the Workflow Orchestrator and would like to use it as a generic orchestrator. The main goal of this workshop is to introduce you to how to write orchestrator workflows that talk to external systems, as well as teaching you how to relate products to other products, using the dependency model of the @@ -22,10 +22,12 @@ Workflow Orchestrator. Through a simple network node and network circuit scenario, a set of products is created showing how domain models are defined. * **Domain models** Explains the benefits of the use of domain models and shows how the hierarchy of products, product blocks, fixed inputs and resource types are used to create product subscriptions for customers. +* **Workflows** + Introduces the workflow concept and how the create, modify, terminate, and validate workflows relate to the product model, using the example orchestrator's node workflows as a reference. * **L2 Point-to-Point product modelling and workflow** For the L2 Point-to-Point product, we will make the CREATE workflow by using the product generator. The use of input forms is explained as part of defining the create workflow. By using this method you should be able to quickly get - up to speed and start coding quickly + up to speed and start coding quickly. ## Workshop folder layout @@ -45,9 +47,9 @@ This workshop uses the following folder layout: ├── templates ├── translations ├── utils -├── workflows -│ └── -└── tasks +└── workflows + ├── + └── tasks ``` ## Workshop software architecture @@ -55,16 +57,16 @@ This workshop uses the following folder layout: The workshop combines a number of opensource software components that can provision a simulated network running in containerlab. The following diagram shows the logical components of the application and how the data flows. In reality there are a number of extra services like Postgres and Redis that store the application data of -the Orchestrator, Netbox and LSO. +the Orchestrator, NetBox and LSO. ### Software used in the workshop -* **The orchestrator**: This includes the UI and python backend that will run all workflows. All data is persisted in a Postgres database. Redis is event broadcasting and synchronisation purposes. -* **[Netbox](https://docs.netbox.dev/en/stable/)**: Netbox is the source of truth for this network topology. It contains all resources that are known - in the topology: Interfaces, Nodes, IP addresses etc. The Orchestrator will configure Netbox but also retrieve resources from it. +* **The orchestrator**: This includes the UI and python backend that will run all workflows. All data is persisted in a Postgres database. Redis is used for event broadcasting and synchronisation purposes. +* **[NetBox](https://docs.netbox.dev/en/stable/)**: NetBox is the source of truth for this network topology. It contains all resources that are known + in the topology: Interfaces, Nodes, IP addresses etc. The Orchestrator will configure NetBox but also retrieve resources from it. * **[LSO](https://github.com/workfloworchestrator/lso)**: The Network Resource Manager (NRM) of this topology. This software is an API abstraction on top of ansible that integrates well with the orchestrator. It is responsible for running ansible jobs to provision the topology. -* **[Container Lab](https://containerlab.dev/)**: This software will manage the (virtual) network topology running the Network Operating System +* **[containerlab](https://containerlab.dev/)**: This software will manage the (virtual) network topology running the Network Operating System of the workshop. Below the network topology is explained. ![Software topology](../images/Software-topology.drawio.png) @@ -74,9 +76,9 @@ the Orchestrator, Netbox and LSO. Once you have installed the example orchestrator with containerlab integration enabled (explained in the next section), we will build the workshop topology that can be used to actually see packets flow. The workflows that you will run in the following steps will do the following: -* Seed Netbox +* Seed NetBox * Provision two PE nodes -* Create an IS-IS cloud to signal MPLS LSP's with backbone links +* Create an IS-IS cloud to signal MPLS LSPs with backbone links * Provision customer Ports that can be used in network services The topology will be as follows: diff --git a/docs/workshops/example-orchestrator/scenario.md b/docs/workshops/example-orchestrator/scenario.md index aa65d28d..1e8d2769 100644 --- a/docs/workshops/example-orchestrator/scenario.md +++ b/docs/workshops/example-orchestrator/scenario.md @@ -3,9 +3,9 @@ During this workshop a set of products will be used together with the needed workflows to manage enrolling network nodes into the Workflow Orchestrator and creating circuits between nodes. The products will be just complex enough to show the basic capabilities of products, product blocks, fixed inputs, -resource types and workflows in the workflow orchestrator. We will cover nesting product blocks and products together. +resource types and workflows in the Workflow Orchestrator. We will cover nesting product blocks and products together. -## Product hiearchy example +## Product hierarchy example In the diagram below you can see how all products and product blocks relate to each other. The example orchestrator has implemented the following example products and corresponding workflows that can be used to build a basic network @@ -62,7 +62,7 @@ flowchart direction LR l2ptp_sap1[SAPBlock] l2ptp_vc[VirtualCircuitBlock] - l2ptp_sap2[SapBlock] + l2ptp_sap2[SAPBlock] l2ptp_sap1 --- l2ptp_vc l2ptp_vc --- l2ptp_sap2 end @@ -95,6 +95,6 @@ flowchart ``` -!!! Hint +!!! hint Take some time to explore the module described above. It shows how the product modelling is done in Python. - Once you are familiar with the code, continue with the workshop + Once you are familiar with the code, continue with the workshop. diff --git a/docs/workshops/example-orchestrator/workflow-basics.md b/docs/workshops/example-orchestrator/workflow-basics.md index cf96412d..ad8a3fab 100644 --- a/docs/workshops/example-orchestrator/workflow-basics.md +++ b/docs/workshops/example-orchestrator/workflow-basics.md @@ -1,3 +1,3 @@ # Workflow Basics -{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/master/README.md', +{{ external_markdown('https://raw.githubusercontent.com/workfloworchestrator/example-orchestrator/main/README.md', '## Workflows - Basics') }}