From f3b474e4361718f4e2a2872b5263fc4feeaeb7e9 Mon Sep 17 00:00:00 2001
From: Simone Spinelli <simone.spinelli@geant.org>
Date: Tue, 29 Aug 2023 06:33:55 +0200
Subject: [PATCH] Architecture section: intro and config decomposition
---
docs/admin_guide/oss_bss/kentik.md | 2 +
docs/admin_guide/oss_bss/librenms.md | 1 +
docs/architecture/components/index.md | 1 +
.../config_decomposition/index.md | 64 +++++++++++++++++++
docs/architecture/index.md | 13 +++-
mkdocs.yml | 16 +++--
6 files changed, 92 insertions(+), 5 deletions(-)
create mode 100644 docs/architecture/components/index.md
create mode 100644 docs/architecture/config_decomposition/index.md
diff --git a/docs/admin_guide/oss_bss/kentik.md b/docs/admin_guide/oss_bss/kentik.md
index e69de29..3cc593c 100644
--- a/docs/admin_guide/oss_bss/kentik.md
+++ b/docs/admin_guide/oss_bss/kentik.md
@@ -0,0 +1,2 @@
+# Integration with Kentik
+
diff --git a/docs/admin_guide/oss_bss/librenms.md b/docs/admin_guide/oss_bss/librenms.md
index e69de29..447c662 100644
--- a/docs/admin_guide/oss_bss/librenms.md
+++ b/docs/admin_guide/oss_bss/librenms.md
@@ -0,0 +1 @@
+# Integration with LibreNMS
diff --git a/docs/architecture/components/index.md b/docs/architecture/components/index.md
new file mode 100644
index 0000000..49c72b0
--- /dev/null
+++ b/docs/architecture/components/index.md
@@ -0,0 +1 @@
+# Components of GAP
\ No newline at end of file
diff --git a/docs/architecture/config_decomposition/index.md b/docs/architecture/config_decomposition/index.md
new file mode 100644
index 0000000..60d1ba0
--- /dev/null
+++ b/docs/architecture/config_decomposition/index.md
@@ -0,0 +1,64 @@
+# Configuration decomposition
+
+## Functional decomposition
+
+Every configuration statement express a particular function, we currently decompose the configuration according to this taxonomy:
+
+{ width='300' }
+
+### Base configuration
+
+It is present on all the nodes it performs exactly the same function adapting to particular values or characteristic of the node itself.
+Examples are:
+
+- SNMP communities: are the same for all the routers, including the client list
+- AAA (local user and radius authentication): the same on all the routers, but the source address of Radius requests is the loopback of the specific device
+
+Once the router has been configured with the base configuration, it is ready for the installation of one or more IPtrunks that will connect it to the rest of the network.
+
+At this point, the router's loopback is reachable via IGP and the new device can be inserted in the network configuring iBGP mesh and adding it to tooling.
+
+Now the router is in service, ready to carry services.
+
+### Service prerequisites
+
+L3VPNs must exist on the router before customer facing services can be configured, there might be also specific communities or routing policies that are generic and are considered as prerequisite for customer connections.
+This functional block is responsible for this.
+
+
+### Service
+
+This block represent a service on the edge: a L2circuit or a BGP peer. This block is itself decomposed in other parts, according to the functional parts needed by configuration.
+In general, we use a meta-service called demarcation point, to identify the physical interface on which the service should be delivered:
+
+{ width='400' }
+
+A service is always delivered on a VLAN (that can be native VLAN in some particula cases, for example IPtrunk). The VLAN is called "Service Delivery Point".
+
+## Separation of data and configuration
+
+Configuration can be seen as the composition of some abstract data structure that represent the business logic, and a template that match the router's specific config dialect.
+In the following example we are going to configure DNS servers on a Juniper and a Nokia router:
+
+DNS servers (abstract data):
+
+```
+system_name_servers:
+ - 192.168.1.1
+ - 192.168.1.254
+```
+
+Junos template:
+```
+system {
+ replace: name-server {
+ {%- for name_server in system_name_servers %}
+ {{ name_server }};
+ {%- endfor %}
+ }
+}
+```
+Nokia template:
+```
+
+```
\ No newline at end of file
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
index 8f222b1..141d470 100644
--- a/docs/architecture/index.md
+++ b/docs/architecture/index.md
@@ -9,6 +9,9 @@ The diagram, shows how GAP position itself as a single point of access not only
GAP is responsible not only to allocate and release these resources but also to verify that all the systems are in sync over time.
In other words, operators are no longer responsible to prepare resources before doing changes (for example allocating IP networks or addresses and configuring accordingly DNS): the GAP component responsible for the interaction with that particular system will take care of allocating and configure the necessary resources.
+
+Included in the orchestration layer, there is a service database that stores all the instances of the services in accordance to the domain models. More details are available in the section [GAP components](../architecture/components/index.md)
+
## OSS/BSS systems currently in scope
### Infoblox
@@ -24,7 +27,7 @@ More detailed information about this integration is available in the [Ipam integ
### Netbox
-Netbox is responsible of managing physical resources such as nodes and interfaces.
+Netbox is responsible of managing physical resources such as nodes and interfaces. More specifically, it contains all the routers and the interfaces and provides to WFO the list of free interfaces.
An interface can be in 3 different states:
@@ -36,9 +39,17 @@ More detailed information about this integration is available in the [Physical r
### LibreNMS
+LibreNMS is a general purpose monitoring system in use at GÉANT to gather relevant metrics as well as checks and facts. LibreNMS is also the inventory for Oxidized: a network configuration backup system that is used to have versioned configuration backups of routers, switches and any other network device that is supported.
More detailed information about this integration is available in the [LibreNMS integration module](../admin_guide/oss_bss/librenms.md)
### Kentik (planned)
+Kentik is a Network Observability tool and it collects serveral information from our PE routers. For this reason it is not in scope for PHASE1.
+
+### Inventory Provider (planned)
+
+At the time of writing, Inventory provider gets the list of the routers from network engineering SOT servers. This will change and Inventory provider can directly query coreDB.
+
## Interaction with a technical domain: IP/MPLS
+GAP
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index d20f416..a77c815 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -45,15 +45,17 @@ nav:
- Home: index.md
- Architecture:
- architecture/index.md
+ - architecture/config_decomposition/index.md
+ - Components:
+ - architecture/components/index.md
+ - WFO: architecture/components/wfo/index.md
+ - Netbox: architecture/components/netbox/index.md
+ - Ansible: architecture/components/ansible/index.md
- DTAP:
- architecture/dtap/index.md
- Test: architecture/dtap/test.md
- Acceptance: architecture/dtap/acceptance.md
- Production: architecture/dtap/production.md
- - Components:
- - Ansible: architecture/components/ansible/index.md
- - WorkflowOrchestrator: architecture/components/wfo/index.md
- - Netbox: architecture/components/netbox/index.md
- User Guide:
- user_guide/index.md
- Sites:
@@ -72,6 +74,11 @@ nav:
- Sites: admin_guide/WFO/sites.md
- Routers: admin_guide/WFO/routers.md
- Iptrunks: admin_guide/WFO/iptrunks.md
+ - OSS/BSS integration:
+ - Infoblox: admin_guide/oss_bss/ipam.md
+ - Netbox: admin_guide/oss_bss/netbox.md
+ - LibreNMS: admin_guide/oss_bss/librenms.md
+ - Kentik: admin_guide/oss_bss/kentik.md
- Legacy Platform:
- Overview: legacy_platform/overview.md
- New Router Deployment: legacy_platform/new_router_deployment.md
@@ -80,6 +87,7 @@ nav:
markdown_extensions:
- abbr
- attr_list
+ - md_in_html
- pymdownx.snippets:
auto_append:
- includes/glossary.md
--
GitLab