PeerGroupAddressFamily and PeerEndpointAddressFamily

docs/admin/release_notes/version_0.9.md

@@ -0,0 +1,17 @@
+# v0.9 Release Notes
+
+## Release Overview
+
+This version introduces `PeerGroupAddressFamily` and `PeerEndpointAddressFamily` data models to provide for more granular configuration modeling.
+
+!!! warning
+    This version **removes** the `import_policy`, `export_policy`, and `multipath` attributes from the `PeerGroupTemplate`, `PeerGroup`, and `PeerEndpoint` models, as these are generally address-family-specific configuration attributes and are modeled as such now. No data migration is provided at this time (as there is no way to identify **which** AFI-SAFI any existing policy/multipath configs should be migrated to), and upgrading to this version will therefore necessarily result in data loss if you had previously populated these model fields. Back up your configuration or record this data in some other format before upgrading if appropriate.
+
+### Added
+
+- [#26](https://github.com/nautobot/nautobot-plugin-bgp-models/issues/26) - Adds `PeerGroupAddressFamily` and `PeerEndpointAddressFamily` data models.
+- [#132](https://github.com/nautobot/nautobot-plugin-bgp-models/pull/132) - Adds `extra_attributes` support to the `AddressFamily` model.
+
+### Removed
+
+- [#132](https://github.com/nautobot/nautobot-plugin-bgp-models/pull/132) - Removes `import_policy`, `export_policy`, and `multipath` attributes from `PeerGroupTemplate`, `PeerGroup`, and `PeerEndpoint` models. Use the equivalent fields on `PeerGroupAddressFamily` and `PeerEndpointAddressFamily` instead.

docs/dev/models.md

@@ -3,13 +3,15 @@
 This plugin adds the following data models to Nautobot:
 
 - AutonomousSystem
+- PeeringRole
 - BGPRoutingInstance
-- PeerEndpoint
-- PeerGroup
-- PeerGroupTemplate
 - AddressFamily
+- PeerGroupTemplate
+- PeerGroup
+- PeerGroupAddressFamily
+- PeerEndpoint
+- PeerEndpointAddressFamily
 - Peering
-- PeeringRole
 
 A key motivation behind this design is the idea that the Source of Truth should take a network-wide view of the BGP configuration rather than a per-device view. This especially applies to the data models for autonomous systems (ASNs), BGP peerings, and network-wide templates (Peer Groups).
 
@@ -31,6 +33,10 @@ The data models introduced by the BGP plugin support the following Nautobot feat
 
 This model represents a network-wide description of a BGP autonomous system (AS). It has fields including the actual AS number (ASN), a description field, foreign key (FK) to a Nautobot `Provider` object, and a FK to a Nautobot `Status` object.
 
+### PeeringRole
+
+This model operates similarly to Nautobot’s `Status` and `Tag` models, in that instances of this model describe various valid values for the `Role` field used by `PeerGroup` and `Peering` records. Similar to those models, this model has fields including a unique name, unique slug, and HTML color code.
+
 ### BGPRoutingInstance
 
 This model represents a device specific BGP process. It has a mandatory FK to a Nautobot `Device`, mandatory FK to a `AutonomousSystem` and following fields:
@@ -53,14 +59,24 @@ Example of the extra attributes:
 
 Extra Attributes are available for following models:
 
-- `PeerEndpoint`
-- `PeerGroup`
-- `PeerGroupTemplate`
 - `BGPRoutingInstance`
+- `AddressFamily`
+- `PeerGroupTemplate`
+- `PeerGroup`
+- `PeerGroupAddressFamily`
+- `PeerEndpoint`
+- `PeerEndpointAddressFamily`
 
-### PeeringRole
+### AddressFamily
 
-This model operates similarly to Nautobot’s `Status` and `Tag` models, in that instances of this model describe various valid values for the `Role` field used by `PeerGroup` and `Peering` records. Similar to those models, this model has fields including a unique name, unique slug, and HTML color code.
+This model represents configuration of a BGP address-family (AFI-SAFI). AddressFamily aims to represent a device specific Address Family instance.
+
+It has a locally unique AFI (address family identifier) field, optional VRF field (FK to Nautobot `VRF`) and following fields:
+
+- Import Policy (optional, string)
+- Export Policy (optional, string)
+
+(*) The network-wide modeling of AddressFamilies will be implemented in the future with `AddressFamilyTemplate` model similar to the `PeerGroupTemplate`.
 
 ### PeerGroupTemplate
 
@@ -70,8 +86,6 @@ This model represents a network-wide configuration for `PeerGroups`. `PeerGroupT
 - Role (optional, FK to `PeeringRole`)
 - Description (string)
 - Enabled (bool)
-- Import Policy (optional, string)
-- Export Policy (optional, string)
 - Secret (optional, FK to Nautobot `Secret`)
 - Extra Attributes (optional, JSON)
 
@@ -85,9 +99,15 @@ This model represents a common configuration for a group of functionally related
 - Role (optional, FK to `PeeringRole`)
 - Description (string)
 - Enabled (bool)
+- Secret (optional, FK to Nautobot `Secret`)
+- Extra Attributes (optional, JSON)
+
+### PeerGroupAddressFamily
+
+This model represents address-family-specific configuration of a PeerGroup. It has a mandatory FK to a `PeerGroup` and a mandatory `afi_safi` field, and additional fields including
+
 - Import Policy (optional, string)
 - Export Policy (optional, string)
-- Secret (optional, FK to Nautobot `Secret`)
 - Extra Attributes (optional, JSON)
 
 ### PeerEndpoint
@@ -107,13 +127,9 @@ Note that in the case of an external peering (connection with an ISP or Transit
 - Role (optional, FK to `PeeringRole`)
 - Description (string)
 - Enabled (bool)
-- Import Policy (optional, string)
-- Export Policy (optional, string)
 - Secret (optional, FK to Nautobot `Secret`)
 - Extra Attributes (optional, JSON)
 
-The device-specific `PeerEndpoint` custom modeling will be implemented in the future with `PeerEndpointContext` and `PeerGroupContext` models.
-
 #### PeerEndpoint Local-IP
 
 To ease the data presentation and consumption, `PeerEndpoint` provides a property named `local_ip`.
@@ -127,16 +143,13 @@ As Source-IP and Source-Interface could be defined at multiple inheritance level
 3. `PeerEndpoint`'s `source_interface` attribute (if exists)
 4. `PeerGroup`'s `source_interface` attribute (if exists)
 
-### AddressFamily
-
-This model represents configuration of a BGP address-family (AFI-SAFI). AddressFamily aims to represent a device specific Address Family instance.
+### PeerEndpointAddressFamily
 
-It has a locally unique AFI (address family identifier) field, optional VRF field (FK to Nautobot `VRF`) and following fields:
+This model represents address-family-specific configuration of a device's PeerEndpoint. It has a mandatory FK to a `PeerEndpoint` and a mandatory `afi_safi` field, and additional keys including:
 
 - Import Policy (optional, string)
 - Export Policy (optional, string)
-
-(*) The network-wide modeling of AddressFamilies will be implemented in the future with `AddressFamilyTemplate` model similar to the `PeerGroupTemplate`.
+- Extra Attributes (optional, JSON)
 
 ### Peering
 
@@ -201,3 +214,18 @@ Following is the complete documentation of the field inheritance hierarchy. Mode
 | export_policy | PeerGroupTemplate |
 | import_policy | PeerGroupTemplate |
 | role | PeerGroupTemplate |
+
+**PeerGroupAddressFamily**:
+
+| **Attribute** | **Inheritance from model** |
+| ------------- | -------------------------- |
+| extra_attributes | AddressFamily (same `afi_safi` only) |
+
+**PeerEndpointAddressFamily**:
+
+| **Attribute** | **Inheritance from model** |
+| ------------- | -------------------------- |
+| extra_attributes | PeerGroupAddressFamily (same `afi_safi` only) → AddressFamily (same `afi_safi` only) |
+| import_policy | PeerGroupAddressFamily (same `afi_safi` only) |
+| export_policy | PeerGroupAddressFamily (same `afi_safi` only) |
+| multipath     | PeerGroupAddressFamily (same `afi_safi` only) |

docs/user/app_overview.md

@@ -11,13 +11,15 @@ An app for [Nautobot](https://github.com/nautobot/nautobot), extending the core
 
 This application adds the following new data models into Nautobot:
 
-- **BGP Routing Instance**: device-specific BGP process
 - **Autonomous System**: network-wide description of a BGP autonomous system (AS)
+- **Peering Role**: describes the valid options for PeerGroup, PeerGroupTemplate, and/or Peering roles
+- **BGP Routing Instance**: device-specific BGP process
+- **Address Family**: device-specific configuration of a BGP address family (AFI-SAFI) with an optional VRF
 - **Peer Group Template**: network-wide template for Peer Group objects
 - **Peer Group**: device-specific configuration for a group of functionally related BGP peers
-- **Address Family**: device-specific configuration of a BGP address family (AFI-SAFI)
+- **Peer Group Address Family**: peer-group-specific configuration of a BGP address-family (AFI-SAFI)
 - **Peering and Peer Endpoints**: A BGP Peering is represented by a Peering object and two endpoints, each representing the configuration of one side of the BGP peering. A Peer Endpoint must be associated with a BGP Routing Instance.
-- **Peering Role**: describes the valid options for PeerGroup, PeerGroupTemplate, and/or Peering roles
+- **Peer Endpoint Address Family**: peer-specific configuration of a BGP address-family (AFI-SAFI)
 
 With these new models, it's now possible to populate the Source of Truth (SoT) with any BGP peerings, internal or external, regardless of whether both endpoints are fully defined in the Source of Truth.
 
@@ -37,13 +39,15 @@ Network Admins who need to model their BGP internal and external peerings inside
 This plugin adds the following data models to Nautobot:
 
 - AutonomousSystem
+- PeeringRole
 - BGPRoutingInstance
-- PeerEndpoint
-- PeerGroup
-- PeerGroupTemplate
 - AddressFamily
+- PeerGroupTemplate
+- PeerGroup
+- PeerGroupAddressFamily
+- PeerEndpoint
+- PeerEndpointAddressFamily
 - Peering
-- PeeringRole
 
 The data models introduced by the BGP plugin support the following Nautobot features:
 

docs/user/cisco_use_case.md

@@ -22,13 +22,16 @@ query ($device_id: ID!) {
             peer_groups {
                 name
                 extra_attributes
-                template {
+                peergroup_template {
                     autonomous_system {
                         asn
                     }
+                    extra_attributes
+                }
+                address_families {
+                    afi_safi
                     import_policy
                     export_policy
-                    extra_attributes
                 }
             }
             endpoints {
@@ -85,23 +88,29 @@ An example data returned from Nautobot is presented below.
             {
               "name": "EDGE-to-LEAF",
               "extra_attributes": null,
-              "template": {
+              "peergroup_template": {
                 "autonomous_system": null,
-                "import_policy": "BGP-LEAF-IN",
-                "export_policy": "BGP-LEAF-OUT",
-                "extra_attributes": {
-                  "next-hop-self": true,
-                  "send-community": true
-                },
+                "extra_attributes": {},
                 "role": {
                   "slug": "peer"
                 }
-              }
+              },
+              "address_families": [
+                {
+                  "afi_safi": "IPV4_UNICAST",
+                  "import_policy": "BGP-LEAF-IN",
+                  "export_policy": "BGP-LEAF-OUT",
+                  "extra_attributes": {
+                    "next-hop-self": true,
+                    "send-community": true,
+                  }
+                }
+              ]
             },
             {
               "name": "EDGE-to-TRANSIT",
               "extra_attributes": null,
-              "template": {
+              "peergroup_template": {
                 "autonomous_system": null,
                 "import_policy": "BGP-TRANSIT-IN",
                 "export_policy": "BGP-TRANSIT-OUT",
@@ -111,7 +120,15 @@ An example data returned from Nautobot is presented below.
                 "role": {
                   "slug": "customer"
                 }
-              }
+              },
+              "address_families": [
+                {
+                  "afi_safi": "IPV4_UNICAST",
+                  "import_policy": "BGP-TRANSIT-IN",
+                  "export_policy": "BGP-TRANSIT-OUT",
+                  "extra_attributes": {}
+                }
+              ]
             }
           ],
           "endpoints": [
@@ -318,16 +335,16 @@ Following snippet represents an example Cisco BGP Configuration Template:
 router bgp {{ data.device.bgp_routing_instances.0.autonomous_system.asn }}
 {%- for peer_group in data.device.bgp_routing_instances.0.peer_groups %}
  neighbor {{ peer_group.name }} peer-group
- neighbor {{ peer_group.name }} route-map {{ peer_group.template.import_policy }} in
- neighbor {{ peer_group.name }} route-map {{ peer_group.template.export_policy }} out
-{%- if "next-hop-self" in peer_group.template.extra_attributes %}
+ neighbor {{ peer_group.name }} route-map {{ peer_group.address_families.0.import_policy }} in
+ neighbor {{ peer_group.name }} route-map {{ peer_group.address_families.0.export_policy }} out
+{%- if "next-hop-self" in peer_group.address_families.0.extra_attributes %}
  neighbor {{ peer_group.name }} next-hop-self
 {%- endif %}
-{%- if "send-community" in peer_group.template.extra_attributes %}
+{%- if "send-community" in peer_group.address_families.0.extra_attributes %}
  neighbor {{ peer_group.name }} send-community
 {%- endif %}
-{%- if "ttl_security_hops" in peer_group.template.extra_attributes %}
- neighbor {{ peer_group.name }} ttl-security hops {{ peer_group.template.extra_attributes.ttl_security_hops }}
+{%- if "ttl_security_hops" in peer_group.peergroup_template.extra_attributes %}
+ neighbor {{ peer_group.name }} ttl-security hops {{ peer_group.peergroup_template.extra_attributes.ttl_security_hops }}
 {%- endif %}
 {%- endfor %}
 !
@@ -352,7 +369,7 @@ router bgp {{ data.device.bgp_routing_instances.0.autonomous_system.asn }}
 
 ## Rendering Cisco Jinja2 BGP Configuration Template with the data retrieved from GraphQL
 
-Following snippet represents an example Cisco BGP Renderer Configuration:
+Following snippet represents an example Cisco BGP rendered configuration:
 
 ```text
 !

docs/user/juniper_use_case.md

@@ -22,10 +22,17 @@ query ($device_id: ID!) {
             peer_groups {
                 name
                 extra_attributes
-                template {
+                peergroup_template {
                     autonomous_system {
                         asn
                     }
+                    role {
+                        slug
+                    }
+                    extra_attributes
+                }
+                address_families {
+                    afi_safi
                     import_policy
                     export_policy
                     extra_attributes
@@ -85,33 +92,45 @@ An example data returned from Nautobot is presented below.
             {
               "name": "EDGE-to-LEAF",
               "extra_attributes": null,
-              "template": {
+              "peergroup_template": {
                 "autonomous_system": null,
-                "import_policy": "BGP-LEAF-IN",
-                "export_policy": "BGP-LEAF-OUT",
-                "extra_attributes": {
-                  "next-hop-self": true,
-                  "send-community": true
-                },
                 "role": {
                   "slug": "peer"
                 }
-              }
+                "extra_attributes": {}
+              },
+              "address_families": [
+                {
+                  "afi_safi": "IPV4_UNICAST",
+                  "import_policy": "BGP-LEAF-IN",
+                  "export_policy": "BGP-LEAF-OUT",
+                  "extra_attributes": {
+                    "next-hop-self": true,
+                    "send-community": true
+                  }
+                }
+              ]
             },
             {
               "name": "EDGE-to-TRANSIT",
               "extra_attributes": null,
-              "template": {
+              "peergroup_template": {
                 "autonomous_system": null,
-                "import_policy": "BGP-TRANSIT-IN",
-                "export_policy": "BGP-TRANSIT-OUT",
                 "extra_attributes": {
                   "ttl_security_hops": 1
                 },
                 "role": {
                   "slug": "customer"
                 }
-              }
+              },
+              "address_families": [
+                {
+                  "afi_safi": "IPV4_UNICAST",
+                  "import_policy": "BGP-TRANSIT-IN",
+                  "export_policy": "BGP-TRANSIT-OUT",
+                  "extra_attributes": {}
+                }
+              ]
             }
           ],
           "endpoints": [
@@ -319,14 +338,14 @@ set routing-options autonomous-system {{ data.device.bgp_routing_instances.0.aut
 
 # Configure Groups
 {%- for peer_group in data.device.bgp_routing_instances.0.peer_groups %}
-{%- if peer_group.template.role.slug == "peer" %}
+{%- if peer_group.peergroup_template.role.slug == "peer" %}
 set protocols bgp group {{ peer_group.name }} type internal
 {%- endif %}
-{%- if peer_group.template.role.slug == "customer" %}
+{%- if peer_group.peergroup_template.role.slug == "customer" %}
 set protocols bgp group {{ peer_group.name }} type external
 {%- endif %}
-set protocols bgp group {{ peer_group.name }} import {{ peer_group.template.import_policy }}
-set protocols bgp group {{ peer_group.name }} export {{ peer_group.template.export_policy }}
+set protocols bgp group {{ peer_group.name }} import {{ peer_group.address_families.0.import_policy }}
+set protocols bgp group {{ peer_group.name }} export {{ peer_group.address_families.0.export_policy }}
 {%- endfor %}
 
 # Configure Peers