graphiant.naas.graphiant_edge_services module – Configure edge services (DHCP, DNS, LLDP, DPI, LWS password)

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

New in graphiant.naas 26.5.0

Synopsis

• Configures Edge Services on the Edge/Gateway devices PUT /v1/devices/{device_id}/config: LAN segment dhcpSubnets, device localWebServerPassword, LAN interface lldpEnabled, edge dns mode (DNSModeStatic, DNSModeCloudflare, or DNSModeDynamic), and edge trafficPolicy.dpiApplications.

• Edge/Gateway only; core devices are rejected. Complements graphiant.naas.graphiant_global_config (syslog, IPFIX, SNMP) and graphiant.naas.graphiant_ntp (NTP). For unstructured payloads, graphiant.naas.graphiant_device_config can push raw edge branch JSON instead.

• Supply edge_services_config_file for a bulk edge_services list, and/or device with service fields to run a single device or override one device from the file.

• DHCP subnet keys in the API combine interface name and ipPrefix with a hyphen. Remove a subnet with state: absent in YAML (sends subnet: null). Static lease IPs must not fall inside configured DHCP ranges.

• Local web server passwords are hashed in GET responses; the module cannot compare plaintext to the portal. Diff output uses localWebServerPasswordConfigured booleans. Without localWebServerPasswordForce (default), localWebServerPassword is pushed only when the device has none configured; if a hash already exists, LWS is skipped. Set localWebServerPasswordForce to push when one is already configured. If localWebServerPasswordForce is true, localWebServerPassword must be supplied via YAML, vault_devices_lws_password (matching device key), or module parameters—the task fails otherwise. Clear force after a successful rotate (portal hash makes force non-idempotent). Supply passwords via localWebServerPassword in YAML (dev/local; do not commit secrets), vault_devices_lws_password (Ansible Vault; recommended), or module parameters. Precedence is YAML localWebServerPassword over vault_devices_lws_password. Config files support self-contained Jinja2 (for loops, set blocks); playbook/Ansible variables are not available at render time—pass vault dicts via the module parameter after include_vars.

• Idempotent merge for DNS mode, LLDP, and DHCP fields. Configure-only (no deconfigure operation).

• Module parameters use camelCase names aligned with the API (dhcpSubnets, dpiApplications, localWebServerPassword, localWebServerPasswordForce). Legacy snake_case aliases (dhcp_subnets, dpi_applications, etc.) are still accepted.

• DPI applications are pushed under edge.trafficPolicy.dpiApplications as a map keyed by application name. The map key is used as application.name in the PUT payload when name is omitted in YAML. Each value wraps application fields (ipProtocol, networks, ports, and optional references to sourceNetworkList, destinationNetworkList, sourcePortList, destinationPortList names defined under edge.trafficPolicy via graphiant.naas.graphiant_prefix_port_list). Use state: absent on a map entry to remove an application (sends application: null). Idempotency compares non-null fields present in YAML; omitted keys and explicit null are ignored (the portal does not clear nested match fields via null). Portal-only fields such as description are ignored unless set in YAML.

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 in the task result message. Choices: false ← (default) true
device string	Portal device hostname for get_device_id. With edge_services_config_file, optional overrides. Required when edge_services_config_file is omitted (single-device mode).
dhcpSubnets aliases: dhcp_subnets list / elements=dictionary	List of DHCP subnet entries (segment, interface, ipPrefix, subnet dict, optional state). Each segment must match an existing LAN segment on the device. interface and ipPrefix must match a configured LAN interface or subinterface. The task fails with a clear error otherwise. API subnet key is interface name and ipPrefix joined with a hyphen. Use state: absent to remove a subnet.
dns dictionary	Edge DNS settings. mode is DNSModeStatic, DNSModeCloudflare, or DNSModeDynamic. For static mode, set static with primaryIpv4, primaryIpv6, secondaryIpv4, secondaryIpv6.
dpiApplications aliases: dpi_applications dictionary	Map of DPI application name to application settings (API edge.trafficPolicy.dpiApplications). The map key is the application name in the API; application.name in YAML is optional and defaults to the key. If set, it must match the key. ipProtocol (any, icmp, tcp, or udp) and optional network/port fields or list name references are required per app. Use state: absent on an entry to remove an application. Legacy list-of-application YAML is also accepted and normalized to this map shape.
edge_services_config_file aliases: edge_services_file string	Path to YAML (optional if device is set with at least one service field). Relative paths resolve using the collection config path (see GRAPHIANT_CONFIGS_PATH). Top-level key edge_services is a list of dicts; each dict has one key, the portal device name.
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
lldp dictionary	Map of LAN interface names to lldpEnabled boolean. The task fails if a key names a WAN/circuit interface or an interface that does not exist on the device.
localWebServerPassword aliases: local_web_server_password string	Plaintext local web server password (API localWebServerPassword). At least 8 characters with upper, lower, and digit. Use no_log in playbooks. May be set in edge_services_config_file YAML per device (without vault) or as a module parameter. Takes precedence over vault_devices_lws_password for the same device. Without localWebServerPasswordForce, applied only when the device has no password yet; skipped silently if one is already configured (portal hash).
localWebServerPasswordForce aliases: local_web_server_password_force boolean	When true, push localWebServerPassword even if the device already has a configured password. When false or omitted (default), password is pushed only on first set. Requires localWebServerPassword in YAML, vault_devices_lws_password, or module parameters; the task fails if force is true and no password is available for that device. Choices: false ← (default) true
operation string	Only configure is supported. Choices: "configure" ← (default)
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	Only present is supported. Choices: "present" ← (default)
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_devices_lws_password dictionary	Map of portal device hostname to local web server password (from Ansible Vault via include_vars). Keys must match device names in edge_services_config_file or device. Injected as localWebServerPassword before apply when YAML does not already set localWebServerPassword for that device. YAML may set localWebServerPasswordForce. Do not reference Ansible/playbook variables inside the config file; pass this dict as this module parameter after include_vars. Self-contained Jinja2 in the config file is supported. Default: {}

