Merge pull request #55 from nautobot/pr-docs-review

OSRB review
nautobot · Sep 2, 2022 · 3e44267 · 3e44267
2 parents 6b63d3c + 07b95f2
commit 3e44267
Show file tree

Hide file tree

Showing 18 changed files with 250 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # Nautobot BGP Models Plugin
 
-A plugin for [Nautobot](https://github.com/nautobot/nautobot) to extend the core models with BGP specific models. All types of BGP peerings can be model and managed, whether or not the device is present in Nautobot.
+A plugin for [Nautobot](https://github.com/nautobot/nautobot) extending the core models with BGP-specific models.
+
+New models enable modeling and management of BGP peerings, whether or not the peer device is present in Nautobot.
 
 > The initial development of this plugin was sponsored by Riot Games, Inc.
 

diff --git a/development/docker-compose.dev.yml b/development/docker-compose.dev.yml
@@ -7,11 +7,22 @@ version: "3.4"
 services:
   nautobot:
     command: "nautobot-server runserver 0.0.0.0:8080"
+    ports:
+      - "8080:8080"
     volumes:
       - "./nautobot_config.py:/opt/nautobot/nautobot_config.py"
       - "../:/source"
+  docs:
+    entrypoint: "mkdocs serve -v -a 0.0.0.0:8080"
     ports:
-      - "8080:8080"
+      - "8001:8080"
+    volumes:
+      - "../docs:/source/docs:ro"
+      - "../mkdocs.yml:/source/mkdocs.yml:ro"
+    image: "nautobot-bgp-models/nautobot:${NAUTOBOT_VER}-py${PYTHON_VER}"
+    healthcheck:
+      disable: true
+    tty: true
   worker:
     volumes:
       - "./nautobot_config.py:/opt/nautobot/nautobot_config.py"

diff --git a/docs/cisco_use_case.md b/docs/cisco_use_case.md
@@ -1,8 +1,10 @@
 # Example use of BGP Models plugin - Cisco BGP Configuration
+
 This document provides an example of generating a Cisco device's desired BGP configuration based on data stored in Nautobot using this plugin. A GraphQL query is used to retrieve the relevant data, which is then rendered through a Jinja2 template to produce the desired configuration.
 
 ## Querying for the data
-In order to retrieve a BGP data, following GraphQL can be issued to a Nautobot.  
+
+In order to retrieve a BGP data, following GraphQL query can be issued to Nautobot.
 
 ```python
 import pynautobot
@@ -352,7 +354,7 @@ router bgp {{ data.device.bgp_routing_instances.0.autonomous_system.asn }}
 
 Following snippet represents an example Cisco BGP Renderer Configuration:
 
-```
+```text
 ! 
 router bgp 65535 
  neighbor EDGE-to-LEAF peer-group 

diff --git a/docs/example.md b/docs/example.md
@@ -0,0 +1,11 @@
+# Examples
+
+To make the start with the plugin easier, we provide two example use cases for common OS platforms: Cisco and Juniper.
+
+## Cisco Configuration Modeling and Rendering
+
+Navigate to [Cisco Example Use Case](cisco_use_case.md) for detailed instructions on how to consume the BGP Models plugin on Cisco devices.
+
+## Juniper Configuration Modeling and Rendering
+
+Navigate to [Juniper Example Use Case](juniper_use_case.md) for detailed instructions on how to consume the BGP Models plugin on Juniper devices.
diff --git a/docs/images_manual/add_asn_12345.png b/docs/images_manual/add_asn_12345.png
diff --git a/docs/images_manual/add_external_peering.png b/docs/images_manual/add_external_peering.png
diff --git a/docs/images_manual/add_internal_peering.png b/docs/images_manual/add_internal_peering.png
diff --git a/docs/images_manual/add_new_ri.png b/docs/images_manual/add_new_ri.png
diff --git a/docs/images_manual/external_peering_created.png b/docs/images_manual/external_peering_created.png
diff --git a/docs/images_manual/internal_peering_created.png b/docs/images_manual/internal_peering_created.png
diff --git a/docs/images_manual/menu.png b/docs/images_manual/menu.png
diff --git a/docs/images_manual/ri_list_view.png b/docs/images_manual/ri_list_view.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,8 @@
 # Nautobot BGP Models Plugin
 
-A plugin for [Nautobot](https://github.com/nautobot/nautobot) to extend the core models with BGP specific models. All types of BGP peerings can be model and managed, whether or not the device is present in Nautobot.
+A plugin for [Nautobot](https://github.com/nautobot/nautobot) extending the core models with BGP-specific models.
+
+New models enable modeling and management of BGP peerings, whether or not the peer device is present in Nautobot.
 
 > The initial development of this plugin was sponsored by Riot Games, Inc.
 

diff --git a/docs/juniper_use_case.md b/docs/juniper_use_case.md
@@ -1,8 +1,10 @@
 # Example use of BGP Models plugin - Juniper BGP Configuration
+
 This document provides an example of generating a Juniper device's desired BGP configuration based on data stored in Nautobot using this plugin. A GraphQL query is used to retrieve the relevant data, which is then rendered through a Jinja2 template to produce the desired configuration.
 
 ## Querying for the data
-In order to retrieve a BGP data, following GraphQL can be issued to a Nautobot.  
+
+To retrieve BGP data, the following GraphQL query can be issued to Nautobot.
 
 ```python
 import pynautobot
@@ -344,7 +346,7 @@ set protocols bgp group {{ endpoint.peer_group.name }} neighbor {{ endpoint.peer
 
 Following snippet represents an example Juniper BGP Renderer Configuration:
 
-```
+```text
 root# show protocols bgp
 group EDGE-to-LEAF {
     type internal;

diff --git a/docs/manual.md b/docs/manual.md
@@ -0,0 +1,92 @@
+# Introduction
+
+Below shows the workflows for the two most common BGP Plugin use cases: modeling internal and external peering. We will showcase how to create each type of peering with the minimum number of steps and inputs required from users.
+
+## Menu Item
+
+All of the "Add object" actions are available under BGP Models Plugin Menu in the top navigation bar:
+![Routing menu](images_manual/menu.png "Routing Menu")
+
+## Internal Peering Creation
+
+To model an internal peering (two devices sharing the same ASN), following has to be defined for two BGP speaker devices:
+
+- a BGP Routing Instance
+- IP Address of an endpoint
+
+
+Note that having a BGP Routing Instance is not mandatory, however we recommend creating this object for devices modeled in Nautobot.
+
+### Autonomous System Creation
+
+The first step is to add an Autonomous System object (via the top menu).
+
+Fill the object details:
+
+![Autonomous System Form](images_manual/add_asn_12345.png "Autonomous System Form")
+
+### BGP Routing Instances creation
+
+The next step is to create a BGP Routing Instance for each device of an internal BGP peering.
+A BGP Routing Instance itself is a representation (or a declaration) of a BGP process on a given device.
+
+Fill the object details:
+
+![BGP Routing Instance Form](images_manual/add_new_ri.png "BGP Routing Instance Form")
+
+Repeat for next devices and check the overall result in the BGP Routing Instance list view:
+
+![BGP Routing Instances List](images_manual/ri_list_view.png "BGP Routing Instances List")
+
+### Peering creation
+
+Under the menu "BGP Peerings - Peerings" click on the "Add" button to add a new peering.
+You will be redirected to a view with two columns in a table, each column representing one side of a BGP peering.
+To create a BGP Peering, you have to complete information for two sides.
+
+![BGP Peering Form](images_manual/add_internal_peering.png "BGP Peering Form")
+
+To create an internal BGP Peering, you only need to specify an existing BGP Routing Instance and an IP Address.
+
+### Peering detail view
+
+Once the BGP Peering is created, you could review its details.
+
+![BGP Peering Details](images_manual/internal_peering_created.png "BGP Peering Details")
+
+
+## External Peering Creation
+
+To model an external peering (two devices having different ASN), the following has to be defined:
+
+- For a device present in Nautobot:
+    - a BGP Routing Instance
+    - IP Address of an endpoint
+
+- For a device not present in Nautobot:
+    - an Autonomous System
+    - IP Address of an endpoint
+
+The steps required to create an internal peer have been explained in the previous section.
+
+### Autonomous System Creation - for Provider
+
+The first step is to add an Autonomous System object for a Provider.
+Fill in the object details and ensure the optional field "Provider" is filled.
+
+### Peering creation
+
+Once the Autonomous System and BGP Routing Instance objects have been created you are ready to create a peering between two devices.
+Under the menu "BGP Peerings - Peerings" click on the "Add" button to add a new peering.
+You will be redirected to a view with two columns in a table, each column representing one side of a BGP peering.
+To create a BGP Peering, You have to complete information for both sides.
+
+![BGP Peering Form](images_manual/add_external_peering.png "BGP Peering Form")
+
+To create an external BGP Peering, for the Provider's side You have to fill in the information with the Provider's ASN and IP Address of the provider's endpoint.
+
+### Peering detail view
+
+Once the BGP Peering is created, you could review its details.
+
+![BGP Peering Details](images_manual/external_peering_created.png "BGP Peering Details")