$ 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):
- api_token API token for SCCFM.
set_via:
env:
- name: SCCFM_API_TOKEN
default: null
no_log: true
type: str
- 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
- 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
- region SCCFM region (int, us, eu, apj, au, uae, in, or ci).
set_via:
env:
- name: SCCFM_REGION
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
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"
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
# 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:
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
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