Skip to content
Documentation

Managing BGP Sessions and Link Aggregations

BGP sessions and link aggregations are standalone resources managed at the fabric level. They define how the physical links between network devices within a fabric are grouped and how BGP peering operates on those links.

Overview

Section titled “Overview”

In previous versions, BGP numbering, link configuration and MLAG pair settings were properties on individual fabric links. These have now been extracted into dedicated resources:

  • Link Aggregations group multiple physical links into a single logical bundle (LAG, MLAG or peer-link)
  • BGP Sessions define how BGP peering is configured on a link or link aggregation

This separation gives administrators finer-grained control and makes the relationship between links, aggregations and BGP sessions explicit.

Network Fabric
  ├── Link 1 ─┐
  ├── Link 2 ─┼── Link Aggregation (LAG/MLAG/peer-link) ──► BGP Session
  ├── Link 3 ─┘
  └── Link 4 ──────────────────────────────────────────────► BGP Session

A BGP session can be associated with either a single link or a link aggregation, but not both.

Section titled “Link Aggregations”

Link aggregations combine multiple fabric links into a single logical connection for increased bandwidth and redundancy.

Aggregation types

Section titled “Aggregation types”
TypeDescription
lagLink Aggregation Group — bundles multiple links between the same pair of switches into a single logical link using LACP.
mlagMulti-chassis LAG — bundles links across two switches that form a switch pair, providing redundancy across chassis. Equivalent to VLT, VPC or MCLAG depending on the vendor.
peer-linkThe inter-switch link between two switches in an MLAG/switch pair. This carries control-plane traffic and data-plane traffic for orphan ports.

Status lifecycle

Section titled “Status lifecycle”
StatusDescription
draftThe aggregation has been created but not yet deployed.
activeThe aggregation is deployed and operational.
deletedThe aggregation has been removed.
Section titled “Creating a link aggregation”

When creating a link aggregation, you specify the type and the list of fabric link IDs to include.

Using the API

Section titled “Using the API”
Terminal window
curl -X POST "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/link-aggregations" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mlag",
    "linkIds": [1, 2]
  }'

The system will validate that the provided links are compatible with the requested aggregation type.

Section titled “Updating a link aggregation”

You can change the member links by providing an updated list of link IDs. The type cannot be changed after creation.

Terminal window
curl -X PATCH "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/link-aggregations/{linkAggregationId}" \
  -H "Content-Type: application/json" \
  -d '{
    "linkIds": [1, 2, 3]
  }'
Section titled “Listing link aggregations”
Terminal window
# List all link aggregations for a fabric
curl "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/link-aggregations"


# Filter by type
curl "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/link-aggregations?filter.type=\$eq:mlag"


# Filter by status
curl "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/link-aggregations?filter.status=\$eq:active"
Section titled “Getting a specific link aggregation”
Terminal window
curl "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/link-aggregations/{linkAggregationId}"

The response includes the associated networkFabricLinks, networkFabricLinkConfigs (configuration change history) and bgpSession if one is attached.

Section titled “Deleting a link aggregation”

Remove any associated BGP session before deleting the link aggregation.

Terminal window
curl -X DELETE "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/link-aggregations/{linkAggregationId}"

BGP Sessions

Section titled “BGP Sessions”

BGP sessions control how BGP peering is configured on a fabric link or link aggregation.

BGP numbering modes

Section titled “BGP numbering modes”
ModeDescription
inheritedThe BGP numbering is inherited from the fabric or template defaults.
numberedThe session uses explicit IPv4/IPv6 addresses for peering. Each end of the link is assigned an IP from the fabric’s underlay subnet.
unnumberedThe session uses the interface’s link-local IPv6 address for peering. This simplifies configuration by avoiding the need for point-to-point IP assignment.
Section titled “BGP link configuration modes”
ModeDescription
disabledBGP is not configured on this link.
activeThe local device actively initiates the BGP session.
passiveThe local device waits for the remote side to initiate the session.

