From 1846400f976bbd530704fefbcc85180f0cde1f17 Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Wed, 16 Aug 2023 13:36:24 +0200
Subject: [PATCH] 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 | 2 +-
.../components/wfo/modeling/index.md | 23 -----------
.../components/wfo/modeling/ports.md | 38 -------------------
.../components/wfo/workflows/deploy_router.md | 16 --------
.../wfo/workflows/node_provisioning.md | 35 -----------------
docs/architecture/index.md | 3 +-
docs/glossary.md | 13 +++++++
docs/index.md | 4 ++
docs/legacy_platform/overview.md | 9 +++--
docs/modeling/index.md | 2 +-
docs/modeling/ports.md | 6 +--
docs/overview/index.md | 14 ++++---
docs/processes/node_provisioning.md | 4 +-
13 files changed, 40 insertions(+), 129 deletions(-)
delete mode 100644 docs/architecture/components/wfo/modeling/index.md
delete mode 100644 docs/architecture/components/wfo/modeling/ports.md
delete mode 100644 docs/architecture/components/wfo/workflows/deploy_router.md
delete mode 100644 docs/architecture/components/wfo/workflows/node_provisioning.md
diff --git a/docs/admin_guide/index.md b/docs/admin_guide/index.md
index de3d3b2..e74c824 100644
--- a/docs/admin_guide/index.md
+++ b/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
diff --git a/docs/architecture/components/wfo/modeling/index.md b/docs/architecture/components/wfo/modeling/index.md
deleted file mode 100644
index e883929..0000000
--- a/docs/architecture/components/wfo/modeling/index.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# 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
diff --git a/docs/architecture/components/wfo/modeling/ports.md b/docs/architecture/components/wfo/modeling/ports.md
deleted file mode 100644
index 99e1cb9..0000000
--- a/docs/architecture/components/wfo/modeling/ports.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# 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.
-```
diff --git a/docs/architecture/components/wfo/workflows/deploy_router.md b/docs/architecture/components/wfo/workflows/deploy_router.md
deleted file mode 100644
index 3dbfd11..0000000
--- a/docs/architecture/components/wfo/workflows/deploy_router.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# 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.
-```
diff --git a/docs/architecture/components/wfo/workflows/node_provisioning.md b/docs/architecture/components/wfo/workflows/node_provisioning.md
deleted file mode 100644
index 5c888a6..0000000
--- a/docs/architecture/components/wfo/workflows/node_provisioning.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# 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.
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
index cca0329..480179d 100644
--- a/docs/architecture/index.md
+++ b/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
diff --git a/docs/glossary.md b/docs/glossary.md
index 232a073..c9702dc 100644
--- a/docs/glossary.md
+++ b/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
diff --git a/docs/index.md b/docs/index.md
index 6190908..0f5b476 100644
--- a/docs/index.md
+++ b/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}
diff --git a/docs/legacy_platform/overview.md b/docs/legacy_platform/overview.md
index cce2b9f..8e729af 100644
--- a/docs/legacy_platform/overview.md
+++ b/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:
diff --git a/docs/modeling/index.md b/docs/modeling/index.md
index e883929..7793cb5 100644
--- a/docs/modeling/index.md
+++ b/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
diff --git a/docs/modeling/ports.md b/docs/modeling/ports.md
index 99e1cb9..67085c5 100644
--- a/docs/modeling/ports.md
+++ b/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.
diff --git a/docs/overview/index.md b/docs/overview/index.md
index f95ba0c..fc45551 100644
--- a/docs/overview/index.md
+++ b/docs/overview/index.md
@@ -1,10 +1,11 @@
# 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.
diff --git a/docs/processes/node_provisioning.md b/docs/processes/node_provisioning.md
index 5c888a6..d5e4107 100644
--- a/docs/processes/node_provisioning.md
+++ b/docs/processes/node_provisioning.md
@@ -1,8 +1,8 @@
# 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
--
GitLab