graphiant.naas.graphiant_dhcp_relay module – Manage Graphiant DHCP relay on interfaces and subinterfaces

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

New in graphiant.naas 26.7.0

Synopsis

• Configures DHCP relay (IPv4 and/or IPv6) on main interfaces and VLAN subinterfaces via PUT /v1/devices/{device_id}/config under edge.interfaces.{name}.interface.ipv4.dhcp.dhcpRelay and the IPv6 equivalent.

• Supports configure and deconfigure operations. Deconfigure sets relayServers: [] for the address families listed in the config file (idempotent when relay is already removed).

• Configuration files support Jinja2 templating for dynamic generation.

• Configure idempotency: compares intended relay servers to existing device state per interface and address family; skips push when already matched (changed=false).

• Validates that each referenced main interface or VLAN subinterface exists on the device before pushing; fails with a list of known interfaces when not found.

• Mutual exclusion: an interface supports either DHCP relay or a DHCP subnet (server), not both. Configure fails with a clear error if the target interface already has a DHCP subnet configured. Remove the DHCP subnet first using graphiant.naas.graphiant_edge_services with state: absent before enabling DHCP relay on that interface.

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 output for troubleshooting and monitoring. Choices: false ← (default) true
device string	Portal device hostname for single-device or loop execution. When combined with dhcp_relay_config_file, overrides that device’s interface list in the file. Required when dhcp_relay_config_file is omitted.
dhcp_relay_config_file aliases: dhcp_relay_file string	Path to the DHCP relay configuration YAML file. Optional when device is set with at least name or interfaces. Can be an absolute path or relative path. Relative paths are resolved using the configured config_path. File must contain a dhcp_relay_config list; each entry maps a device name to a dict with an interfaces key (list of interface entries with name, vlan, dhcpRelayIpv4, dhcpRelayIpv6).
dhcpRelayIpv4 aliases: dhcp_relay_ipv4 list / elements=string	List of IPv4 DHCP relay server addresses for the interface named by name. Ignored when interfaces is set.
dhcpRelayIpv6 aliases: dhcp_relay_ipv6 list / elements=string	List of IPv6 DHCP relay server addresses for the interface named by name. Ignored when interfaces is set.
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
interfaces list / elements=dictionary	List of interface entries for multi-interface module-param mode. Each entry may contain name, vlan, dhcpRelayIpv4, and dhcpRelayIpv6. When set, takes precedence over name / vlan / dhcpRelayIpv4 / dhcpRelayIpv6.
name aliases: interface_name string	Interface name for single-interface module-param mode (e.g. GigabitEthernet4/0/0). Required when dhcp_relay_config_file is omitted and interfaces is not set.
operation string	The specific DHCP relay operation to perform. configure: Configure DHCP relay on interfaces and subinterfaces. deconfigure: Remove DHCP relay from interfaces and subinterfaces. Choices: "configure" "deconfigure"
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 DHCP relay configuration. present: Maps to configure when operation is not specified. absent: Maps to deconfigure when operation is 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.
vlan any	VLAN ID for subinterface relay. Omit for main interface. Used together with name in single-interface mode.

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 With --diff, the module shows per-device before/after relay server lists for interfaces that would change (under edge.interfaces).	Supports diff mode.

Notes

Note

• Check mode (--check): No config is pushed; payloads that would be pushed are logged with [check_mode]. changed reflects whether an apply would update at least one device.

• Interfaces must be configured first using graphiant.naas.graphiant_interfaces before applying DHCP relay.

• Multiple relay entries for the same parent interface (different VLAN subinterfaces) are merged into a single device PUT payload.

See Also

See also

graphiant.naas.graphiant_interfaces

Configure interfaces before setting up DHCP relay

Examples

# --- From YAML config file ---

- name: Configure DHCP relay on interfaces (from YAML)
  graphiant.naas.graphiant_dhcp_relay:
    operation: configure
    dhcp_relay_config_file: "sample_dhcp_relay_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

- name: Deconfigure DHCP relay from interfaces (from YAML)
  graphiant.naas.graphiant_dhcp_relay:
    operation: deconfigure
    dhcp_relay_config_file: "sample_dhcp_relay_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

# --- Single device, single interface from module parameters ---

