graphiant.naas.graphiant_traffic_policy module – Manage device traffic policy rulesets and LAN segment attachments

Note

This module is part of the graphiant.naas collection (version 26.7.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_traffic_policy.

New in graphiant.naas 26.5.0

Synopsis

• Configure or delete device-level traffic policy rulesets under edge.trafficPolicy.trafficRulesets.

• Attach or detach a named ruleset on LAN segments under edge.segments.<name>.trafficRuleset.ruleset.

• Reads a structured YAML config file and builds the raw device-config payload in Python.

• The configure workflow applies rulesets (operation=configure) and attaches them to LAN segments (operation=attach_to_lan_segments). The deconfigure workflow clears segment references (operation=detach_from_lan_segments) and deletes listed rulesets (operation=deconfigure).

• Configure is idempotent: compares intended rulesets to existing device state and skips push when already matched.

• Deconfigure deletes only the rulesets listed in the YAML by setting ruleset: null per ruleset key.

• Under configure, set state: absent on a ruleset or individual rule in YAML to delete only that object (sends ruleset: null or rule: null in the payload). Omitted state means present. This allows removing one rule without deconfiguring the whole ruleset.

• Attach/detach operations compare each listed segment’s ruleset reference to the device and skip when unchanged.

• With ansible-playbook --check, writes are skipped but changed reflects whether an apply would update at least one device. Use --diff to preview details.diff_plan and Ansible diff.

Requirements

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

• python >= 3.7

• graphiant-sdk >= 25.12.1

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.
detailed_logs boolean	Enable detailed logging. Choices: false ← (default) true
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
operation string	Specific operation to perform. configure creates/updates rulesets listed under trafficRulesets. Pair with attach_to_lan_segments (or the playbook configure tag) to attach rulesets to LAN segments. deconfigure deletes listed rulesets by setting ruleset=null. Pair with detach_from_lan_segments (or the playbook deconfigure tag) to clear segment references first. attach_to_lan_segments sets edge.segments.<segment>.trafficRuleset.ruleset from the YAML segments map. detach_from_lan_segments clears the ruleset reference on each segment listed under segments. Choices: "configure" "deconfigure" "attach_to_lan_segments" "detach_from_lan_segments"
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	Desired state for traffic policy rulesets. present maps to configure when operation is omitted. For a full apply, also run attach_to_lan_segments or use the sample playbook configure tag. absent maps to deconfigure when operation is omitted. For a full teardown, also run detach_from_lan_segments or use the sample playbook deconfigure tag. Choices: "present" ← (default) "absent"
traffic_policy_config_file string / required	Path to the traffic policy YAML file. Can be an absolute path or relative to the configured config_path. Expected top-level key is trafficPolicyObject (list of devices). Each device may define trafficRulesets and/or segments in the same file. configure/deconfigure use trafficRulesets; attach/detach operations use segments.
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 In check mode, no configuration is pushed to devices, but the module still reads current device state to determine whether changes would be made. Payloads that would be pushed are logged with a [check_mode] prefix.	Supports check mode.
diff_mode	Support: full When the playbook runs with --diff and a device would change, the module returns a diff dictionary (before / after strings). Structured entries are also in details.diff_plan. Ruleset diffs list only changed rules under rules (plus _meta when ruleset metadata changes).	Supports Ansible’s --diff for pending traffic policy updates.

Notes

Note

• One YAML file may define both trafficRulesets and segments. configure/deconfigure read trafficRulesets only; attach_to_lan_segments/detach_from_lan_segments read segments only. Run both steps for a full traffic policy lifecycle, or use the sample playbook tags configure and deconfigure, which run attach/detach together with ruleset configure/deconfigure.

• This module manages traffic policies directly on devices (device config API), not portal-only objects.

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

• Deconfigure payload uses ruleset: null per ruleset key; this module preserves nulls in the final payload pushed to the API.

• Check mode (--check) reads live device state, skips writes, sets changed from whether an apply would update at least one device, and logs would-be payloads with a [check_mode] prefix when detailed_logs is enabled.

• Diff mode (--diff) adds Ansible diff (before / after strings) and details.diff_plan. Ruleset entries list only changed rules under rules (plus _meta when ruleset metadata changes). Segment attach/detach diffs show per-segment ruleset references under segments.

Examples

# Configure workflow: rulesets, then attach to LAN segments (same YAML file).
- name: Configure device-level traffic policy rulesets
  graphiant.naas.graphiant_traffic_policy:
    operation: configure
    traffic_policy_config_file: "sample_device_traffic_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: traffic_policy_result
  no_log: true

- name: Attach traffic ruleset to LAN segments
  graphiant.naas.graphiant_traffic_policy:
    operation: attach_to_lan_segments
    traffic_policy_config_file: "sample_device_traffic_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

# Deconfigure workflow: detach from LAN segments, then delete listed rulesets.
- name: Detach traffic ruleset from LAN segments
  graphiant.naas.graphiant_traffic_policy:
    operation: detach_from_lan_segments
    traffic_policy_config_file: "sample_device_traffic_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

- name: Deconfigure device-level traffic policy rulesets
  graphiant.naas.graphiant_traffic_policy:
    operation: deconfigure
    traffic_policy_config_file: "sample_device_traffic_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

# Preview pending changes without pushing (check mode)
- name: Preview traffic policy configure (dry run)
  graphiant.naas.graphiant_traffic_policy:
    operation: configure
    traffic_policy_config_file: "sample_device_traffic_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  check_mode: true
  register: traffic_policy_preview

# Preview per-rule diffs (run playbook with --diff or set diff: true on the task)
- name: Preview traffic policy rule changes
  graphiant.naas.graphiant_traffic_policy:
    operation: configure
    traffic_policy_config_file: "sample_device_traffic_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  diff: true
  register: traffic_policy_diff
  # details.diff_plan[].before/after.trafficRulesets.<name>.rules.<seq> — changed rules only

Return Values

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

Key	Description
changed boolean	Whether the operation would push config to at least one device. In check mode (--check), no configuration is pushed, but changed reflects whether changes would be made. Returned: always
configured_devices list / elements=string	Device names where configuration was pushed (when changed=true). Returned: when supported
details dictionary	Raw manager result details (includes diff_plan, configured/skipped device lists). Each diff_plan entry has device, branch (for example edge.trafficPolicy.trafficRulesets or edge.segments), and normalized before / after snapshots. Ruleset branches list only changed rules under rules; ruleset metadata changes appear under _meta. Returned: when supported
diff dictionary	Ansible diff output when the playbook runs with --diff and at least one device would change. Built from details.diff_plan as JSON before / after strings per device and branch. Returned: when diff mode is enabled and details.diff_plan is non-empty
msg string	Result message (includes detailed logs when enabled). Returned: always
operation string	The operation performed. Returned: always
skipped_devices list / elements=string	Device names that were skipped because desired state already matched. Returned: when supported
traffic_policy_config_file string	The traffic policy config file used for the operation. Returned: always

Authors

• Graphiant Team (@graphiant)

Collection links

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