diff --git a/docs/admin_guide/wfo/routers.md b/docs/admin_guide/wfo/routers.md index 932021c8fdcb60695d5c2472a69442f5a135040b..dd264da4c6ec3cf0058babade3457352ab71d2ba 100644 --- a/docs/admin_guide/wfo/routers.md +++ b/docs/admin_guide/wfo/routers.md @@ -1 +1,141 @@ # 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`.