Creating a BGP session

Section titled “Creating a BGP session”

A BGP session must be associated with either a link or a link aggregation (provide one of linkId or linkAggregationId, not both).

Section titled “On a single link”
Terminal window
curl -X POST "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/bgp-sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "bgpNumbering": "unnumbered",
    "bgpLinkConfiguration": "active",
    "linkId": 1
  }'
Section titled “On a link aggregation”
Terminal window
curl -X POST "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/bgp-sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "bgpNumbering": "numbered",
    "bgpLinkConfiguration": "active",
    "linkAggregationId": 5
  }'

Listing BGP sessions

Section titled “Listing BGP sessions”
Terminal window
# List all BGP sessions in a fabric
curl "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/bgp-sessions"


# Filter by numbering type
curl "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/bgp-sessions?filter.bgpNumbering=\$eq:unnumbered"


# Filter by link configuration
curl "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/bgp-sessions?filter.bgpLinkConfiguration=\$eq:active"

Getting a specific BGP session

Section titled “Getting a specific BGP session”
Terminal window
curl "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/bgp-sessions/{bgpSessionId}"

The response includes the associated networkFabricLink and linkAggregation objects when present.

Deleting a BGP session

Section titled “Deleting a BGP session”
Terminal window
curl -X DELETE "https://<your-server>/api/v2/network-fabrics/{networkFabricId}/bgp-sessions/{bgpSessionId}"

Configuration templates

Section titled “Configuration templates”

BGP sessions and link aggregations are deployed to network devices using specialized configuration templates. These replace the previous generic network device configuration template.

  • BGP Session Configuration Templates — define the CLI commands pushed to switches when creating or deleting a BGP session. Templates are matched by driver, device position, remote device position, network type (underlay/overlay), MLAG pair, numbering and link configuration. See the API reference at /api/v2/network-device-bgp-session-configuration-templates.

  • Link Aggregation Configuration Templates — define the CLI commands pushed to switches when creating, deleting, adding or removing members from a link aggregation. Templates are matched by driver, aggregation type and action (create, delete, add-member, remove-member). See the API reference at /api/v2/network-device-link-aggregation-configuration-templates.

Both template types use base64-encoded preparation and configuration commands, similar to the previous network device configuration templates.

Example: setting up an MLAG with BGP

Section titled “Example: setting up an MLAG with BGP”

This example creates an MLAG between two spine-leaf links and configures a BGP session on it.

Prerequisites:

  • Fabric ID 1 with links 10 and 11 connecting a leaf switch pair to a spine switch

Step 1: Create the MLAG link aggregation

Terminal window
curl -X POST "https://<your-server>/api/v2/network-fabrics/1/link-aggregations" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mlag",
    "linkIds": [10, 11]
  }'

Note the returned id (e.g. 5).

Step 2: Create a BGP session on the MLAG

Terminal window
curl -X POST "https://<your-server>/api/v2/network-fabrics/1/bgp-sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "bgpNumbering": "unnumbered",
    "bgpLinkConfiguration": "active",
    "linkAggregationId": 5
  }'

Step 3: Verify

Terminal window
# Check the link aggregation and its associated BGP session
curl "https://<your-server>/api/v2/network-fabrics/1/link-aggregations/5"

The response should show the MLAG with both member links and the attached BGP session.

Section titled “Relationship to fabric links”

Fabric links now include references to their associated link aggregation and BGP session:

  • networkFabricLinkAggregationId — the link aggregation this link belongs to (if any)
  • linkAggregation — the full link aggregation object
  • bgpSession — the BGP session configured on this link (if any, and if the session is directly on the link rather than on an aggregation)
  • config — the link configuration object, which also references the link aggregation

When a link is part of a link aggregation, the BGP session is typically configured on the aggregation rather than on the individual link.

Section titled “Related topics”