$ ansible-doc -t module cisco.sccfm.trigger_asa_upgrade
> MODULE cisco.sccfm.trigger_asa_upgrade (sccfm-ansible/plugins/modules/trigger_asa_upgrade.py)
Trigger a software and/or ASDM upgrade on one or more ASA devices
managed by SCC Firewall Manager.
Idempotent — if every target device already runs the requested
version(s), the module returns `ok' (changed=False).
Validates that the software upgrade is not a downgrade and that the
target ASDM version is compatible with the target (or current)
software version. ASDM downgrades are allowed.
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
- asdm_version Target ASDM version (e.g. `7.18(1.152')).
At least one of `software_version' or `asdm_version'
is required.
default: null
type: str
- force_upgrade Force upgrade even if a staged upgrade already
exists.
default: false
type: bool
- 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 ASA devices.
Mutually exclusive with `uids'.
The query is automatically combined with `deviceType:ASA'.
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 ASA firmware version (e.g. `9.18(4')).
At least one of `software_version' or
`asdm_version' is required.
default: null
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 software and ASDM on specific devices
- name: Trigger ASA upgrade
cisco.sccfm.trigger_asa_upgrade:
uids:
- "12345678-1234-1234-1234-123456789abc"
software_version: "9.18(4)"
asdm_version: "7.18(1.152)"
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
# Example 2: Stage-only upgrade using a query
- name: Stage ASA upgrade for branch devices
cisco.sccfm.trigger_asa_upgrade:
query: "name:branch-*"
software_version: "9.18(4)"
stage_upgrade: true
# Example 3: ASDM-only upgrade
- name: Upgrade ASDM on a group of ASAs
cisco.sccfm.trigger_asa_upgrade:
uids:
- "uid-1"
- "uid-2"
asdm_version: "7.18(1.152)"
# Example 4: Wait for the upgrade transaction to finish
- name: Trigger ASA upgrade and wait for completion
cisco.sccfm.trigger_asa_upgrade:
uids:
- "uid-1"
software_version: "9.18(4)"
wait: true
timeout: 3600
# Example 5: Using module_defaults (recommended)
- name: Trigger ASA upgrade
hosts: localhost
gather_facts: false
module_defaults:
group/cisco.sccfm.all:
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
tasks:
- name: Stage ASA upgrade for branch devices
cisco.sccfm.trigger_asa_upgrade:
query: "name:branch-*"
software_version: "9.18(4)"
stage_upgrade: true
RETURN VALUES:
- device_count Number of devices included in the upgrade.
returned: always
type: int
- transaction The triggered or completed transaction object for the
upgrade.
returned: success (changed=True)
type: dict