graphiant.naas.graphiant_nat_policy module – Manage device NAT 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_nat_policy.

New in graphiant.naas 26.7.0

Synopsis

• Configure or delete device-level NAT policy rulesets under edge.natPolicy.natRulesets.

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

• Reads a structured YAML config file and/or inline module params and builds the raw device-config payload.

• 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/params by setting ruleset: null per ruleset key.

• Under configure, set state: absent on a ruleset entry to delete that ruleset (sends ruleset: null), or set state: absent on an individual rule to delete only that rule (sends rule: null). Omitted state means present.

• Under attach_to_lan_segments, set state: absent on a segment entry to detach that segment from its current NAT ruleset. Equivalent to running operation=detach_from_lan_segments for that individual segment.

• Safety check: deleting a ruleset that is still referenced by LAN segments raises an error. Detach the affected segments first using operation=detach_from_lan_segments or operation=attach_to_lan_segments with state: absent on those segments, then delete the 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
device string	Portal device hostname for single-device or loop execution. When combined with nat_policy_config_file, overrides that device’s natRulesets and/or segments in the file with the values supplied via natRulesets / segments. Required when nat_policy_config_file is omitted.
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
nat_policy_config_file aliases: nat_policy_file string	Path to the NAT policy YAML file. Can be an absolute path or relative to the configured config_path. Expected top-level key is natPolicyObject (list of devices). Each device may define natRulesets and/or segments in the same file. configure/deconfigure use natRulesets; attach/detach operations use segments. Optional when device is set with at least natRulesets or segments.
natRulesets aliases: nat_rulesets dictionary	NAT ruleset definitions for the device named by device (configure and deconfigure operations). Dict keyed by ruleset name. Each value is either a ruleset body dict (containing rules list/dict and optional name) or {state: absent} to delete that ruleset. Within a ruleset body, individual rules in the rules list may include state: absent to delete only that rule. Deleting a ruleset that is still attached to LAN segments raises an error. Detach the segments first (detach_from_lan_segments or attach_to_lan_segments with state: absent), then delete. Ignored for attach_to_lan_segments and detach_from_lan_segments operations. When combined with nat_policy_config_file and device, overrides that device’s ruleset map.
operation string	Specific operation to perform. configure creates/updates rulesets listed under natRulesets. Use state: absent on a ruleset entry or an individual rule to delete only that object. Pair with attach_to_lan_segments (or the playbook configure tag) to attach rulesets to LAN segments. deconfigure deletes all listed rulesets by setting ruleset: null. A ruleset still attached to LAN segments raises an error — use detach_from_lan_segments or attach_to_lan_segments with state: absent to detach first. Pair with the playbook deconfigure tag to clear segment references before deleting. attach_to_lan_segments sets edge.segments.<segment>.natRuleset.ruleset from the segments map. Use state: absent on a segment entry to detach that segment from its current ruleset. 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.
segments dictionary	LAN segment to NAT ruleset mapping for the device named by device (attach_to_lan_segments and detach_from_lan_segments operations). Dict keyed by segment name. For attach_to_lan_segments, each value may be one of: a ruleset name string, a dict with natRuleset or ruleset keys, or {state: absent} to detach that segment from its current ruleset reference. For detach_from_lan_segments, values are not used — all listed segments are detached. When combined with nat_policy_config_file and device, overrides that device’s segments map.
state string	Desired state for NAT policy rulesets. present maps to configure when operation is omitted. absent maps to deconfigure when operation is omitted. 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. The segment attachment safety check and absent no-op pruning are skipped in check mode so that a full deconfigure workflow (detach + deconfigure) can be previewed with --check --diff without running the real detach step first.	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 NAT policy updates.

Notes

Note

• One YAML file may define both natRulesets and segments. configure/deconfigure read natRulesets only; attach_to_lan_segments/detach_from_lan_segments read segments only. Run both steps for a full NAT policy lifecycle, or use the sample playbook tags configure and deconfigure.

• nat_policy_config_file and device are mutually complementary: either may be omitted, but at least one must be provided. When both are set, device overrides that device’s natRulesets and segments in the file with natRulesets / segments from module params.

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

