graphiant.naas.graphiant_device_config module – Push raw device configurations to Graphiant devices

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

New in graphiant.naas 25.12.0

Synopsis
Requirements
Parameters
Attributes
Notes
See Also
Examples
Return Values

Synopsis

This module pushes device configurations directly to Graphiant devices using the /v1/devices/{device_id}/config API.
Supports Edge, Gateway, and Core device types.
Enables pushing any configuration that conforms to the Graphiant API specification.
Users can capture API payloads from the Graphiant Portal UI developer tools and use them directly in configuration files.
Supports optional user-defined Jinja2 templates for configuration generation.
Configuration files support Jinja2 templating syntax for dynamic configuration generation.
Provides dry-run validation mode to validate configurations before deployment.

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.
config_file string / required	Path to the device configuration YAML file. Required for all operations. Can be an absolute path or relative path. Relative paths are resolved using the configured config_path. Configuration files support Jinja2 templating syntax for dynamic generation. File must contain device_config list with entries in the format: device_config: - device-name: payload: \| { JSON payload conforming to API spec }
detailed_logs boolean	Enable detailed logging output for troubleshooting and monitoring. When enabled, provides comprehensive logs of all device configuration operations. Logs are captured and included in the result_msg for display using ansible.builtin.debug module. Choices: `false` ← (default) `true`
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
operation string	The specific device configuration operation to perform. `configure`: Push device configuration to devices (PUT /v1/devices/{device_id}/config). `show_validated_payload`: Dry-run mode that shows the validated payload after SDK model processing. Validates configuration syntax, resolves device names, and displays what would be pushed to the API. Unrecognized fields are excluded by SDK models. No changes are made to devices. Choices: `"configure"` ← (default) `"show_validated_payload"`
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 device configuration. `present`: Maps to `configure` operation when `operation` not specified. `absent` state is not supported as device configuration is a PUT operation. Choices: `"present"` ← (default)
template_file string	Optional path to a user-defined Jinja2 template file. When provided, the template is rendered with config file data as context. The rendered template should produce the final device_config structure. Can be an absolute path or relative path. Relative paths are resolved using the configured config_path. Use this to create reusable templates for common configuration patterns.
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: partial For `show_validated_payload` operation, check mode returns `changed=False` as this is a read-only validation operation that makes no changes to the system. For `configure` operation, check mode returns `changed=True` as the module cannot accurately determine whether changes would actually be made without querying the current state via API calls. The module does not perform state comparison in check mode for `configure` operations due to API limitations. This means that check mode may report changes even when the configuration is already applied.	Supports check mode with partial support.

Notes

Note

Supported Device Types:
- Edge devices: Use ‘edge’ key in payload
- Gateway devices: Use ‘edge’ key in payload (same as edge)
- Core devices: Use ‘core’ key in payload
Configuration Approach:
- The config file contains device_config entries with device names and their payloads.
- Payloads are JSON structures conforming to the PUT /v1/devices/{device_id}/config API schema.
- Users can copy payloads directly from the Graphiant Portal UI developer tools.
- Configuration files support Jinja2 templating for dynamic value substitution.
Template Support:
- Optional user-defined templates can be provided to generate payloads from simplified config data.
- Templates are rendered with the config file data as context.
- Built-in templates are NOT used - this is a direct API manager.
Concurrent Execution:
- Configurations are pushed to multiple devices concurrently for efficiency.
- Each device’s portal status is verified before configuration push.

Examples

- name: Push device configuration to edge devices
  graphiant.naas.graphiant_device_config:
    operation: configure
    config_file: "sample_device_config_payload.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: config_result

- name: Display configuration result
  ansible.builtin.debug:
    msg: "{{ config_result.msg }}"

- name: Show validated payload (dry-run) before pushing
  graphiant.naas.graphiant_device_config:
    operation: show_validated_payload
    config_file: "sample_device_config_payload.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: preview_result

- name: Display validated payload
  ansible.builtin.debug:
    msg: "{{ preview_result.msg }}"

- name: Push configuration using user-defined template
  graphiant.naas.graphiant_device_config:
    operation: configure
    config_file: "sample_device_config_with_template.yaml"
    template_file: "device_config_template.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: template_result

- name: Configure devices with state parameter
  graphiant.naas.graphiant_device_config:
    state: present
    config_file: "sample_device_config_payload.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

# Example config file (sample_device_config_payload.yaml):
# ---
# device_config:
#   - edge-1-sdktest:
#       payload: |
#         {
#           "edge": {
#             "dns": {
#               "dns": {
#                 "static": {
#                   "primaryIpv4V2": { "address": "8.8.8.8" },
#                   "secondaryIpv4V2": { "address": "8.8.4.4" }
#                 }
#               }
#             },
#             "regionName": "us-west-2 (San Jose)"
#           },
#           "description": "Configure custom DNS and region",
#           "configurationMetadata": { "name": "dns_config_v1" }
#         }
#   - edge-2-sdktest:
#       payload: |
#         {
#           "edge": {
#             "dns": {
#               "dns": {
#                 "static": {
#                   "primaryIpv4V2": { "address": "8.8.8.8" },
#                   "secondaryIpv4V2": { "address": "8.8.4.4" }
#                 }
#               }
#             }
#           },
#           "description": "Configure custom DNS"
#         }

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 to the system. `true` for configure operations. `false` for show_validated_payload operations. Returned: always Sample: `true`
config_file string	The configuration file used for the operation. Returned: always Sample: `"sample_device_config_payload.yaml"`
msg string	Result message from the operation, including detailed logs when `detailed_logs` is enabled. Returned: always Sample: `"Successfully configured 3 device(s)"`
operation string	The operation that was performed. Either `configure` or `show_validated_payload`. Returned: always Sample: `"configure"`
template_file string	The template file used for the operation, if provided. Returned: when applicable Sample: `"device_config_template.yaml"`

Authors

Graphiant Team (@graphiant)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/graphiant/naas/graphiant_device_config_module.html