graphiant.naas.graphiant_prefix_port_list module – Manage Graphiant prefix and port lists (edge.trafficPolicy.networkLists, edge.trafficPolicy.portLists)

Note

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

New in graphiant.naas 26.5.0

Synopsis

• Create or delete prefix and port lists under edge traffic policy (edge.trafficPolicy.networkLists, edge.trafficPolicy.portLists).

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

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

Requirements

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

• python >= 3.7

• graphiant-sdk >= 26.5.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.
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. create_prefix_port_lists builds full prefix and port list objects. delete_prefix_port_lists deletes listed prefix and port lists by setting networkLists=null and portLists=null. create_prefix_lists builds full prefix list objects. delete_prefix_lists deletes listed prefix lists by setting networkLists=null. create_port_lists builds full port list objects. delete_port_lists deletes listed port lists by setting portLists=null. Choices: "create_prefix_port_lists" "delete_prefix_port_lists" "create_prefix_lists" "delete_prefix_lists" "create_port_lists" "delete_port_lists"
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.
prefix_port_list_config_file string / required	Path to the prefix and port list YAML file. Can be an absolute path or relative to the configured config_path. Expected top-level key is networkLists and portLists (list of devices).
state string	Desired state for prefix and port lists. present maps to create_prefix_port_lists; absent maps to delete_prefix_port_lists, create_prefix_lists, delete_prefix_lists, create_port_lists, delete_port_lists if operation not set. 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 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.	Supports Ansible’s --diff for pending traffic policy list updates.

Notes

Note

• Prefix and Port List Operations:

• - Create_prefix_port_lists: Create prefix and port lists listed in the config.

• - Delete_prefix_port_lists: Delete prefix and port lists listed in the config.

• - Create_prefix_lists: Create prefix lists listed in the config.

• - Delete_prefix_lists: Delete prefix lists listed in the config.

• - Create_port_lists: Create port lists listed in the config.

• - Delete_port_lists: Delete port lists listed in the config.

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

• The module automatically resolves device names to IDs.

• YAML schema uses CamelCase keys (for example: networkLists, portLists).

• Create idempotency: compares intended prefix and port lists to existing device state; skips push when already matched (changed=false).

• On create_* operations, each list entry may use state: absent to remove that name only (sends list: null) while other entries in the same file are created or updated. Default is state: present.

• Delete deletes only the prefix and port lists listed in the YAML.

• Delete payload uses networkLists: null and portLists: null; this module preserves nulls in the final payload pushed to the API.

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

Examples

- name: Configure prefix and port lists
  graphiant.naas.graphiant_prefix_port_list:
    operation: create_prefix_port_lists
    prefix_port_list_config_file: "sample_prefix_and_port_list.yaml"
    detailed_logs: true
    state: present
  register: create_prefix_port_lists_result
  no_log: true

- name: Display result message (includes detailed logs)
  ansible.builtin.debug:
    msg: "{{ prefix_port_list_result.msg }}"

- name: Deconfigure prefix and port lists (deletes only prefixes and port lists listed in YAML)
  graphiant.naas.graphiant_prefix_port_list:
    operation: delete_prefix_port_lists
    prefix_port_list_config_file: "sample_prefix_and_port_list.yaml"
    detailed_logs: true
    state: absent
  register: delete_prefix_port_lists_result
  no_log: true

- name: Create prefix lists
  graphiant.naas.graphiant_prefix_port_list:
    operation: create_prefix_lists
    prefix_port_list_config_file: "sample_prefix_and_port_list.yaml"
    detailed_logs: true
    state: present
  register: create_prefix_lists_result
  no_log: true

- name: Display create prefix lists result message (includes detailed logs)
  ansible.builtin.debug:
    msg: "{{ create_prefix_lists_result.msg }}"
  no_log: true

- name: Delete prefix lists
  graphiant.naas.graphiant_prefix_port_list:
    operation: delete_prefix_lists
    prefix_port_list_config_file: "sample_prefix_and_port_list.yaml"
    detailed_logs: true
    state: absent
  register: delete_prefix_lists_result
  no_log: true

- name: Display delete prefix lists result message (includes detailed logs)
  ansible.builtin.debug:
    msg: "{{ delete_prefix_lists_result.msg }}"
  no_log: true

- name: Create port lists
  graphiant.naas.graphiant_prefix_port_list:
    operation: create_port_lists
    prefix_port_list_config_file: "sample_prefix_and_port_list.yaml"
    detailed_logs: true
    state: present
  register: create_port_lists_result
  no_log: true

- name: Display create port lists result message (includes detailed logs)
  ansible.builtin.debug:
    msg: "{{ create_port_lists_result.msg }}"
  no_log: true

- name: Delete port lists
  graphiant.naas.graphiant_prefix_port_list:
    operation: delete_port_lists
    prefix_port_list_config_file: "sample_prefix_and_port_list.yaml"
    detailed_logs: true
    state: absent
  register: delete_port_lists_result
  no_log: true

- name: Display delete port lists result message (includes detailed logs)
  ansible.builtin.debug:
    msg: "{{ delete_port_lists_result.msg }}"
  no_log: true

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. true when config would be pushed to at least one device; false when intended state already matched. In check mode (--check), no configuration is pushed, but changed reflects whether changes would be made. Returned: always Sample: false
configured_devices list / elements=string	Device names where configuration was pushed (when changed=true). Returned: when supported Sample: ["edge-1-sdktest"]
details dictionary	Raw manager result details (includes diff_plan, configured/skipped device lists). Returned: when supported
diff dictionary	Ansible diff output when the playbook runs with --diff and at least one device would change. Returned: when diff mode is enabled and details.diff_plan is non-empty
msg string	Result message from the operation, including detailed logs when detailed_logs is enabled. Returned: always Sample: "Prefix and port lists already match desired state; no changes needed"
operation string	The operation performed. Returned: always Sample: "create_prefix_port_lists"
prefix_port_list_config_file string	The prefix and port list config file used for the operation. Returned: always Sample: "sample_prefix_and_port_list.yaml"
skipped_devices list / elements=string	Device names that were skipped because desired state already matched. Returned: when supported Sample: ["edge-1-sdktest"]

Authors

• Graphiant Team (@graphiant)

Collection links

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