graphiant.naas.graphiant_device_system module – Configure device name, region, and site (Edge or Core)

Note

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

New in graphiant.naas 26.4.0

Synopsis

• Sets name, regionName, and site on the edge or core object for PUT /v1/devices/{device_id}/config, matching https://github.com/Graphiant-Inc/graphiant-sdk-python/blob/main/docs/V1DevicesDeviceIdConfigPutRequest.md.

• YAML and module options use the same keys as the API branch payload (except optional device_type, which selects the edge vs core branch and is not sent in the request body).

• After GET /v1/devices/{id}, the module maps portal role to the config branch (core → core, cpe → edge) when device_type is omitted. If device_type is set, it must match that mapping.

• Supply system_config_file for a bulk device_system list, and/or device with name / regionName / site to run a single device or to override one device from the file.

• Only keys you set are merged onto current device state; omitted keys are left unchanged.

• Validates portal site exists when site.name is set.

• Idempotent when the merged payload already matches the device. Current state is read from GET /v1/devices/{id} using hostname as name, regionOverride.name when set else region.name as regionName, and site.name as site, aligned with the portal device object.

• Omit site entirely to leave the portal site unchanged. A YAML site key with an empty value or without name is treated as unspecified (not a request to clear site).

• If a device has no site in the portal and your desired config also omits site, a config push is not attempted, because the API can reject the update. The module fails the task, and skipped_no_site lists the affected hostnames. No other device in the same play is updated in that run (aborted) until you assign a site in the portal or set site in YAML.

Requirements

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

• python >= 3.7

• graphiant-sdk >= 26.4.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 name for get_device_id. With system_config_file, optional overrides for this device. Required when system_config_file is omitted (single-device mode).
device_type string	Selects the edge or core branch of PUT .../config. Not sent in the API body. Optional. If omitted, the branch is taken from the device’s portal role on GET /v1/devices/{id} (core for core, cpe for edge/CPE). If set, it must match that inferred branch. Choices: "edge" "core"
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
name string	Device hostname (API edge.name / core.name).
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.
regionName string	Device’s region name (API regionName).
site dictionary	Site object (API site), e.g. {name: "MySite"}. Must exist in the portal when set.
state string	Only present is supported. Choices: "present" ← (default)
system_config_file aliases: device_system_file string	Path to YAML (optional if device is set with at least one of name, regionName, site). Relative paths resolve using the collection config path (see GRAPHIANT_CONFIGS_PATH). Top-level key device_system is a list of dicts; each dict has one key, the portal device name.
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; the module still reads current device state to determine whether changes would be made. changed is true when at least one device would be updated, unless a device hits the no-site error (task fails, changed false). 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). Structured entries are also in details.diff_plan.	Supports Ansible’s --diff for pending edge/core branch updates.

Notes

Note

• Deconfigure is not supported; apply desired values with operation=configure.

• 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, unless a device fails the no-site rule, in which case the task fails and changed is false. Use --diff with check mode to preview branch changes when a run would succeed.

See Also

See also

graphiant.naas.graphiant_device_config

Push arbitrary raw device configuration payloads.

graphiant.naas.graphiant_sites

Create and manage sites referenced in site.name.

Examples

- name: Configure from YAML (device_system list)
  graphiant.naas.graphiant_device_system:
    operation: configure
    system_config_file: "sample_device_system.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: sys_result

- name: Single device from module parameters (branch from portal role if device_type omitted)
  graphiant.naas.graphiant_device_system:
    operation: configure
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-3-sdktest"
    name: "edge-3-sdktest"
    regionName: "us-east-2 (Atlanta)"
    site:
      name: "New York-sdktest"
    detailed_logs: true

- name: Override site for one device from the file
  graphiant.naas.graphiant_device_system:
    operation: configure
    system_config_file: "sample_device_system.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-3-sdktest"
    site:
      name: "San Jose-sdktest"

Return Values

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

Key	Description
aborted_pushes_due_to_no_site boolean	true when a multi-device run failed for skipped_no_site and other pending updates were not applied. Returned: on failure, when a batch was aborted
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 entries when a branch would change, etc.). Returned: always
diff dictionary	Ansible --diff payload (before and after text) when changes would be applied. Returned: when playbook uses --diff and at least one device branch would change
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
skipped_no_site list / elements=string	Device names for which a push was not attempted because the portal has no site on the device and the desired edge/core payload has no site (the API requires a site before that update). The task fails when this is non-empty. Returned: failure
system_config_file string	Path to the YAML file used, if any. Returned: when provided
would_configure_devices list / elements=string	When the task fails for skipped_no_site, the other devices that would have been updated in the same run but were not, because the batch was aborted. Returned: on failure, when a batch was aborted

Authors

• Graphiant Team (@graphiant)

Collection links

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