• 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. The segment attachment safety check and absent no-op pruning are skipped in check mode so that a full deconfigure workflow can be previewed with --check --diff without running the real detach step first.

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

• Supported NAT rule types are OneToOne and PAT. Each rule requires seq, type, originalSrcIpPrefix, and translatedSrcIpPrefix. name, originalDstIpPrefix, translatedDstIpPrefix, and advertisePreNatPrefixes are optional. advertisePreNatPrefixes defaults to false.

• Deconfigure workflow ordering is enforced: a ruleset still attached to LAN segments cannot be deleted. Detach first using detach_from_lan_segments or attach_to_lan_segments with state: absent, then deconfigure.

Examples

# =============================================================================
# CONFIGURE WORKFLOW: create/update rulesets, then attach to LAN segments
# =============================================================================

# Step 1 — configure NAT rulesets from a YAML file.
- name: Configure device-level NAT policy rulesets
  graphiant.naas.graphiant_nat_policy:
    operation: configure
    nat_policy_config_file: "sample_device_nat_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

# Step 2 — attach rulesets to LAN segments (reads 'segments' key from the same YAML file).
- name: Attach NAT ruleset to LAN segments
  graphiant.naas.graphiant_nat_policy:
    operation: attach_to_lan_segments
    nat_policy_config_file: "sample_device_nat_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

# =============================================================================
# DECONFIGURE WORKFLOW: detach from LAN segments first, then delete rulesets
#
# Order matters: deleting a ruleset that is still attached to LAN segments
# raises an error. Always detach before deconfiguring.
# =============================================================================

# Step 1 — detach each listed segment from its ruleset reference.
- name: Detach NAT ruleset from LAN segments
  graphiant.naas.graphiant_nat_policy:
    operation: detach_from_lan_segments
    nat_policy_config_file: "sample_device_nat_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

# Step 2 — delete listed rulesets (raises error if any are still attached).
- name: Deconfigure device-level NAT policy rulesets
  graphiant.naas.graphiant_nat_policy:
    operation: deconfigure
    nat_policy_config_file: "sample_device_nat_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

# =============================================================================
# STATE: ABSENT — delete a single ruleset or rule without deconfigure
# =============================================================================

# Delete one ruleset (state: absent on the ruleset entry under configure).
# Detach the segment first if it still references this ruleset.
- name: Delete a single NAT ruleset via state absent
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "edge-1-sdktest"
    natRulesets:
      NAT-Ruleset-1:
        state: absent

# Delete one rule within a ruleset (state: absent on the rule entry).
- name: Delete rule seq 20 from NAT-Ruleset-1
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "edge-1-sdktest"
    natRulesets:
      NAT-Ruleset-1:
        rules:
          - seq: 20
            state: absent

# =============================================================================
# STATE: ABSENT ON SEGMENTS — detach a segment via attach_to_lan_segments
# =============================================================================

# Detach a single segment from its ruleset using state: absent on that segment.
# Equivalent to detach_from_lan_segments for only that segment.
- name: Detach LAN-Segment-1 from its NAT ruleset (state absent)
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: attach_to_lan_segments
    device: "edge-1-sdktest"
    segments:
      LAN-Segment-1:
        state: absent
      LAN-Segment-2: NAT-Ruleset-2   # attach/update another segment in the same call

# =============================================================================
# SINGLE DEVICE — inline module params (no YAML file required)
# =============================================================================

- name: Configure NAT rulesets on a single device
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "edge-1-sdktest"
    natRulesets:
      NAT-Ruleset-1:
        rules:
          - seq: 10
            type: OneToOne
            name: host-mapping
            originalSrcIpPrefix: 192.168.1.0/24
            translatedSrcIpPrefix: 10.0.1.0/24
          - seq: 20
            type: PAT
            originalSrcIpPrefix: 10.1.0.0/16
            translatedSrcIpPrefix: 203.0.113.1/32
            advertisePreNatPrefixes: true

- name: Attach NAT ruleset to LAN segments (module params)
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: attach_to_lan_segments
    device: "edge-1-sdktest"
    segments:
      LAN-Segment-1: NAT-Ruleset-1

