From 63c4cb0250ffb32a1f4887675a3d18bd9a4a2f2d Mon Sep 17 00:00:00 2001 From: Mark90 Date: Tue, 7 Jul 2026 15:43:31 +0200 Subject: [PATCH 1/6] Include l2p2p docs inline --- docs/workshops/example-orchestrator/create-your-own.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/workshops/example-orchestrator/create-your-own.md b/docs/workshops/example-orchestrator/create-your-own.md index 63bbb404..e1e1a5a0 100644 --- a/docs/workshops/example-orchestrator/create-your-own.md +++ b/docs/workshops/example-orchestrator/create-your-own.md @@ -4,5 +4,10 @@ To cap off this workshop we will create a new product and workflows by using the Orchestrator provides the user. In this scenario you will create a product that is very similar to the provided L2VPN product, but constrained to two interfaces. In other words a L2 Point-to-Point circuit. -A description of what this L2 product could look like can be found -[in this section of the documentation](../../../orchestrator-core/architecture/product-modeling/l2-point-to-point/). +A description of what this L2 product could look like is included below (see also +[this section of the documentation](../../orchestrator-core/architecture/product_modelling/l2_point_to_point.md)). + +{% + include-markdown "../../../orchestrator-core/docs/architecture/product_modelling/l2_point_to_point.md" + heading-offset=1 +%} From 8cbdfadfa1c2db5c56892a596f03f46140f4fa0a Mon Sep 17 00:00:00 2001 From: Mark90 Date: Tue, 7 Jul 2026 15:44:52 +0200 Subject: [PATCH 2/6] Update scenario docs product names/block --- docs/workshops/example-orchestrator/scenario.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/workshops/example-orchestrator/scenario.md b/docs/workshops/example-orchestrator/scenario.md index 1e8d2769..cd9df701 100644 --- a/docs/workshops/example-orchestrator/scenario.md +++ b/docs/workshops/example-orchestrator/scenario.md @@ -58,10 +58,10 @@ flowchart node1 --- port1 node2 --- port2 port3 --- node3 - subgraph sg_l2ptp[L2PointToPoint subscription] + subgraph sg_l2p2p[L2p2p subscription] direction LR l2ptp_sap1[SAPBlock] - l2ptp_vc[VirtualCircuitBlock] + l2ptp_vc[L2p2pVirtualCircuitBlock] l2ptp_sap2[SAPBlock] l2ptp_sap1 --- l2ptp_vc l2ptp_vc --- l2ptp_sap2 @@ -89,7 +89,7 @@ flowchart style sg_port2 rx:20,ry:20,fill:#ffe699 style sg_port3 rx:20,ry:20,fill:#c5e0b4 style sg_l2vpn rx:20,ry:20,fill:#ffe699 - style sg_l2ptp rx:20,ry:20,fill:#c5e0b4 + style sg_l2p2p rx:20,ry:20,fill:#c5e0b4 classDef default rx:10,ry:10,fill:#ff9300,stroke:#333,stroke-width:1px ``` From 7313610599ec3a3dd6a6d589d339afb932861f25 Mon Sep 17 00:00:00 2001 From: Mark90 Date: Tue, 7 Jul 2026 15:52:55 +0200 Subject: [PATCH 3/6] Embed l2p2p markdown --- docs/workshops/example-orchestrator/create-your-own.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/workshops/example-orchestrator/create-your-own.md b/docs/workshops/example-orchestrator/create-your-own.md index e1e1a5a0..15e8b0fd 100644 --- a/docs/workshops/example-orchestrator/create-your-own.md +++ b/docs/workshops/example-orchestrator/create-your-own.md @@ -5,9 +5,10 @@ Orchestrator provides the user. In this scenario you will create a product that L2VPN product, but constrained to two interfaces. In other words a L2 Point-to-Point circuit. A description of what this L2 product could look like is included below (see also -[this section of the documentation](../../orchestrator-core/architecture/product_modelling/l2_point_to_point.md)). +[this section of the documentation](../../../orchestrator-core/architecture/product-modeling/l2-point-to-point/)). + {% - include-markdown "../../../orchestrator-core/docs/architecture/product_modelling/l2_point_to_point.md" + include-markdown "../../../orchestrator-core/docs/architecture/product-modeling/l2-point-to-point.md" heading-offset=1 %} From ee84bcc2063b89755e5a3ff9201b892e2a2c6b3a Mon Sep 17 00:00:00 2001 From: Mark90 Date: Tue, 7 Jul 2026 22:00:29 +0200 Subject: [PATCH 4/6] Update generator workshop --- .../example-orchestrator/generator.md | 85 +++++++++++-------- 1 file changed, 48 insertions(+), 37 deletions(-) diff --git a/docs/workshops/example-orchestrator/generator.md b/docs/workshops/example-orchestrator/generator.md index b6f04acf..257fc3a8 100644 --- a/docs/workshops/example-orchestrator/generator.md +++ b/docs/workshops/example-orchestrator/generator.md @@ -19,32 +19,30 @@ total 32 ``` This directory houses all the configuration of the initial products that the example orchestrator provides. It is a -starting point for developing new products. In this workshop we will create a new file and generate the -L2-Point-to-Point model and workflows by configuring it with this yaml file. +starting point for developing new products. -### Step 2 - Configure the YAML - -Create a new file in the template directory called `l2-p2p.yaml` +Create a new file in the template directory called `l2_p2p.yaml`: ```shell -touch templates/l2-p2p.yaml +touch templates/l2_p2p.yaml ``` +In this workshop we will generate the L2-Point-to-Point model and workflows by configuring it with this yaml file. + +### Step 2 - Configure the YAML + This file will contain the Initial product type configuration. Please create a yaml configuration reflecting the product model as described on the [previous page](create-your-own.md). The goal is to configure the generator to reuse as many of the product blocks already existing in the orchestrator as possible. -!!! tip "Inspiration" - Take a look at the `l2vpn.yaml` model for inspiration. As you can see this file has been configured in a certain - way to reflect the configuration of the product. For more in depth documentation take a look at the [reference - doc](../../orchestrator-core/reference-docs/cli.md#generate). +Take a look at the [`l2vpn.yaml`](https://github.com/workfloworchestrator/example-orchestrator/blob/main/templates/l2vpn.yaml) model for inspiration. +As you can see, this file has been configured in a certain way to reflect the configuration of the product. +For more in depth documentation about `generate` take a look at the [reference +doc](../../orchestrator-core/reference-docs/cli.md#generate). -!!! danger "What can I do when I encounter errors?" - If you get stuck just remove all generated files, edit the yaml and try again. - -??? example "Answer - l2-p2p.yaml" +??? example "Answer - l2_p2p.yaml" When creating the YAML you should notice that you do not have to create the **SAP** product blocks again. You just - have reference the **SAPS** in the **Virtual Circuit** configuration. In this way you start reusing existing + have reference the **SAP** in the **Virtual Circuit** configuration. In this way you start reusing existing building blocks that already exist in the orchestrator. We cannot reuse the existing Virtual Circuit with the generator due to the different limits on the amount of SAPS that can be connected to the Virtual Circuit of the L2 P2P product. @@ -53,7 +51,7 @@ reuse as many of the product blocks already existing in the orchestrator as poss config: summary_forms: true name: l2_p2p - type: L2P2P + type: L2p2p tag: L2P2P description: "L2 Point-to-Point" fixed_inputs: @@ -66,7 +64,7 @@ reuse as many of the product blocks already existing in the orchestrator as poss description: "Level of network redundancy" product_blocks: - name: l2_p2p_virtual_circuit - type: L2P2PVirtualCircuit + type: L2p2pVirtualCircuit tag: VC description: "virtual circuit product block" fields: @@ -106,12 +104,15 @@ docker compose exec -it orchestrator bash source .venv/bin/activate ``` +!!! danger "What can I do when I encounter errors?" + If you want to start over, use `git restore .` and `git clean -id` from your example-orchestrator directory to undo changes. + #### Product Blocks Run the command to generate the domain models product blocks: ```shell -python main.py generate product-blocks -cf templates/l2-p2p.yaml --no-dryrun +python main.py generate product-blocks -cf templates/l2_p2p.yaml --no-dryrun ``` The `--no-dryrun` option will immediately write the files to the `products/product_blocks` folder and create: @@ -123,7 +124,7 @@ product and defines the strict hierarchy of virtual circuit and saps. Now create the product. ```shell -python main.py generate product -cf templates/l2-p2p.yaml --no-dryrun +python main.py generate product -cf templates/l2_p2p.yaml --no-dryrun ``` This will create the file `products/product_types/l2_p2p.py`. When looking at this file you can see it created the @@ -134,45 +135,55 @@ domain model, fixed inputs and imported the correct product blocks to be used in Now generate the workflows. This command will always create 4 sets of workflows `create`, `modify`, `terminate` and `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. Make sure to - backup the contents, or restore it afterwards. Bug is tracked in - https://github.com/workfloworchestrator/orchestrator-core/issues/1757. - Run the command: ```shell -python main.py generate workflows -cf templates/l2-p2p.yaml --no-dryrun --force +python main.py generate workflows -cf templates/l2_p2p.yaml --no-dryrun ``` As you can see this file needs to be run with the --force flag as it needs to overwrite a number of configuration -files. Furthermore it will populate the files in `workflows.l2_p2p`. Feel free to take a look and see what it -already has done. +files. Furthermore it will populate the files in `workflows/l2_p2p/`. Do that now: + +```shell +python main.py generate workflows -cf templates/l2_p2p.yaml --no-dryrun --force +``` + +!!! warning + There is a [bug](https://github.com/workfloworchestrator/orchestrator-core/issues/1757) in `generate workflows` + which makes it overwrite the contents of `workflows/shared.py` instead of + extend it with the missing elements. You can use `git restore` to restore it aftwards. + +Take a look around to see which files have been created by now. +Can you explain what each of them are for? #### Database migrations As a final step the user must generate and run the migrations to wire up the database. This is done as follows. ```shell -python main.py generate migration -cf templates/l2-p2p.yaml +python main.py generate migration -cf templates/l2_p2p.yaml python main.py db upgrade heads ``` ### 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 -and start implementing steps to provision the resource that is being created by the create workflow. Take some time -in the orchestrator UI to see what has been configured. +If this has been executed without errors, you should see the option **l2_p2p protected** and +**l2_p2p unprotected** appear in the **New subscription** menu, as well as in the Metadata pages. +Select either product, and try to fill in the form. There is a small quirk with one of the fields, which has been +left in as an exercise to understand the interaction between the workflow form and the UI. + +Once you submit the form you'll notice that creating the subscription does not work right away, as +the "initial_input_form_generator" still needs to be extended with a field to select Port subscriptions for the SAPs, +and the "construct_l2_p2p_model" step will need to be updated accordingly. +This is out of scope for the workshop. -- Metadata pages -- Action menu -- Available workflows +But this should give you an idea how the generator gives users a head start by setting up a product and workflows according +to the best practices. They can then go into the workflow source code and start implementing steps +to provision the resource that is being created by the create workflow. ### Step 5 - Bonus -Implement a new step in the create workflow that manipulates the subscription in a certain way. An example could be +Add a new step in the `create_l2_p2p` 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. ??? example "Answer" From 318db5d46f058b5fc367fcd7e72054070150d89d Mon Sep 17 00:00:00 2001 From: Mark90 Date: Tue, 7 Jul 2026 22:00:51 +0200 Subject: [PATCH 5/6] Ping --- docs/workshops/example-orchestrator/execute-workflows.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/workshops/example-orchestrator/execute-workflows.md b/docs/workshops/example-orchestrator/execute-workflows.md index 8e08613d..fd5ac775 100644 --- a/docs/workshops/example-orchestrator/execute-workflows.md +++ b/docs/workshops/example-orchestrator/execute-workflows.md @@ -75,3 +75,6 @@ You can log in to the router and check the status of ISIS using: show network-instance default protocols isis adjacency show network-instance default protocols isis interface ``` + +Feel free to play around with the created devices. +Can you manage to send a ping through the created link? From f6dcb477e51ab5b9c1f6a203d8dfe787f551c350 Mon Sep 17 00:00:00 2001 From: Mark90 Date: Tue, 7 Jul 2026 22:07:03 +0200 Subject: [PATCH 6/6] Describe architecture documentation as optional --- .../example-orchestrator/workflow-introduction.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/workshops/example-orchestrator/workflow-introduction.md b/docs/workshops/example-orchestrator/workflow-introduction.md index 1e152624..015747c2 100644 --- a/docs/workshops/example-orchestrator/workflow-introduction.md +++ b/docs/workshops/example-orchestrator/workflow-introduction.md @@ -1,11 +1,14 @@ -> This document assumes you are already familiar with the key safeguards and potential pitfalls outlined in the [Architecture of workflows](../../orchestrator-core/architecture/application/workflow.md) - ### Continuing the Workshop The next sections introduce the workflow concept and its relationship to the product model. -Code examples referenced throughout can be found in the example orchestrator under the `.workflows.node` directory. +Code examples referenced throughout can be found in the example orchestrator under the `workflows/` directory. Please read at least the following pages to grasp the functionality of how workflows work and how the user/frontend will interact with the Orchestrator API: * [Workflow Basics](workflow-basics.md) * [Create Workflow](node-create.md) + +!!! info + For more in-depth details you can consult the + [Architecture of workflows](../../orchestrator-core/architecture/application/workflow.md), but this is not required + to complete this workshop.