Attributes

Attribute	Support	Description
check_mode	Support: full In check mode, no configuration is pushed; 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 by the underlying client.	Supports check mode similarly to other device config modules.
diff_mode	Support: full When the playbook runs with --diff and a device branch would change, the module returns a diff dictionary (before / after strings). LWS password values are not shown; use localWebServerPasswordConfigured. Structured entries are also in details.diff_plan.	Supports Ansible’s --diff for pending edge branch updates.

Notes

Note

• Configuration files support Jinja2 templating syntax for dynamic value substitution.

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

See Also

See also

graphiant.naas.graphiant_device_system

Configure device name, region, and site.

graphiant.naas.graphiant_interfaces

Configure LAN/WAN interfaces before DHCP subnets and LLDP.

graphiant.naas.graphiant_global_config

Global syslog, IPFIX, and SNMP (not edge DHCP/DNS/LLDP/LWS).

graphiant.naas.graphiant_ntp

NTP configuration (separate from edge DNS mode).

graphiant.naas.graphiant_device_config

Push raw device JSON when structured modules are not used.

Examples

- name: Configure edge services from YAML
  graphiant.naas.graphiant_edge_services:
    operation: configure
    edge_services_config_file: "sample_edge_services.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: edge_result

- name: Enable LLDP on LAN interfaces for one device
  graphiant.naas.graphiant_edge_services:
    operation: configure
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-10-joule-sj-dr"
    lldp:
      GigabitEthernet4/0/0: true
      GigabitEthernet8/0/0: true
    detailed_logs: true

- name: Set Cloudflare DNS mode
  graphiant.naas.graphiant_edge_services:
    operation: configure
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-10-joule-sj-dr"
    dns:
      mode: DNSModeCloudflare

- name: Add DHCP pool on a LAN segment
  graphiant.naas.graphiant_edge_services:
    operation: configure
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-2-sdktest"
    dhcpSubnets:
      - segment: lan-1-test
        interface: GigabitEthernet8/0/0
        ipPrefix: "10.2.11.0/24"
        state: present
        subnet:
          name: Edge-2-lan-1-test-DHCP
          ipGateway: "10.2.11.1"
          ipRangesV2:
            ipRange:
              - start: "10.2.11.100"
                end: "10.2.11.200"
    state: present

- name: Configure edge services from YAML with vault LWS passwords
# Load vault_secrets.yml with M(ansible.builtin.include_vars) first (see edge_services_management.yml).
- name: Apply edge services (LWS passwords from vault_devices_lws_password)
  graphiant.naas.graphiant_edge_services:
    operation: configure
    edge_services_config_file: "sample_edge_services.yaml"
    vault_devices_lws_password: "{{ vault_devices_lws_password | default({}) }}"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  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 configuration was pushed to at least one device. Returned: always
configured_devices list / elements=string	Device names where an update was applied. Returned: when supported
details dictionary	Structured payload from the manager (device lists, diff_plan, etc.). Returned: always
diff dictionary	Ansible --diff payload when changes would be applied. Returned: when playbook uses --diff and at least one device branch would change
edge_services_config_file string	Path to the YAML file used, if any. Returned: when provided
msg string	Human-readable result (includes detailed logs when enabled). Returned: always
operation string	Operation performed (always configure). Returned: always
skipped_devices list / elements=string	Device names skipped because state already matched. Returned: when supported

Authors

• Graphiant Team (@graphiant)

Collection links

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