- name: Configure DHCP relay on a single interface (module params)
  graphiant.naas.graphiant_dhcp_relay:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "edge-1-sdktest"
    name: "GigabitEthernet4/0/0"
    vlan: 1
    dhcpRelayIpv4:
      - 10.1.1.1
      - 10.2.1.1
    dhcpRelayIpv6:
      - 2001:10:1:1::1

- name: Deconfigure DHCP relay on a single interface (module params)
  graphiant.naas.graphiant_dhcp_relay:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: deconfigure
    device: "edge-1-sdktest"
    name: "GigabitEthernet4/0/0"
    vlan: 1
    dhcpRelayIpv4:
      - 10.1.1.1

# --- Single device, multiple interfaces from module parameters ---

- name: Configure DHCP relay on multiple interfaces (module params)
  graphiant.naas.graphiant_dhcp_relay:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "edge-1-sdktest"
    interfaces:
      - name: GigabitEthernet4/0/0
        vlan: 1
        dhcpRelayIpv4:
          - 10.1.1.1
          - 10.2.1.1
        dhcpRelayIpv6:
          - 2001:10:1:1::1
      - name: GigabitEthernet8/0/0
        dhcpRelayIpv4:
          - 10.1.11.1
          - 10.2.11.1

# --- Loop over multiple devices (one interface per iteration) ---

- name: Configure DHCP relay on multiple devices (loop)
  graphiant.naas.graphiant_dhcp_relay:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "{{ item.device }}"
    name: "{{ item.name }}"
    vlan: "{{ item.vlan | default(omit) }}"
    dhcpRelayIpv4: "{{ item.dhcpRelayIpv4 | default(omit) }}"
    dhcpRelayIpv6: "{{ item.dhcpRelayIpv6 | default(omit) }}"
  loop:
    - device: edge-1-sdktest
      name: GigabitEthernet4/0/0
      vlan: 1
      dhcpRelayIpv4: ["10.1.1.1", "10.2.1.1"]
      dhcpRelayIpv6: ["2001:10:1:1::1"]
    - device: edge-2-sdktest
      name: GigabitEthernet8/0/0
      dhcpRelayIpv4: ["10.1.11.1"]

# --- Override one device from a YAML file ---

- name: Override DHCP relay for one device from file
  graphiant.naas.graphiant_dhcp_relay:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    dhcp_relay_config_file: "sample_dhcp_relay_config.yaml"
    device: "edge-1-sdktest"
    name: "GigabitEthernet4/0/0"
    dhcpRelayIpv4:
      - 192.168.1.1

# --- Per-interface state: absent (remove all relay on one interface, configure others) ---

- name: Remove relay from one subinterface while configuring others
  graphiant.naas.graphiant_dhcp_relay:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "edge-3-sdktest"
    interfaces:
      - name: GigabitEthernet7/0/0
        dhcpRelayIpv4:
          - 10.2.1.2
      - name: GigabitEthernet8/0/0
        vlan: 30
        state: absent

# --- Per-AF state: absent (remove only IPv4 relay, keep IPv6) ---

- name: Remove IPv4 relay only, keep IPv6 on subinterface
  graphiant.naas.graphiant_dhcp_relay:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "edge-3-sdktest"
    interfaces:
      - name: GigabitEthernet8/0/0
        vlan: 30
        dhcpRelayIpv4:
          state: absent
        dhcpRelayIpv6:
          relayServers:
            - 2001:10:2:1::2

# --- Check / diff mode ---

- name: Preview DHCP relay changes (check + diff)
  graphiant.naas.graphiant_dhcp_relay:
    operation: configure
    dhcp_relay_config_file: "sample_dhcp_relay_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  check_mode: true
  diff: 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
configured_devices list / elements=string	Device names where configuration would be or was pushed. Returned: when supported
details dictionary	Raw manager result (includes diff_plan, configured/skipped device and interface lists). Returned: when supported
dhcp_relay_config_file string	The DHCP relay configuration file used for the operation, if provided. Returned: when provided
diff dictionary	Ansible --diff payload showing per-device before/after DHCP relay state. Returned: when playbook uses --diff and at least one device would be updated
msg string	Result message from the operation. Returned: always
operation string	The operation that was performed. Returned: always
skipped_devices list / elements=string	Device names where no DHCP relay changes were needed. Returned: when supported

Authors

• Graphiant Team (@graphiant)

Collection links

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