Add content on architecture

Add paragraphs in architecture
Add glossary with used terms
Add MyST addons
Expand list of GÉANT whitelisted terms

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

docs/architecture/index.md

@@ -6,10 +6,10 @@ versions all configuration, and it's also responsible for managing mechanisms su
 * Automatic checks to validate data and data references.
 * Merge requests for change approval.
 
-We try to keep the stack of tools limited:
+The stack of tools is kept limited:
 
 * Ansible is the tool that deploys configuration and orchestrates changes.
-* If needed, custom Python scripts can be used to support extra functionality.
+* If needed, custom Python scripts can support extra functionality.
 
 This approach works well for the deployment of 'base configuration'. For service fulfillment, three more components are
 introduced:
@@ -25,8 +25,8 @@ The configuration of a network element can be decomposed in different functional
 
 * Base configuration.
 * Service configuration:
-  * Interface facing services (IFS)
-  * Customer facing services (CFS)
+  * {term}`IFS`
+  * {term}`CFS`
 
 The base configuration includes all configuration necessary to provision a new node, and to include it in the network.
 It covers aspects such as:
@@ -64,3 +64,59 @@ infrastructure from the high-level, network-wide intent.
 * Automatic check evaluate all changes
 * After passing pipelines, all changes are merged into the `main` branch. These pipelines run once a change is 
 peer-reviewed and approved.
+
+- - -
+
+## Orchestration and service DB
+
+All services offered can be summarised in the following four categories. Some examples are given in the table below.
+
+|         | Multipoint  | Point 2 point    |
+|---------|-------------|------------------|
+| Layer 2 | VPLS / EVPN | Layer 2 circuits |
+| Layer 3 | L3VPN       | Core links       |
+
+### 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
+
+
+### Services and ports
+
+While a port shouldn't be configured in case there is no service insisting on it, it could happen that multiple
+services are insisting on the same port. For this reason, we define the following entities:
+
+{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.
+```

docs/conf.py

@@ -13,7 +13,7 @@ source_suffix = {
 }
 
 # -- Options for Markdown support --------------------------------------------
-myst_enable_extensions = ['replacements', 'smartquotes', 'strikethrough']
+myst_enable_extensions = ['attrs_block', 'deflist', 'replacements', 'smartquotes', 'strikethrough']
 suppress_warnings = ['myst.strikethrough']
 
 # -- Options for HTML output -------------------------------------------------

docs/glossary.md

+# Glossary of terms
+
+{.glossary}
+CFS
+: Customer Facing Service
+
+GA
+: Access Port
+
+GAN
+: Access Node
+
+GP
+: Physical Port
+
+IFS
+: Interface Facing Service
+
+MPLS
+: Multi-Protocol Label Switching
+
+MTTR
+: Mean Time To Repair
+
+SDP
+: Service Delivery Point

docs/index.md

@@ -7,4 +7,5 @@ The focus of this platform is configuration management and service orchestration
 ```{toctree}
 overview/index.md
 architecture/index.md
+glossary.md
 ```

docs/overview/index.md

@@ -3,7 +3,7 @@
 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.
 
-In the context of the IP/MPLS layer and particularly the backbone routers, different teams manage configuration in
+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.
 
@@ -12,7 +12,7 @@ and DevOps strategies there is one single framework to deploy and to operate. Co
 code and managing it under a version control system (GitLab) will enable better visibility and control of changes and 
 will help standardize the way of working.
 
-The goal is to reduce configuration drifts and exceptions, Mean Time To Repair (MTTR) in case of fault, and possibly the
+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
 to ensure the highest quality and to detect problems early.

docs/vale/styles/Vocab/geant-jargon/accept.txt

 IP/MPLS
 MPLS
+MTTR
 configuration as code
-reachability
-loopback
+[Rr]eachability
+[Ll]oopback
 Ansible
 [Bb]ackbone
 IFS
 CFS
+GAN
+SDP
 AAA
 GÉANT Automation Platform
 GAP
+[Mm]ultipoint