From 0e5495a6a5adf54734b84b15aebbf0254aa5b2fa Mon Sep 17 00:00:00 2001
From: Simone Spinelli <simone.spinelli@geant.org>
Date: Tue, 29 Aug 2023 21:32:07 +0200
Subject: [PATCH] More Architecure documentation
---
docs/architecture/components/ansible/index.md | 14 ++++++++++-
docs/architecture/components/index.md | 24 ++++++++++++++++++-
docs/architecture/components/netbox/index.md | 23 +++++++++++++++++-
docs/architecture/components/wfo/index.md | 8 ++++++-
docs/index.md | 11 +++++++++
mkdocs.yml | 1 +
6 files changed, 77 insertions(+), 4 deletions(-)
diff --git a/docs/architecture/components/ansible/index.md b/docs/architecture/components/ansible/index.md
index ab8b4fd..de8cb29 100644
--- a/docs/architecture/components/ansible/index.md
+++ b/docs/architecture/components/ansible/index.md
@@ -1 +1,13 @@
-# Ansible
\ No newline at end of file
+# Ansible
+
+Ansible is responsible of:
+
+- compiling, deploying and deleting configuration on targeted devices
+- gather operational information from the targeted devices
+
+The Ansible subsystem is composed by three main functional parts:
+
+- A plugin that is responsible for exposing the Ansible engine to workflow orchestrator via APIs
+- A set of Ansible roles and playbooks that interacts with the network elements
+- A set of global variables stored in a Git repository that partially build the Ansible Inventory
+
diff --git a/docs/architecture/components/index.md b/docs/architecture/components/index.md
index 49c72b0..c411f4e 100644
--- a/docs/architecture/components/index.md
+++ b/docs/architecture/components/index.md
@@ -1 +1,23 @@
-# Components of GAP
\ No newline at end of file
+# Components of GAP
+
+As previously stated, GAP is a platform and not a monolitic piece of software. GAP interacts with different OSS/BSS systems already present in GÉANT and these are tightly part of it in a certain sense.
+
+From a high level point of view, GAP can be seen as the sum of these parts:
+
+- __A service database__ called CoreDB that contains the models of the service intances, called _subscriptions_. Subscriptions are abstract objects that represent functional configuration constructs: the attributes that characterize these objects are defined in the _domain models_.
+
+- __An orchestration engine__ called Workflow Orchestrator that is capable of executing lists of steps called workflows.
+
+- __A web interface__ for operators, called Orchestrator GUI to intuitively launch and inspect workflows.
+
+- __An automation engine__, Ansible, capable of intracting with network devices to configure them or to gather operational information.
+
+- __A set of authoritative systems to manage resources__:
+ - IP addresses and DNS names (Infoblox)
+ - Physical interfaces (Netbox)
+
+ To interact with these external systems, specific plugins or wrappers are in place.
+
+An overview of how these components interacts is depicted in the following diagram:
+
+{ width=300}
\ No newline at end of file
diff --git a/docs/architecture/components/netbox/index.md b/docs/architecture/components/netbox/index.md
index da7a2fe..b35d4ec 100644
--- a/docs/architecture/components/netbox/index.md
+++ b/docs/architecture/components/netbox/index.md
@@ -1 +1,22 @@
-# Netbox
\ No newline at end of file
+# Netbox
+
+Netbox is a DCIM (DataCenter Infrastructure Manager) capable of managing inventory of Sites, Racks, Devices, Ports etc...
+
+In our case we use Netbox to store information about utilization of physical interfaces.
+
+There are some strong assumptions that we make:
+
+- all the nodes have a fixed configuration that does not change often over time
+- the only point where operators can allocate interfaces is GAP.
+- we do not manage the legacy Juniper network
+
+## Network hardware
+
+The new routers have a static hardware configuration which is dependant from the TIER. The following table summarize it:
+
+|Tier|Chassis|Control plane|Switching fabric|Linecard|
+|--|--|--|--|--|
+|Tier1|SR7s|2x CPM2-s|4x SFM7-s|2x XCM2 - 2x XMA2-s (36p QSFPDD)|
+|Tier2|SR7s|2x CPM2-s|4x SFM7-s|2x XCM2 - 2x XMA2-s (36p QSFPDD)|
+|Tier3|TBD|TBD|TBD|TBD|
+|Tier4|TBD|TBD|TBD|TBD|
\ No newline at end of file
diff --git a/docs/architecture/components/wfo/index.md b/docs/architecture/components/wfo/index.md
index 548ff30..d584ff3 100644
--- a/docs/architecture/components/wfo/index.md
+++ b/docs/architecture/components/wfo/index.md
@@ -1 +1,7 @@
-# Workflow Orchestrator
\ No newline at end of file
+# Workflow Orchestrator
+
+In this page, we describe the mechanisms that govern:
+
+- Workflow Orchestrator
+- CoreDB
+- The "framework" for the integration plugins
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 9b6e637..ec76746 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -13,9 +13,18 @@ GAP represents the vision of GÉANT in terms of Network Automation and Orchestra
- to introduce a different way of working that avoids fragmentation and silos.
GAP is partially based on Open Source Software and partially internally developed and integrates with most of the tooling already in use in GÉANT.
+
+!!! Acknoledgements
+
+ The OSS components that GAP uses are mainly:
+
+ - Workflow Orchestrator [https://workfloworchestrator.org/](https://workfloworchestrator.org/) (developed and maintained by [Surf](https://www.surf.nl/) and [ESnet](https://www.es.net/))
+ - Ansible [https://www.ansible.com/](https://www.ansible.com/)
+
More information about the GAP architecture is available in the [Architecture](./architecture/index.md) section.
+
## About this documentation portal
This site is organized in 4 main sections:
@@ -29,4 +38,6 @@ The documentation provided in this portal is final and reviewed. For information
Also this documentation does not cover the design of network services, just the modelling and the mechanics related with automation.
+!!! Info
+ For any info or clarification you can refer to goat_at_geant_dot_org
diff --git a/mkdocs.yml b/mkdocs.yml
index a77c815..2a5636f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -85,6 +85,7 @@ nav:
# Extensions
markdown_extensions:
+ - admonition
- abbr
- attr_list
- md_in_html
--
GitLab