add documentation for router workflows

docs/admin_guide/wfo/routers.md

 # Routers
+
+Routers are the packet-layer devices that form the backbone of the GÉANT 
+network. They only require an active site subscription to be available, 
+which is the location one is hosted at. Virtually all services depend on an 
+active router subscription. As a result, this is one of the most fundamental 
+subscription instances in GSO.
+
+## Modelling and attributes
+
+The attributes of a router are as follows:
+
+| Attribute name           | Attribute type | Description                                                                                             |
+|--------------------------|----------------|---------------------------------------------------------------------------------------------------------|
+| `router_fqdn`            | `str`          | The FQDN of a router                                                                                    |
+| `router_ts_port`         | `PortNumber`   | The port of the terminal server that this router is connected to.<br/>Used to offer out of band access. |
+| `router_access_via_ts`   | `bool`         | Whether this router should be accessed through the terminal server, or through its loopback address.    |
+| `router_lo_ipv4_address` | `IPv4Address`  | The IPv4 loopback address of a router.                                                                  |
+| `router_lo_ipv6_address` | `IPv6Address`  | The IPv6 loopback address of a router.                                                                  |
+| `router_lo_iso_address`  | `str`          | The ISO address of the router, used for ISIS support.                                                   |
+| `router_role`            | `RouterRole`   | The role of the router, which can be P, PE, or AMT.                                                     |
+| `router_site`            | `SiteBlock`    | The site that this router is located at.                                                                |
+| `vendor`                 | `RouterVendor` | The vendor of a router, either Juniper or Nokia.                                                        |
+
+## Workflows
+
+A router supports different workflows to take it through the subscription 
+lifecycle.
+
+### Deployment
+
+For the deployment of a router, two workflows are required to be run. The 
+first is creation of the router subscription itself, and preparing it for 
+insertion into the network. After completing this workflow, it needs to get 
+added to the iBGP mesh of existing routers in the network.
+
+!!! tip
+    The creation of a new router also requires an active site subscription, 
+    ensure that this is already in place before continuing.
+
+### Creation
+
+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 this is not the case, 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, the 
+router is moved into an `ACTIVE` state.
+
+### 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 due to the fact that the 
+router is now reachable by other machines by its loopback address. Using out 
+of band access is therefore not needed anymore.
+
+### Redeploy
+
+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.
+
+### Termination
+
+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:
+
+1. Deprovision IPAM resources (if selected).
+2. Try to remove configuration form the router (if selected).
+3. Commit removal of configuration (if selected).
+4. For Nokia devices: remove interfaces from Netbox.
+5. Set the subscription status to `TERMINATED`.