$ ansible-doc -t module cisco.sccfm.trigger_ftd_upgrade
> MODULE cisco.sccfm.trigger_ftd_upgrade (sccfm-ansible/plugins/modules/trigger_ftd_upgrade.py)
Trigger a software upgrade on one or more FTD devices managed by SCC
Firewall Manager.
Idempotent — if every eligible target device already runs the
requested version, the module returns `ok' (changed=False).
Devices that the upgrade API does not support (e.g. FDM-managed
FTDs) are automatically skipped with a warning.
Validates that the software upgrade is not a downgrade.
Supports staging (download + readiness check only) via
`stage_upgrade'.
OPTIONS (= indicates it is required):
- config_path Optional path to the canonical SCCFM profile
configuration file.
default: null
type: path
- ignore_maintenance_window Allow upgrade outside the device
maintenance window.
default: false
type: bool
- limit Maximum number of devices to return when using `query'.
Ignored when using `uids'.
default: 50
type: int
- offset Pagination offset when using `query'.
Ignored when using `uids'.
default: 0
type: int
- profile Named SCCFM profile configured by `sccfm-cli configure'.
default: default
type: str
- query Lucene query to select FTD devices.
Mutually exclusive with `uids'.
The query is automatically combined with FTD device type
filters.
default: null
type: str
= software_version Target FTD software version (e.g. `7.4.1').
The module resolves the corresponding
`upgrade_package_uid' from the compatible
versions list automatically.
type: str
- stage_upgrade Stage only — download image and run readiness checks
without applying the upgrade.
default: false
type: bool
- timeout Maximum number of seconds to wait for the upgrade
transaction when `wait=true'.
default: 3600
type: int
- uids List of device UIDs to upgrade.
Mutually exclusive with `query'.
default: null
elements: str
type: list
- upgrade_name Human-readable name to identify and track the upgrade
run.
default: null
type: str
- wait Wait for the returned upgrade transaction to reach a
terminal status.
When enabled, the module fails if the transaction ends in
`ERROR' or `CANCELLED'.
default: false
type: bool
AUTHOR: Cisco SCCFM Team (@CiscoDevNet)
EXAMPLES:
# Example 1: Upgrade specific FTD devices
- name: Trigger FTD upgrade
cisco.sccfm.trigger_ftd_upgrade:
uids:
- "12345678-1234-1234-1234-123456789abc"
software_version: "7.4.1"
profile: default
# Example 2: Stage-only upgrade using a query
- name: Stage FTD upgrade for branch devices
cisco.sccfm.trigger_ftd_upgrade:
query: "name:branch-ftd-*"
software_version: "7.4.1"
stage_upgrade: true
# Example 3: Wait for the upgrade transaction to finish
- name: Trigger FTD upgrade and wait for completion
cisco.sccfm.trigger_ftd_upgrade:
uids:
- "uid-1"
software_version: "7.4.1"
wait: true
timeout: 3600
# Example 4: Using module_defaults (recommended)
- name: Trigger FTD upgrade
hosts: localhost
gather_facts: false
module_defaults:
group/cisco.sccfm.all:
profile: default
tasks:
- name: Stage FTD upgrade for branch devices
cisco.sccfm.trigger_ftd_upgrade:
query: "name:branch-ftd-*"
software_version: "7.4.1"
stage_upgrade: true
RETURN VALUES:
- device_count Number of eligible devices included in the upgrade.
returned: always
type: int
- skipped Devices that were skipped because the upgrade API rejected
them, keyed by device UID with the error message as value.
returned: always
type: dict
- transaction The triggered or completed transaction object for the
upgrade.
returned: success (changed=True)
type: dict