Move workflow docstrings into Python files

docs/index.md

@@ -38,8 +38,9 @@ This site is organized in 4 main sections:
   including all the components and the interactions between them
 - [Admin guide](admin_guide/index.md): provides detailed information of 
   the domain models in WFO and all the Ansible mechanics
-- [Workflows](workflow/index.md): provides operational guides of the 
-  Workflow Orchestrator based GAP
+- [Code Documentation](reference/gso/index.md): provides code documentation of the 
+  Workflow Orchestrator based GAP. This includes all models, workflows, and external services
+  that the GAP interacts with.
 
 The documentation provided in this portal is final and reviewed. For information
 about the ongoing work please refer to the [internal wiki page](https://wiki.

docs/workflow/activate_iptrunk.md

-# Activate IP trunk
-
-When the SharePoint checklist of a trunk is completed, this workflow is run to 
-take the subscription from `PROVISIONING` to `ACTIVE`. The operator is asked 
-to give a URL to the completed checklist.

docs/workflow/activate_router.md

-# Activate Router
-
-When the SharePoint checklist of a router is completed, this workflow is run to 
-take the subscription from `PROVISIONING` to `ACTIVE`. The operator is asked 
-to give a URL to the completed checklist.

docs/workflow/create_iptrunk.md

-# Create IP trunk
-
-This the workflow that brings the subscription from `INACTIVE` to `PROVISIONING`.
-The deployment of a new IPtrunk consist in the following steps:
-
-- Fill the form with the necessary fields:
-    - SID
-    - Type
-    - Speed
-    - Nodes
-    - LAG interfaces with description
-    - LAG members with description
-- WFO will query IPAM to retrieve the IPv4/IPv6 Networks necessary for the
-trunk. The container to use is specified in `oss-params.json`
-- The configuration necessary to deploy the LAG is generated and applied to the
-destination nodes using the Ansible playbook `iptrunks.yaml` This is done first 
-in a dry mode (without committing) and then in a real mode committing the
-configuration. The commit message has the `subscription_id` and the
-`process_id`. Included in this, is the configuration necessary to enable LLDP on
-the physical interfaces.
-- Once the LAG interface is deployed, another Ansible playbook is called to 
-verify that IP traffic can actually flow over the trunk ( `iptrunk_checks.yaml`)
-- Once the check is passed, the ISIS configuration will take place using the 
-same `iptrunks.yaml`. Also in this case first there is a dry run and then a
-commit.
-- After this step the ISIS adjacency gets checked using again
-`iptrunks_checks.yaml`
-
-The trunk is deployed with an initial ISIS metric of 90.000 to prevent traffic 
-to pass.

docs/workflow/create_router.md

-# Create Router
-
-To add a new router to the GÉANT network, the `create_router` workflow must 
-be executed first. The intake form for this workflow requires the following 
-fields to be filled in:
-
-* Trouble ticket number
-* Router vendor
-* Router site
-* Hostname
-* Terminal server port
-* Router role
-
-The hostname is validated, by checking that the resulting FQDN is not 
-already taken in IPAM.
-
-!!! warning
-    The validation only checks whether the FQDN is already taken in IPAM, 
-    **not** whether it is registered somewhere on the internet.
-
-When the workflow is started, a subscription object is first instantiated in 
-the service database, containing all the information that was provided in 
-the input form at the beginning. Then, the loopback addresses are allocated 
-in IPAM, which results in both the IPv4 and IPv6 addresses in the product model.
-
-Once allocated, the first dry run of deploying router configuration takes place.
-An Ansible playbook is run, with all the attributes of the new router. This 
-is where GSO communicates with LSO, and the router configuration is checked, 
-but not committed to the machine.
-
-After the dry run, the operator is presented with a view of the outcome of 
-this playbook. This is their opportunity to verify successful execution of 
-the Ansible playbook, and whether the difference in configuration is as 
-expected. If not, this is their chance to abort the workflow, and no harm is
-done to the router.
-
-When the operator confirms the outcome of this playbook execution, the 
-playbook runs once again, but it will also commit the configuration after 
-checking. With the new router configured, the IPAM resources are verified to 
-ensure this external system is configured correctly.
-
-If the new router is a Nokia, all its interfaces are added to Netbox. This 
-is done to keep track of interface reservations and bookkeeping. For Juniper 
-routers, this does not need to take place. These existing devices are not 
-migrated into Netbox.
-
-Finally, an Ansible playbook is run to verify that the connectivity and 
-optical power levels of the router are in order. Once this is completed, a 
-checklist item is created in SharePoint and the router is taken into the
-`PROVISIONING` state.

docs/workflow/create_site.md

-# Create Site
-
-The `create_site` workflow creates a new site object in the service database,
-and sets the subscription lifecycle to `ACTIVE`. The attributes that are input
-using the intake form of the workflow are stored, and nothing else happens.

docs/workflow/deploy_twamp.md

-# Deploy TWAMP
-
-Takes a trunk that is either `PROVISIONING` or `ACTIVE` and deploy configuration
-for TWAMP. The trunk will not change state after running this workflow.

docs/workflow/index.md

-# Workflows
-
-This section contains an overview of all documented workflows in GAP.

docs/workflow/migrate_iptrunk.md

-# Migrate IP trunk
-
-Migrate one side of an IP trunk from one router to another. In the input form,
-the operator selects a new router where this trunk should terminate on.  

docs/workflow/modify_connection_strategy.md

-# Modify connection strategy
-
-Run this workflow to change the way Ansible playbooks connect to a router.
-Either via OOB access, or directly to the loopback interface.

docs/workflow/modify_isis_metric.md

-# Modify ISIS metric
-
-This workflow modifies the ISIS metric of a trunk.
-
-The strategy is to re-apply the necessary template to the configuration
-construct: using a "replace" strategy only the necessary modifications will be
-applied.

docs/workflow/modify_router_kentik_license.md

-# Modify Router Kentik license
-
-Change the license of a router in Kentik. The operator can select the license
-from a list of all available plans in Kentik, and it will show the utilisation
-of each license.

docs/workflow/modify_site.md

-# Modify Site
-
-Attributes of an existing site can be modified using the `modify_site` workflow.
-As a result, other subscriptions that rely on this site will have referenced 
-attributes updated as well. 
-
-!!! warning
-
-    Be aware that although this *does* update attributes in the services 
-    database, it does **not** update any active subscription instances that are
-    already deployed. You will need to run additional workflows to update
-    subscriptions that depend on this change

docs/workflow/modify_trunk_interface.md

-# Modify IP trunk interface
-
-Modifies LAG interfaces and members. This is used to  increase capacity or to
-change SID/interface descriptions.
-
-The strategy is to re-apply the necessary template to the configuration
-construct: using a "replace" strategy only the necessary modifications will be
-applied.

docs/workflow/promote_p_to_pe.md

-# Promote P to PE
-
-Promote a router from the P role to a PE role.

docs/workflow/redeploy_base_config.md

-# Redeploy base configuration
-
-When a new router is deployed, it is loaded with the current version of
-configuration that contain the bare necessities. For various reasons, this 
-template may change, and the resulting configuration follows from this. To 
-update a router 'in the wild' where this change should be reflected, the 
-workflow `redeploy_base_config` is used.
-
-This workflow only takes a trouble ticket number as initial input, and 
-deploys the base configuration, first as a dry run. After confirmation by an 
-operator, the configuration is committed to the machine, and this completes 
-the workflow.

docs/workflow/terminate_iptrunk.md

-# Terminate IP trunk
-
-This workflow deletes all the configuration related with an IPtrunk from the
-network and brings the subscription from `ACTIVE` to `TERMINATED`. The steps
-are the following:
-
-- Modify the ISIS metric of the trunks so to evacuate traffic - and await
-confirmation from an operator.
-- Delete all the configuration (first dry then actual deletion):
-    - LAG and members of the LAG
-    - reference in LLDP protocol (if Juniper)
-    - reference in ISIS protocol
-- Delete the IPv4/IPv6 networks from IPAM

docs/workflow/terminate_router.md

-# Terminate Router
-
-To terminate a router, the workflow `terminate_router` is used. The operator 
-is presented with an input form that requires once again a trouble ticket 
-number. On top of this, there is also the option whether this workflow should
-remove all configuration on the router, and whether IPAM entries related to 
-this device should be removed.
-
-The workflow consists of the following steps:
-
-- Deprovision IPAM resources (if selected).
-- Try to remove configuration form the router (if selected).
-- Commit removal of configuration (if selected).
-- For Nokia devices: remove interfaces from Netbox.
-- Remove the device from LibreNMS.
-- For PE routers: apply the archiving license in Kentik.
-- Set the subscription status to `TERMINATED`.

docs/workflow/terminate_site.md

-# Terminate Site
-
-The `terminate_site` workflow will take an existing and active site 
-subscription from an `ACTIVE` to a `TERMINATED` state. This requires all 
-dependant subscription instances to already be terminated. If this is not 
-the case, the workflow will be unavailable for an operator to run, accompanied
-by an error message explaining this fact.

docs/workflow/update_ibgp_mesh.md

-# Update iBGP mesh
-
-Once a new router is added to the network, it must become reachable by all 
-other devices. To achieve this, the `update_ibgp_mesh` workflow must be 
-executed. This workflow will add the new P router to all PE routers in the 
-network, and add all existing PE routers to the new P router. The only input 
-this workflow takes, is a trouble ticket number. All other required 
-information is already in the service database.
-
-The workflow will run 5 Ansible playbooks:
-
-1. Check: add P router to all PE routers
-2. Deploy: add P router to all PE routers
-3. Check: add all PE routers to P router
-4. Deploy: add all PE routers to P router
-5. Verify: check that the iBGP has come up
-
-Once these playbooks have been run successfully, the new P router is added 
-to LibreNMS. Finally, the subscription model of the router is updated such that
-`router_access_via_ts` is set to `False`. This is because the router is now 
-reachable by other machines by its loopback address. Using out of band access is
-therefore not needed anymore.