graphiant.naas.graphiant_interfaces module – Manage Graphiant interfaces and circuits

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_interfaces.

New in graphiant.naas 25.12.0

Synopsis

• This module provides comprehensive interface and circuit management capabilities for Graphiant Edge devices.

• Supports LAN interface configuration and deconfiguration for subinterfaces.

• Enables WAN interface and circuit management with static routes.

• Supports circuit-only operations for updating static routes without reconfiguring interfaces.

• All operations use Jinja2 templates for consistent configuration deployment.

• 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.
circuit_config_file string	Path to the circuit configuration YAML file. Required for WAN and circuit operations (configure_wan_circuits_interfaces, deconfigure_wan_circuits_interfaces, configure_circuits, deconfigure_circuits). Optional for LAN-only 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 circuit definitions with static routes and circuit configurations.
circuits_only boolean	If true, perform a circuits-only deconfigure (static route removal) and skip interface changes. Supported for deconfigure_interfaces and deconfigure_wan_circuits_interfaces. When true, static routes are removed from referenced circuits, but interfaces remain configured. Choices: false ← (default) true
detailed_logs boolean	Enable detailed logging output for troubleshooting and monitoring. When enabled, provides comprehensive logs of all interface 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”
interface_config_file string / required	Path to the interface 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 interface definitions with device names, interface names, and subinterface configurations.
operation string	The specific interface operation to perform. configure_interfaces: Configure all interfaces (LAN and WAN) in one operation. deconfigure_interfaces: Deconfigure all interfaces. Removes WAN static routes first (when circuit config provided), then resets parent interface to default LAN and deletes subinterfaces. configure_lan_interfaces: Configure LAN interfaces (subinterfaces) only. deconfigure_lan_interfaces: Deconfigure LAN interfaces (subinterfaces) only. configure_wan_circuits_interfaces: Configure WAN circuits and interfaces together. deconfigure_wan_circuits_interfaces: Deconfigure WAN circuits and interfaces together (two-stage: static routes first, then interface reset). configure_circuits: Configure circuits only. Can be called separately after interface is configured. deconfigure_circuits: Deconfigure circuits only. Removes static routes if any. Choices: "configure_interfaces" "deconfigure_interfaces" "configure_lan_interfaces" "deconfigure_lan_interfaces" "configure_wan_circuits_interfaces" "deconfigure_wan_circuits_interfaces" "configure_circuits" "deconfigure_circuits"
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 interfaces. present: Maps to configure_interfaces when operation not specified. absent: Maps to deconfigure_interfaces when operation not specified. 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.

Attributes

Attribute	Support	Description
check_mode	Support: full When run with --check, the module logs the exact payloads that would be pushed with a [check_mode] prefix so you can see what configuration would be applied.	Supports check mode. In check mode, no configuration is pushed to the devices but payloads that would be pushed are logged with [check_mode].
diff_mode	Support: full	Supports diff mode. When run with --diff, a per-device before/after of the interface and circuit payload that would be pushed is returned.

Notes

Note

• Interface Operations:

• - LAN interfaces: Configure/deconfigure subinterfaces for LAN connectivity.

• - WAN interfaces: Configure/deconfigure WAN circuits and interfaces together.

• - Circuits only: Update circuit configurations including static routes without touching interfaces.

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

• The module automatically resolves device names to IDs and validates configurations.

• Prerequisite: LAN segments referenced by lan: on an interface or subinterface must already exist in the enterprise. Create them first (e.g. lan_segments_management.yml --tag configure). Configure operations validate referenced LAN segment names against live portal state and fail fast (listing the available segments) when one is missing.

• Both configure and deconfigure operations are field-level idempotent and safe to run repeatedly: each device’s desired config is compared against live state and devices already in the desired state are skipped (reported under skipped_devices), so changed is accurate.

• Check mode (--check): No config is pushed; payloads that would be pushed are logged with [check_mode].

• Per-entry state: absent — LAN only. Within configure_interfaces or configure_lan_interfaces you can remove an individual LAN interface or LAN subinterface without a full deconfigure run. On a LAN subinterface: only vlan is required alongside state: absent; the subinterface is deleted while the parent and all other entries are configured normally. On a LAN main interface: only name is required; a non-default LAN attachment is reset to the enterprise default LAN (its subinterfaces are left untouched — remove them individually with per-sub state: absent). WAN interfaces, WAN subinterfaces, and circuits are never affected by state: absent — they are skipped, including within configure_wan_circuits_interfaces. All are idempotent — if the LAN interface/subinterface is already absent the device is skipped.

• LAN segment move: When an interface or subinterface is moved to a different LAN segment, the API requires a two-step push (segment-only then full config). The module does this automatically; in check mode both payloads are shown.

• WAN static-route cleanup (important):

• - Detaching a WAN interface from a circuit may be treated by the backend as a circuit removal.

