graphiant.naas.graphiant_device_lifecycle_info module – Query device lifecycle state and software upgrade status

Note

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

New in graphiant.naas 26.10.0

Synopsis

• Read-only query of GET /v1/edges-summary (with upgradeSummary=true); matches the portal’s Maintain > Device Lifecycle page. Returns per-device status, portalStatus, and upgradeSummary fields (running/last-running/ready-for-activation version, schedule state), plus lifecycle_state (a friendly label for status: activated, staging, maintenance, or deactivated).

• With neither config_file nor device set, all devices matching role are returned, and the task cannot fail on a missing device (there is no fixed target list to compare against). When device or config_file‘s device_lifecycle list names specific devices, the task fails if any of them are not found (returned in failed_devices), the same way a named graphiant.naas.graphiant_device_lifecycle change_state target that does not exist fails rather than being silently skipped.

• Supply config_file for a device_lifecycle list (only the device names, i.e. the list keys, are used — other per-device fields in that file are ignored here), and/or device to query a single device.

Requirements

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

• python >= 3.7

• graphiant-sdk >= 26.10.0

• tabulate (optional; logs a tabulated device table with detailed_logs=true when installed)

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	Path to YAML with a top-level device_lifecycle list (only the device names, i.e. the list keys, are used); optional if device is set instead, or to list every device. Relative paths resolve using the collection config path (see GRAPHIANT_CONFIGS_PATH). The file may also set a top-level role key (same as the role option); role on the task always overrides the file’s value.
detailed_logs boolean	Enable detailed logging in the task result message. When tabulate is installed, this also logs a table of the reported devices (Device ID, Host Name, Lifecycle State, Portal Sync, Release, Release Name, Software Version, Upgrade Status, Rollout Name, Site, Connected Region, Location) and the enterprise the connection resolved to — useful for diagnosing an empty or unexpected result (e.g. credentials resolving to the wrong enterprise). Portal Sync is the raw portalStatus (e.g. Ready, Configuring, ModeChanged) — the same status graphiant.naas.graphiant_device_lifecycle‘s change_state polls for after a mutation. Software Version is the device’s own swVersion. Release and Release Name are resolved from multiple sources, in order, since any single one of them is frequently empty for a given device: for Release — a GET /v1/software/releases/summary catalog lookup by swVersion, then upgradeSummary.runningVersion.release; for Release Name — the device’s own swName, then that same catalog lookup, then upgradeSummary.runningVersion.name. All can legitimately end up empty for an unlisted/superseded build that was never given a friendly name. Choices: false ← (default) true
device string	Portal device name to query. With config_file, optional override for this one device. Omit along with config_file to query all devices matching role.
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
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.
role string	Client-side device role filter (e.g. cpe, gateway) used only when neither config_file nor device is set. If not set here, taken from a top-level role key in config_file when present, else all devices are returned (no filter). The portal’s own Device Lifecycle page always sends filter[role]=UnknownDeviceRole regardless of the actual devices shown — the API has no server-side role filter to apply, so that value has no effect there either; it is not a real device role and filtering on it here would incorrectly match no devices.
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	Always read-only; check mode has no side effects.

See Also

See also

graphiant.naas.graphiant_device_lifecycle

Change device lifecycle state, schedule/roll back software upgrades.

Examples

- name: Get upgrade/lifecycle status for all cpe devices
  graphiant.naas.graphiant_device_lifecycle_info:
    role: "cpe"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  register: status_result

- name: Show status
  ansible.builtin.debug:
    var: status_result.devices

- name: Get status for a single device
  graphiant.naas.graphiant_device_lifecycle_info:
    device: "edge-1-sdktest"
    detailed_logs: true
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

- name: Get status for the devices listed in a config file
  graphiant.naas.graphiant_device_lifecycle_info:
    config_file: "sample_device_lifecycle.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

Return Values

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

Key	Description
changed boolean	Always false (read-only). Returned: always
details dictionary	Raw manager result payload. Returned: always
devices dictionary	Per-device status, keyed by device name. Returned: always
connected_regions list / elements=string	Regions the device has tunnel-terminator connections to. Returned: success
device_id integer	Portal device ID. Returned: success
last_running_version dictionary	upgradeSummary.lastRunningVersion. Returned: success
lifecycle_state string	Friendly label for status (activated/staging/maintenance/deactivated). Returned: success
location string	Discovered location (city/state/country) as a single string. Returned: success
portal_status string	Portal sync status (e.g. Ready). Returned: success
ready_for_activation_version dictionary	upgradeSummary.readyForActivationVersion, when a download is complete but not yet activated. Returned: success
rollout_name string	upgradeSummary.rolloutName, when the device is part of a rollout. Returned: success
running_version dictionary	upgradeSummary.runningVersion (release/version/name). Returned: success
schedule dictionary	upgradeSummary.schedule (action/state/download progress/failure reason/target version). Returned: success
site string	Portal site name. Returned: success
status string	Raw portal status (e.g. active, inactive, staging, maintenance). Returned: success
sw_name string	Software release name (e.g. 26.6.3). Returned: success
sw_version string	Software build version string. Returned: success
upgrade_status string	upgradeSummary.status (e.g. UpToDate, UpgradeAvailable). Returned: success
failed_devices list / elements=dictionary	Devices that could not be found. Only possible when specific devices were requested via device or config_file; non-empty fails the task. Returned: always
device_name string	The device name that could not be found. Returned: success
error string	Error detail explaining the lookup failure. Returned: success
msg string	Result message, including detailed logs when detailed_logs is enabled. Returned: always

Authors

• Graphiant Team (@graphiant)

Collection links

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