update documentation

remove duplicate files
add references to glossary where relevant

Signed-off-by: Karel van Klink <karel.vanklink@geant.org>

docs/admin_guide/index.md

@@ -5,7 +5,7 @@ Next to this, also troubleshooting and maintenance are included.
 
 The structure is:
 
-- WFO
+- {term}`WFO`
   - Modelling
   - Workflow
   - Maintenance

docs/architecture/components/wfo/modeling/index.md

-# Data models
-
-To be able to model network objects, a data model must exist for every configuration item in the network. This allows
-for describing the network, and the services as a composition of abstract objects.
-
-## Decomposition of objects
-
-Every object -- both services and access ports -- is composed of the following building blocks:
-* Administrative metadata
-  * Object ID
-  * Status
-  * Owner
-* Configuration data that depends on the specific service, some examples:
-  * Access port
-    * Access port type
-    * Physical interfaces
-  * IP trunk
-    * IPv4 network
-    * IPv6 network
-    * IS-IS metric
-* Placement metadata
-  * Access node
-  * Service delivery point

docs/architecture/components/wfo/modeling/ports.md

-# Services and ports
-
-While a port shouldn't be configured in case there is no service insisting on it, it could happen that more than one
-service is insisting on one port. For this reason, the following entities exist:
-
-{term}`SDP`
-: Service Delivery Point: the logical interface where a service is delivered
-
-{term}`GA`
-: Access Port: an access point into the GÉANT network
-
-{term}`GP`
-: Physical Port: the physical boundary for the {term}`GA`
-
-{term}`GAN`
-: Access Node: the node where a service is delivered
-
-These concepts apply to both {term}`CFS`es and {term}`IFS`es.
-
-```{figure} ../static/access_port_diagram.png
-:alt: Diagram that displays the different entities that make up a GÉANT service.
-
-A visualisation of how services insist on ports.
-```
-
-## Peer-to-peer and multipoint services
-
-There is a distinction between services -- as mentioned in [configuration (de)composition](#configuration-decomposition)
--- between peer-to-peer and multipoint services. In both cases, {term}`SDP` is the delivery point of a service.
-However, for multipoint services customers are supposed to be dual-homed in at least two different {term}`GAN`s.
-
-To give some examples, the figure below shows a decomposition of a GeantIP service for an NREN.
-
-```{figure} ../static/geant_ip_ports_diagram.png
-:alt: Diagram that displays the different entities that make up a GeantIP service instance.
-
-A visualisation of an instance of a GeantIP service that consists of different configuration objects.
-```

docs/architecture/components/wfo/workflows/deploy_router.md

-# Router deployment
-
-From a bird's-eye view, the process of deploying a new router in the network is as follows:
-
-1. Manually configure the router such that it's reachable from out-of-band ({term}`OOB`).
-2. Upgrade the router to the most recent OS.
-3. Deploy base configuration.
-4. Configure trunks to connect the router to the network.
-5. Update the protocol meshes (such as {term}`iBGP`).
-6. Promote the router to the production environment.
-
-```{figure} ../static/WFO_deploy_router.png
-:alt: Diagram that displays the steps that Workflow Orchestrator takes to provision a new router. 
-
-{term}`WFO` provisions a new router by following the steps shown here.
-```

docs/architecture/components/wfo/workflows/node_provisioning.md

-# Node provisioning
-
-A node can either be a router, a switch, or a terminal server. In general -- as laid out more extensively 
-[here](https://wiki.geant.org/display/NETENG/001+-+Topology+and+physical+layout) (behind login) -- a {term}`PoP` 
-consists of:
-
-* One or two routers
-* One switch
-* One terminal server
-
-Globally, the workflow for a new site is as follows:
-
-1. Deploy terminal server:
-   1. Generate base configuration from GitLab
-   2. Ship the device to its location
-   3. Verify reachability and insert in LibreNMS
-2. Deploy {term}`PoP` router in a 'core' fashion
-   1. Rack it up and configure the hardware
-   2. Connect the router to the terminal server via both a console connection, and FXP
-   3. Deploy base configuration using {term}`GAP`
-3. Deploy {term}`PoP` switch
-   1. Rack it up and configure the hardware
-   2. Connect the switch to the terminal server via both a console connection, and FXP
-   3. Deploy base configuration using {term}`GAP`
-4. Deploy the {term}`PoP` interconnect between router and switch
-   1. Set up a physical connection between router and switch
-   2. Deploy configuration using {term}`GAP`
-5. Deploy IP trunks to connect the router to the rest of the network
-   1. Set up a physical connection
-   2. Deploy configuration using {term}`GAP`
-6. Update the {term}`iBGP` mesh to include the new router, promoting it to an edge router
-   1. Deploy configuration using {term}`GAP`
-   2. Using {term}`GAP`, insert the devices in LibreNMS
-
-In the context of the automation platform, the {term}`PoP` interconnects mentioned are modeled as separate objects.

docs/architecture/index.md

@@ -61,7 +61,8 @@ On top of this 'base layer' services can be deployed. Some examples of offered s
 infrastructure from the high-level, network-wide intent.
 * Any network changes are automatically halted and rolled back if the network displays unintended behaviour.
 * The infrastructure doesn't allow operations that violate network policies. 
-[Source.](https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/45687.pdf)
+<a href="https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/45687.pdf" 
+target="_blank">Source</a>.
 
 ### Other principles
 

docs/glossary.md

@@ -28,6 +28,13 @@ iBGP
 IFS
 : Interface Facing Service
 
+IP
+: Internet Protocol
+
+IS-IS
+: Intermediate System to Intermediate System: a routing protocol described in 
+<a href="https://datatracker.ietf.org/doc/html/rfc7142" target="_blank">{term}`RFC` 7142</a>.
+
 MPLS
 : Multi-Protocol Label Switching
 
@@ -37,12 +44,18 @@ MTTR
 MTU
 : Maximum Transmission Unit
 
+NREN
+: National Research and Education Network
+
 OOB
 : Out-of-band
 
 PoP
 : Point of Presence
 
+RFC
+: Request For Comments
+
 SDP
 : Service Delivery Point
 

docs/index.md

@@ -9,7 +9,11 @@ This documentation has the following sections:
 :caption: Architecture
 :maxdepth: 1
 overview/index.md
+modeling/index.md
+modeling/ports.md
 architecture/index.md
+processes/deploy_router.md
+processes/node_provisioning.md
 ```
 
 ```{toctree}

docs/legacy_platform/overview.md

@@ -2,8 +2,11 @@
 
 The current {term}`GAP` is simple and its fundamental parts are:
 
-- An [Ansible inventory](https://gitlab.geant.net/neteam/network-automation/na-production/prod_network_inventory/-/tree/master) stored in Git
-- A set of [Ansible playbooks](https://gitlab.geant.net/neteam/network-automation/na-production/prod_network_ansible) stored in Git
+- An <a href="https://gitlab.geant.net/neteam/network-automation/na-production/prod_network_inventory/-/tree/master" 
+target="_blank">Ansible inventory</a> stored in Git
+- A set of 
+<a href="https://gitlab.geant.net/neteam/network-automation/na-production/prod_network_ansible" target="_blank">Ansible
+playbooks</a> stored in Git
 - An Ansible master instance to execute these playbooks
 - A Jenkins instance to orchestrate Ansible
 
@@ -19,7 +22,7 @@ Currently, {term}`GAP` is capable of the following capabilities:
 - Provisioning of nodes and {term}`IP` trunks:
   - Deployment of base configuration on a new router
   - Deployment of a new trunk with metric=9000
-  - Insertion of a new router in the iBGP mesh
+  - Insertion of a new router in the {term}`iBGP` mesh
 - Periodic checks of configuration:
   - Verification of single stanza of configuration
 - Others:

docs/modeling/index.md

@@ -17,7 +17,7 @@ Every object -- both services and access ports -- is composed of the following b
   * IP trunk
     * IPv4 network
     * IPv6 network
-    * IS-IS metric
+    * {term}`IS-IS` metric
 * Placement metadata
   * Access node
   * Service delivery point

docs/modeling/ports.md

@@ -17,7 +17,7 @@ service is insisting on one port. For this reason, the following entities exist:
 
 These concepts apply to both {term}`CFS`es and {term}`IFS`es.
 
-```{figure} ../static/access_port_diagram.png
+```{figure} /static/access_port_diagram.png
 :alt: Diagram that displays the different entities that make up a GÉANT service.
 
 A visualisation of how services insist on ports.
@@ -29,9 +29,9 @@ There is a distinction between services -- as mentioned in [configuration (de)co
 -- between peer-to-peer and multipoint services. In both cases, {term}`SDP` is the delivery point of a service.
 However, for multipoint services customers are supposed to be dual-homed in at least two different {term}`GAN`s.
 
-To give some examples, the figure below shows a decomposition of a GeantIP service for an NREN.
+To give some examples, the figure below shows a decomposition of a GeantIP service for an {term}`NREN`.
 
-```{figure} ../static/geant_ip_ports_diagram.png
+```{figure} /static/geant_ip_ports_diagram.png
 :alt: Diagram that displays the different entities that make up a GeantIP service instance.
 
 A visualisation of an instance of a GeantIP service that consists of different configuration objects.

docs/overview/index.md

 # Overview
 
 Configuration management is the process that maintains consistency and integrity of the network and of the services
-built on top of it. It ensures that the network meets requirements in terms of functionalities, performances, and security.
+built on top of it. It ensures that the network meets requirements in terms of functionalities, performance, and 
+security.
 
-In the context of the IP/{term}`MPLS` layer and particularly the backbone routers, different teams manage configuration in
-different ways. To deploy new nodes and to operate the network, they use various tools en methods. These tools check 
+In the context of the IP/{term}`MPLS` layer and particularly the backbone routers, different teams manage configuration
+in different ways. To deploy new nodes and to operate the network, they use various tools en methods. These tools check 
 compliance and quality afterward: this approach requires much manual work, and it's inherently error-prone.
 
 This project aims to standardize the configuration and the configuration deployment process. By using Open Source tools
@@ -13,9 +14,10 @@ code and managing it under a version control system (GitLab) will enable better
 will help standardize the way of working.
 
 The goal is to reduce configuration drifts and exceptions, {term}`MTTR` in case of fault, and possibly the
-number and the severity of incidents. To verify configuration compliance before it gets deployed, several policies are in
-place. Multiple non-production environments are used to automatically run regression and acceptance tests, in order
+number and the severity of incidents. To verify configuration compliance before it gets deployed, several policies are
+in place. Multiple non-production environments are used to automatically run regression and acceptance tests, in order
 to ensure the highest quality and to detect problems early.
 
 Automated configuration management must be considered as the foundation of further work in network automation, towards
-service orchestration trough different technology domains (Optical, IP/MPLS, Applications) and intent-based networking.
+service orchestration trough different technology domains (Optical, IP/{term}`MPLS`, Applications) and intent-based
+networking.

docs/processes/node_provisioning.md

 # Node provisioning
 
 A node can either be a router, a switch, or a terminal server. In general -- as laid out more extensively 
-[here](https://wiki.geant.org/display/NETENG/001+-+Topology+and+physical+layout) (behind login) -- a {term}`PoP` 
-consists of:
+<a href="https://wiki.geant.org/display/NETENG/001+-+Topology+and+physical+layout" target="_blank">here</a> (behind
+login) -- a {term}`PoP`consists of:
 
 * One or two routers
 * One switch