• If that circuit still has static routes, the operation can fail with:

• ‘error removing circuit “<name>”. Remove static routes first.’

• deconfigure_wan_circuits_interfaces and deconfigure_interfaces automatically remove static routes first (when a circuit config is provided).

• - Use deconfigure_circuits when you only want to remove static routes and keep interfaces/circuits attached.

See Also

See also

graphiant.naas.graphiant_global_config

Configure global objects (LAN segments, VPN profiles) that may be referenced in interface configurations.

graphiant.naas.graphiant_bgp

Configure BGP peering after interfaces are configured

Examples

- name: Configure all interfaces (LAN and WAN)
  graphiant.naas.graphiant_interfaces:
    operation: configure_interfaces
    interface_config_file: "sample_interface_config.yaml"
    circuit_config_file: "sample_circuit_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: configure_result

- name: Configure LAN interfaces only
  graphiant.naas.graphiant_interfaces:
    operation: configure_lan_interfaces
    interface_config_file: "sample_interface_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

- name: Configure WAN circuits and interfaces
  graphiant.naas.graphiant_interfaces:
    operation: configure_wan_circuits_interfaces
    interface_config_file: "sample_interface_config.yaml"
    circuit_config_file: "sample_circuit_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

- name: Configure circuits only (update static routes)
  graphiant.naas.graphiant_interfaces:
    operation: configure_circuits
    interface_config_file: "sample_interface_config.yaml"
    circuit_config_file: "sample_circuit_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

- name: Deconfigure circuits (remove static routes)
  graphiant.naas.graphiant_interfaces:
    operation: deconfigure_circuits
    interface_config_file: "sample_interface_config.yaml"
    circuit_config_file: "sample_circuit_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

- name: Deconfigure WAN circuits and interfaces
  graphiant.naas.graphiant_interfaces:
    operation: deconfigure_wan_circuits_interfaces
    interface_config_file: "sample_interface_config.yaml"
    circuit_config_file: "sample_circuit_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

- name: Deconfigure all interfaces
  graphiant.naas.graphiant_interfaces:
    operation: deconfigure_interfaces
    interface_config_file: "sample_interface_config.yaml"
    circuit_config_file: "sample_circuit_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

- name: Deconfigure interfaces using state parameter
  graphiant.naas.graphiant_interfaces:
    state: absent
    interface_config_file: "sample_interface_config.yaml"
    circuit_config_file: "sample_circuit_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

# Remove a single subinterface (VLAN 19) while keeping everything else configured.
# In the config file, mark the subinterface with state: absent:
#
#   interfaces:
#     - edge-1:
#       - name: GigabitEthernet7/0/0
#         lan: lan-1-test
#         ipv4: 10.1.11.1/24
#         subinterfaces:
#           - vlan: 18
#             lan: lan-7-test
#             ipv4: 10.1.17.1/24   # kept — configured normally
#           - vlan: 19
#             state: absent         # removed — sends {"interface": null} for VLAN 19
#
- name: Remove a specific subinterface (idempotent — skipped if already absent)
  graphiant.naas.graphiant_interfaces:
    operation: configure_interfaces
    interface_config_file: "sample_interface_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

# Remove a single main interface while configuring everything else normally.
# In the config file, mark the interface with state: absent — only name is required:
#
#   interfaces:
#     - edge-1:
#       - name: GigabitEthernet5/0/0
#         state: absent              # resets LAN attachment to enterprise default; subinterfaces untouched
#       - name: GigabitEthernet7/0/0
#         lan: lan-1-test            # configured normally
#         ipv4: 10.1.11.1/24
#
- name: Remove a specific interface (idempotent — skipped if already at default state)
  graphiant.naas.graphiant_interfaces:
    operation: configure_interfaces
    interface_config_file: "sample_interface_config.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
changed boolean	Whether the operation made changes to the system. Configure operations typically return true because the configuration is pushed via PUT. Deconfigure operations may return false when nothing needs to be removed (idempotent). Returned: always Sample: true
circuit_config_file string	The circuit configuration file used for the operation. Only returned when circuit_config_file was provided. Returned: when applicable Sample: "sample_circuit_config.yaml"
circuits_only boolean	Whether only circuits were affected in the operation. Returned: always Sample: false
interface_config_file string	The interface configuration file used for the operation. Returned: always Sample: "sample_interface_config.yaml"
msg string	Result message from the operation, including detailed logs when detailed_logs is enabled. Returned: always Sample: "Successfully configured all interfaces"
operation string	The operation that was performed. One of configure_interfaces, deconfigure_interfaces, configure_lan_interfaces, deconfigure_lan_interfaces, configure_wan_circuits_interfaces, deconfigure_wan_circuits_interfaces, configure_circuits, or deconfigure_circuits. Returned: always Sample: "configure_interfaces"

Authors

• Graphiant Team (@graphiant)

Collection links

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