- name: Detach NAT ruleset from LAN segments (module params)
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: detach_from_lan_segments
    device: "edge-1-sdktest"
    segments:
      LAN-Segment-1: NAT-Ruleset-1

- name: Deconfigure NAT rulesets on a single device (module params)
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: deconfigure
    device: "edge-1-sdktest"
    natRulesets:
      NAT-Ruleset-1: {}

# =============================================================================
# LOOP — configure multiple devices
# =============================================================================

- name: Configure NAT rulesets on multiple devices
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    device: "{{ item.device }}"
    natRulesets: "{{ item.natRulesets }}"
  loop:
    - device: edge-1-sdktest
      natRulesets:
        NAT-Ruleset-1:
          rules:
            - seq: 10
              type: OneToOne
              originalSrcIpPrefix: 192.168.1.0/24
              translatedSrcIpPrefix: 10.0.1.0/24
    - device: edge-2-sdktest
      natRulesets:
        NAT-Ruleset-2:
          rules:
            - seq: 10
              type: PAT
              originalSrcIpPrefix: 10.1.0.0/16
              translatedSrcIpPrefix: 203.0.113.1/32

# =============================================================================
# OVERRIDE — combine YAML file with inline params for one device
# =============================================================================

- name: Override NAT ruleset for one device from file
  graphiant.naas.graphiant_nat_policy:
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    operation: configure
    nat_policy_config_file: "sample_device_nat_policies.yaml"
    device: "edge-1-sdktest"
    natRulesets:
      NAT-Ruleset-Override:
        rules:
          - seq: 10
            type: OneToOne
            originalSrcIpPrefix: 172.16.0.0/24
            translatedSrcIpPrefix: 10.0.2.0/24

# =============================================================================
# CHECK / DIFF MODE — preview changes without pushing
# =============================================================================

# Dry-run: reads live device state, skips writes, sets changed=true when changes
# would be made. The segment safety check and absent no-op pruning are skipped in
# check mode, so a full deconfigure workflow can be previewed without a prior detach.
- name: Preview NAT policy configure (dry run)
  graphiant.naas.graphiant_nat_policy:
    operation: configure
    nat_policy_config_file: "sample_device_nat_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  check_mode: true
  register: nat_policy_preview

# Diff mode: shows before/after per device and branch.
# details.diff_plan[].before/after.natRulesets.<name>.rules.<seq> — changed rules only.
# details.diff_plan[].before/after.segments.<name> — segment ruleset reference.
- name: Preview NAT policy rule changes (diff mode)
  graphiant.naas.graphiant_nat_policy:
    operation: configure
    nat_policy_config_file: "sample_device_nat_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  diff: true
  register: nat_policy_diff

Return Values

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

Key	Description
changed boolean	Whether the operation pushed (or would push in check mode) config to at least one device. In check mode (--check), no configuration is pushed, but changed is true when changes would be made. Returned: always
configured_devices list / elements=string	Device names where configuration was pushed (or would be pushed in check mode). Returned: always
details dictionary	Raw manager result dict containing diff_plan, configured_devices, and skipped_devices. diff_plan is a list of per-device change entries. Each entry has device (hostname), branch (e.g. edge.natPolicy.natRulesets or edge.segments), and normalized before / after snapshots showing the state before and after the intended change. For ruleset branches, only changed rules appear under rules; ruleset-level metadata changes appear under _meta. For segment branches, each changed segment appears under segments with its before/after ruleset reference. Returned: always
diff dictionary	Ansible diff output when the playbook runs with --diff and at least one device would change. Built from details.diff_plan as formatted JSON before / after strings per device and branch. before shows the current device state; after shows the intended state. Returned: when diff mode is enabled and details.diff_plan is non-empty
msg string	Human-readable result message. Returned: always
nat_policy_config_file string	The NAT policy config file used for the operation, if one was provided. Returned: when provided
operation string	The operation that was performed. Returned: always
skipped_devices list / elements=string	Device names skipped because the desired state already matched the device. Returned: always

Authors

• Graphiant Team (@graphiant)

Collection links

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