graphiant.naas.graphiant_bgp module – Manage Graphiant BGP peering, routing policies, and route aggregations

Note

This module is part of the graphiant.naas collection (version 26.10.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install graphiant.naas. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: graphiant.naas.graphiant_bgp.

New in graphiant.naas 25.12.0

Synopsis

• This module provides comprehensive BGP peering and routing policy management for Graphiant Edge devices.

• Supports BGP peering neighbor configuration and deconfiguration.

• Enables attachment and detachment of global BGP routing policies (filters) to BGP peers.

• Supports BGP route aggregation configuration per LAN segment.

• Neighbors and aggregations are independent — a segment can define either or both.

• Supports enabling/disabling eBGP multipath per LAN segment via a segment ebgpMultipath field.

• Configuration files support Jinja2 templating for dynamic generation.

Requirements

The below requirements are needed on the host that executes this module.

• python >= 3.7

• graphiant-sdk >= 26.10.0

Parameters

Parameter	Comments
access_token string	Bearer token for API authentication (for example, from graphiant login, which opens a browser for sign-in (SSO or non-SSO) and retrieves the token). If not passed as a module argument, the collection reads GRAPHIANT_ACCESS_TOKEN (set after graphiant login when you source ~/.graphiant/env.sh). When a bearer token is present (module argument or environment), it takes precedence over username and password. If no valid token is available, the module authenticates with username and password when both are supplied.
bgp_config_file string / required	Path to the BGP configuration YAML file. Required for all operations. Can be an absolute path or relative path. Relative paths are resolved using the configured config_path. Configuration files support Jinja2 templating syntax for dynamic generation. File must contain either BGP peering neighbor definitions or route aggregation definitions, or both.
detailed_logs boolean	Enable detailed logging output for troubleshooting and monitoring. When enabled, provides comprehensive logs of all BGP operations. Logs are captured and included in the result_msg for display using ansible.builtin.debug module. Choices: false ← (default) true
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
operation string	The specific BGP operation to perform. configure: Configure BGP peering neighbors and/or route aggregations; attach global BGP routing policies. deconfigure: Remove BGP peering neighbors and/or route aggregations. Policies are automatically detached. detach_policies: Detach global BGP routing policies from BGP peers without removing peers or aggregations. Choices: "configure" "deconfigure" "detach_policies"
password string	Graphiant portal password for authentication. Required for password-based login when no valid bearer token is available from access_token or GRAPHIANT_ACCESS_TOKEN.
state string	The desired state of the BGP configuration. present: Maps to configure when operation not specified. absent: Maps to deconfigure when operation not specified. Removes all neighbors and aggregations listed in the config file. Choices: "present" ← (default) "absent"
username string	Graphiant portal username for authentication. Required for password-based login when no valid bearer token is available from access_token or GRAPHIANT_ACCESS_TOKEN.
vault_bgp_peering_md5_passwords dictionary	Dict of device name to BGP neighbor address to MD5 password (configure only). Fills a neighbor’s MD5 password from Ansible Vault only when md5Password is null/absent in the config file; a non-null value in the config always wins. Pass from playbook vars loaded from an encrypted vault_secrets.yml; secrets stay in memory. Keys must match the device name and the neighbor remoteIpv4Address in the BGP config. Default: {}

Attributes

Attribute	Support	Description
check_mode	Support: full The module fetches each device’s current BGP state and compares it against the desired configuration. In check mode the same comparison runs, but the config push is skipped; changed reflects whether a push would have occurred. Devices already in the desired state are reported under skipped_devices and do not count as changes.	Full check mode support with per-device state comparison.
diff_mode	Support: full	Supports diff mode; shows per-device before/after BGP state when run with --diff.

Notes

Note

• BGP Operations:

• - Configure (state: present): Create BGP peering neighbors, route aggregations, and attach routing policies.

• - Deconfigure (state: absent): Remove BGP peering neighbors and route aggregations. Policies are detached.

• - Detach Policies: Detach global BGP routing policies from BGP peers without removing the peers or aggregations.

• Per-entry removal: within configure, an individual neighbor or aggregation marked with

• state: absent in the config file is removed while all other entries are configured normally,

• so a single peer/aggregation can be deleted without a full deconfigure.

• Per-policy detach: within configure, set a neighbor filter field

• (ipv4InboundFilter, ipv4OutboundFilter, ipv6InboundFilter, ipv6OutboundFilter)

• to absent to detach just that routing policy while keeping the neighbor and its other settings.

• Omitting a filter field leaves the currently attached policy unchanged.

• Config-file fields use camelCase (e.g. remoteIpv4Address, peerAs, lanSegment, bgpAggregations).

• The original snake_case field names (remote_ipv4_address, peer_as, …) are still accepted as

• aliases for backward compatibility; when both forms are given the camelCase value wins.

• Configuration files support Jinja2 templating syntax for dynamic configuration generation.

• The module automatically resolves device names, site names, and policy names to IDs.

• All operations are idempotent and safe to run multiple times.

• Global BGP filters must be created using graphiant.naas.graphiant_global_config module

• before attaching to BGP peers.

• BGP Aggregation config file fields per segment entry:

• bgpAggregations: list of aggregation entries, each with:

• prefix (required): The network prefix to aggregate, e.g. 1.1.1.0/27.

• asSet (optional, default false): Include AS set information in the aggregated route.

• summaryOnly (optional, default false): Suppress advertisement of more-specific routes.

• state (optional): Set to ‘absent’ to remove just this aggregation under configure.

• Neighbor entries likewise accept state: absent to remove a single peer under configure.

See Also

See also

graphiant.naas.graphiant_interfaces

Configure interfaces before setting up BGP peering

graphiant.naas.graphiant_global_config

Configure global BGP filters (routing policies) that can be attached to BGP peers

Examples

- name: Configure BGP peering, route aggregations and attach policies
  graphiant.naas.graphiant_bgp:
    operation: configure
    bgp_config_file: "sample_bgp_peering.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: bgp_result

# Load MD5 passwords from an encrypted vault file (secrets stay in memory only).
- name: Load BGP MD5 passwords from Ansible Vault
  ansible.builtin.include_vars: "configs/vault_secrets.yml"
  no_log: true

- name: Configure BGP peering with neighbor MD5 passwords from Ansible Vault
  graphiant.naas.graphiant_bgp:
    operation: configure
    bgp_config_file: "sample_bgp_peering.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    # Leave md5Password null/absent in the config; vault fills it per device -> neighbor address.
    vault_bgp_peering_md5_passwords: "{{ vault_bgp_peering_md5_passwords | default({}) }}"
  register: bgp_result

# Remove a single neighbor/aggregation without a full deconfigure by marking
# the entry with `state: absent` in the config file, e.g.:
#   bgpPeering:
#     - edge-1-sdktest:
#         segments:
#           - lanSegment: lan-7-test
#             neighbors:
#               - remoteIpv4Address: 10.1.17.11   # kept, configured normally
#                 peerAs: 60011
#               - remoteIpv4Address: 10.1.17.12   # removed
#                 peerAs: 60012
#                 state: absent
- name: Configure BGP peering (per-entry state:absent removes just that neighbor/aggregation)
  graphiant.naas.graphiant_bgp:
    operation: configure
    bgp_config_file: "sample_bgp_peering.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

- name: Detach policies from BGP peers
  graphiant.naas.graphiant_bgp:
    operation: detach_policies
    bgp_config_file: "sample_bgp_peering.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

- name: Deconfigure BGP peering and aggregations
  graphiant.naas.graphiant_bgp:
    operation: deconfigure
    bgp_config_file: "sample_bgp_peering.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

- name: Configure BGP peering using state parameter
  graphiant.naas.graphiant_bgp:
    state: present
    bgp_config_file: "sample_bgp_peering.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

- name: Deconfigure BGP peering and aggregations using state parameter
  graphiant.naas.graphiant_bgp:
    state: absent
    bgp_config_file: "sample_bgp_peering.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
bgp_config_file string	The BGP configuration file used for the operation. Returned: always Sample: "sample_bgp_peering.yaml"
changed boolean	Whether the operation made changes to the system. true only when at least one device required a config push. false when every device already matched the desired state (idempotent no-op). Returned: always Sample: true
configured_devices list / elements=string	Names of devices whose BGP configuration was pushed (differed from desired state). Returned: always Sample: ["edge-1-sdktest"]
details dictionary	Manager result, including the per-device diff_plan with before/after BGP state. Returned: always
msg string	Result message from the operation, including detailed logs when detailed_logs is enabled. Returned: always Sample: "Successfully configured BGP peering and attached policies"
operation string	The operation that was performed. One of configure, deconfigure, or detach_policies. Returned: always Sample: "configure"
skipped_devices list / elements=string	Names of devices skipped because they already matched the desired state. Returned: always Sample: ["edge-2-sdktest"]

Authors

• Graphiant Team (@graphiant)

Collection links

• Issue Tracker
• Homepage
• Repository (Sources)
• Report an issue
• View source code
• Communication