Join AnsibleFest at Red Hat Summit!

This is the latest (stable) Ansible community documentation. For Red Hat Ansible Automation Platform subscriptions, see Life Cycle for version details.

cisco.dnac.swim_intent module – Intent module for SWIM related functions

Note

This module is part of the cisco.dnac collection (version 6.31.3).

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 cisco.dnac. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: cisco.dnac.swim_intent.

New in cisco.dnac 6.6.0

Synopsis

• Manage operation related to image importation, distribution, activation and tagging image as golden

• API to fetch a software image from remote file system using URL for HTTP/FTP and upload it to Catalyst Center. Supported image files extensions are bin, img, tar, smu, pie, aes, iso, ova, tar_gz and qcow2.

• API to fetch a software image from local file system and upload it to Catalyst Center Supported image files extensions are bin, img, tar, smu, pie, aes, iso, ova, tar_gz and qcow2.

• API to tag/untag image as golen for a given family of devices

• API to distribute a software image on a given device. Software image must be imported successfully into Catalyst Center before it can be distributed.

• API to activate a software image on a given device. Software image must be present in the device flash.

Requirements

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

• dnacentersdk == 2.4.5

• python >= 3.9

Parameters

Parameter	Comments
config list / elements=dictionary / required	List of details of SWIM image being managed
image_activation_details dictionary	Details for SWIM image activation. Device on which the image needs to activated can be speciifed using any of the following parameters - deviceSerialNumber, deviceIPAddress, deviceHostname or deviceMacAddress.
activate_lower_image_version boolean	ActivateLowerImageVersion flag. Choices: false true
device_family_name string	Specify the name of the device family such as Switches and Hubs, etc.
device_hostname string	Device hostname where the image needs to be activated
device_ip_address string	Device IP address where the image needs to be activated
device_mac_address string	Device MAC address where the image needs to be activated
device_role string	Defines the device role, with permissible values including ALL, UNKNOWN, ACCESS, BORDER ROUTER, DISTRIBUTION, and CORE. ALL - This role typically represents all devices within the network, regardless of their specific roles or functions. UNKNOWN - This role is assigned to devices whose roles or functions have not been identified or classified within Cisco Catalsyt Center. This could happen if the platform is unable to determine the device’s role based on available information. ACCESS - This role typically represents switches or access points that serve as access points for end-user devices to connect to the network. These devices are often located at the edge of the network and provide connectivity to end-user devices. BORDER ROUTER - These are devices that connect different network domains or segments together. They often serve as gateways between different networks, such as connecting an enterprise network to the internet or connecting multiple branch offices. DISTRIBUTION - This role represents function as distribution switches or routers in hierarchical network designs. They aggregate traffic from access switches and route it toward the core of the network or toward other distribution switches. CORE - This role typically represents high-capacity switches or routers that form the backbone of the network. They handle large volumes of traffic and provide connectivity between different parts of network, such as connecting distribution switches or providing interconnection between different network segments.
device_serial_number string	Device serial number where the image needs to be activated
device_upgrade_mode string	It specifies the mode of upgrade to be applied to the devices having the following values - ‘install’, ‘bundle’, and ‘currentlyExists’. install - This mode instructs Cisco Catalyst Center to perform a clean installation of the new image on the target devices. When this mode is selected, the existing image on the device is completely replaced with the new image during the upgrade process. This ensures that the device runs only the new image version after the upgrade is completed. bundle - This mode instructs Cisco Catalyst Center bundles the new image with the existing image on the device before initiating the upgrade process. This mode allows for a more efficient upgrade process by preserving the existing image on the device while adding the new image as an additional bundle. After the upgrade, the device can run either the existing image or the new bundled image, depending on the configuration. currentlyExists - This mode instructs Cisco Catalyst Center to checks if the target devices already have the desired image version installed. If image already present on devices, no action is taken and upgrade process is skipped for those devices. This mode is useful for avoiding unnecessary upgrades on devices that already have the correct image version installed, thereby saving time.
distribute_if_needed boolean	Enable the distribute_if_needed option when activating the SWIM image. Choices: false true
image_name string	SWIM image’s name
schedule_validate boolean	ScheduleValidate query parameter. ScheduleValidate, validates data before schedule (optional). Choices: false true
site_name string	Used to get device details associated to this site.
image_distribution_details dictionary	Details for SWIM image distribution. Device on which the image needs to distributed can be speciifed using any of the following parameters - deviceSerialNumber, deviceIPAddress, deviceHostname or deviceMacAddress.
device_family_name string	Specify the name of the device family such as Switches and Hubs, etc.
device_hostname string	Device hostname where the image needs to be distributed
device_ip_address string	Device IP address where the image needs to be distributed
device_mac_address string	Device MAC address where the image needs to be distributed
device_role string	Defines the device role, with permissible values including ALL, UNKNOWN, ACCESS, BORDER ROUTER, DISTRIBUTION, and CORE. ALL - This role typically represents all devices within the network, regardless of their specific roles or functions. UNKNOWN - This role is assigned to devices whose roles or functions have not been identified or classified within Cisco Catalsyt Center. This could happen if the platform is unable to determine the device’s role based on available information. ACCESS - This role typically represents switches or access points that serve as access points for end-user devices to connect to the network. These devices are often located at the edge of the network and provide connectivity to end-user devices. BORDER ROUTER - These are devices that connect different network domains or segments together. They often serve as gateways between different networks, such as connecting an enterprise network to the internet or connecting multiple branch offices. DISTRIBUTION - This role represents function as distribution switches or routers in hierarchical network designs. They aggregate traffic from access switches and route it toward the core of the network or toward other distribution switches. CORE - This role typically represents high-capacity switches or routers that form the backbone of the network. They handle large volumes of traffic and provide connectivity between different parts of network, such as connecting distribution switches or providing interconnection between different network segments.
device_serial_number string	Device serial number where the image needs to be distributed
device_series_name string added in cisco.dnac 6.12.0	This parameter specifies the name of the device series. It is used to identify a specific series of devices, such as Cisco Catalyst 9300 Series Switches, within the Cisco Catalyst Center.
image_name string	SWIM image’s name
site_name string	Used to get device details associated to this site.
import_image_details dictionary	Details of image being imported
local_image_details dictionary	Details of the local path of the image to be imported.
file_path string	Provide the absolute file path needed to import an image from your local system (Eg “/path/to/your/file”). Accepted files formats are - .gz,.bin,.img,.tar,.smu,.pie,.aes,.iso,.ova,.tar_gz,.qcow2,.nfvispkg,.zip,.spa,.rpm.
is_third_party boolean	Query parameter to determine if the image is from a third party (optional). Choices: false true
third_party_application_type string	Specify the ThirdPartyApplicationType query parameter to indicate the type of third-party application. Allowed values include WLC, LINUX, FIREWALL, WINDOWS, LOADBALANCER, THIRDPARTY, etc.(optional). WLC (Wireless LAN Controller) - It’s a network device that manages and controls multiple wireless access points (APs) in a centralized manner. LINUX - It’s an open-source operating system that provides a complete set of software packages and utilities. FIREWALL - It’s a network security device that monitors and controls incoming and outgoing network traffic based on predetermined security rules.It acts as a barrier between a trusted internal network and untrusted external networks (such as the internet), preventing unauthorized access. WINDOWS - It’s an operating system known for its graphical user interface (GUI) support, extensive compatibility with hardware and software, and widespread use across various applications. LOADBALANCER - It’s a network device or software application that distributes incoming network traffic across multiple servers or resources. THIRDPARTY - It refers to third-party images or applications that are not part of the core system. NAM (Network Access Manager) - It’s a network management tool or software application that provides centralized control and monitoring of network access policies, user authentication, and device compliance. WAN Optimization - It refers to techniques and technologies used to improve the performance and efficiency of WANs. It includes various optimization techniques such as data compression, caching, protocol optimization, and traffic prioritization to reduce latency, increase throughput, and improve user experience over WAN connections. Unknown - It refers to an unspecified or unrecognized application type. Router - It’s a network device that forwards data packets between computer networks. They are essential for connecting multiple networks together and directing traffic between them.
third_party_image_family string	Provide the ThirdPartyImageFamily query parameter to identify the family of the third-party image. Image Family name like PALOALTO, RIVERBED, FORTINET, CHECKPOINT, SILVERPEAK etc. (optional).
third_party_vendor string	Include the ThirdPartyVendor query parameter to specify the vendor of the third party.
type string	Specifies the import source, supporting local file import (local) or remote url import (remote).
url_details dictionary	URL details for SWIM import
payload list / elements=dictionary	Swim Import Via Url’s payload.
application_type string	An optional parameter that specifies the type of application. Allowed values include WLC, LINUX, FIREWALL, WINDOWS, LOADBALANCER, THIRDPARTY, etc. This is only applicable for third-party image types(optional). WLC (Wireless LAN Controller) - It’s network device that manages and controls multiple wireless access points (APs) in a centralized manner. LINUX - It’s an open source which provide complete operating system with a wide range of software packages and utilities. FIREWALL - It’s a network security device that monitors and controls incoming and outgoing network traffic based on predetermined security rules.It acts as a barrier between a trusted internal network and untrusted external networks (such as the internet), preventing unauthorized access. WINDOWS - It’s an OS which provides GUI support for various applications, and extensive compatibility with hardware and software. LOADBALANCER - It’s a network device or software application that distributes incoming network traffic across multiple servers or resources. THIRDPARTY - It refers to third-party images or applications that are not part of the core system. NAM (Network Access Manager) - It’s a network management tool or software application that provides centralized control and monitoring of network access policies, user authentication, and device compliance. WAN Optimization - It refers to techniques and technologies used to improve the performance and efficiency of WANs. It includes various optimization techniques such as data compression, caching, protocol optimization, and traffic prioritization to reduce latency, increase throughput, and improve user experience over WAN connections. Unknown - It refers to an unspecified or unrecognized application type. Router - It’s a network device that forwards data packets between computer networks. They are essential for connecting multiple networks together and directing traffic between them.
image_family string	Represents the name of the image family and is applicable only when uploading third-party images. Image Family name like PALOALTO, RIVERBED, FORTINET, CHECKPOINT, SILVERPEAK etc. (optional).
is_third_party boolean	Flag indicates whether the image is uploaded from a third party (optional). Choices: false true
source_url string	A mandatory parameter for importing a SWIM image via a remote URL. This parameter is required when using a URL to import an image.(For example, http://{host}/swim/cat9k_isoxe.16.12.10s.SPA.bin, ftp://user:password@{host}/swim/cat9k_isoxe.16.12.10s.SPA.iso)
vendor string	The name of the vendor, that applies only to third-party image types when importing via URL (optional).
schedule_at string	ScheduleAt query parameter. Epoch Time (The number of milli-seconds since January 1 1970 UTC) at which the distribution should be scheduled (optional).
schedule_desc string	ScheduleDesc query parameter. Custom Description (optional).
schedule_origin string	ScheduleOrigin query parameter. Originator of this call (optional).
tagging_details dictionary	Details for tagging or untagging an image as golden
device_image_family_name string	Device Image family name(Eg Cisco Catalyst 9300 Switch)
device_role string	Defines the device role, with permissible values including ALL, UNKNOWN, ACCESS, BORDER ROUTER, DISTRIBUTION, and CORE. ALL - This role typically represents all devices within the network, regardless of their specific roles or functions. UNKNOWN - This role is assigned to devices whose roles or functions have not been identified or classified within Cisco Catalsyt Center. This could happen if the platform is unable to determine the device’s role based on available information. ACCESS - This role typically represents switches or access points that serve as access points for end-user devices to connect to the network. These devices are often located at the edge of the network and provide connectivity to end-user devices. BORDER ROUTER - These are devices that connect different network domains or segments together. They often serve as gateways between different networks, such as connecting an enterprise network to the internet or connecting multiple branch offices. DISTRIBUTION - This role represents function as distribution switches or routers in hierarchical network designs. They aggregate traffic from access switches and route it toward the core of the network or toward other distribution switches. CORE - This role typically represents high-capacity switches or routers that form the backbone of the network. They handle large volumes of traffic and provide connectivity between different parts of network, such as connecting distribution switches or providing interconnection between different network segments.
device_series_name string added in cisco.dnac 6.12.0	This parameter specifies the name of the device series. It is used to identify a specific series of devices, such as Cisco Catalyst 9300 Series Switches, within the Cisco Catalyst Center.
image_name string	SWIM image name which will be tagged or untagged as golden.
site_name string	Site name for which SWIM image will be tagged/untagged as golden. If not provided, SWIM image will be mapped to global site.
tagging boolean	Booelan value to tag/untag SWIM image as golden If True then the given image will be tagged as golden. If False then the given image will be un-tagged as golden. Choices: false true
config_verify boolean	Set to True to verify the Cisco Catalyst Center config after applying the playbook config. Choices: false ← (default) true
dnac_api_task_timeout integer	Defines the timeout in seconds for API calls to retrieve task details. If the task details are not received within this period, the process will end, and a timeout notification will be logged. Default: 1200
dnac_debug boolean	Flag for Cisco DNA Center SDK to enable debugging. Choices: false ← (default) true
dnac_host string / required	The Cisco DNA Center hostname.
dnac_log boolean	Flag to enable/disable playbook execution logging. When true and dnac_log_file_path is provided, - Create the log file at the execution location with the specified name. When true and dnac_log_file_path is not provided, - Create the log file at the execution location with the name ‘dnac.log’. When false, - Logging is disabled. If the log file doesn’t exist, - It is created in append or write mode based on the “dnac_log_append” flag. If the log file exists, - It is overwritten or appended based on the “dnac_log_append” flag. Choices: false ← (default) true
dnac_log_append boolean	Determines the mode of the file. Set to True for ‘append’ mode. Set to False for ‘write’ mode. Choices: false true ← (default)
dnac_log_file_path string	Governs logging. Logs are recorded if dnac_log is True. If path is not specified, - When ‘dnac_log_append’ is True, ‘dnac.log’ is generated in the current Ansible directory; logs are appended. - When ‘dnac_log_append’ is False, ‘dnac.log’ is generated; logs are overwritten. If path is specified, - When ‘dnac_log_append’ is True, the file opens in append mode. - When ‘dnac_log_append’ is False, the file opens in write (w) mode. - In shared file scenarios, without append mode, content is overwritten after each module execution. - For a shared log file, set append to False for the 1st module (to overwrite); for subsequent modules, set append to True. Default: "dnac.log"
dnac_log_level string	Sets the threshold for log level. Messages with a level equal to or higher than this will be logged. Levels are listed in order of severity [CRITICAL, ERROR, WARNING, INFO, DEBUG]. CRITICAL indicates serious errors halting the program. Displays only CRITICAL messages. ERROR indicates problems preventing a function. Displays ERROR and CRITICAL messages. WARNING indicates potential future issues. Displays WARNING, ERROR, CRITICAL messages. INFO tracks normal operation. Displays INFO, WARNING, ERROR, CRITICAL messages. DEBUG provides detailed diagnostic info. Displays all log messages. Default: "WARNING"
dnac_password string	The Cisco DNA Center password to authenticate.
dnac_port string	The Cisco DNA Center port. Default: "443"
dnac_task_poll_interval integer	Specifies the interval in seconds between successive calls to the API to retrieve task details. Default: 2
dnac_username aliases: user string	The Cisco DNA Center username to authenticate. Default: "admin"
dnac_verify boolean	Flag to enable or disable SSL certificate verification. Choices: false true ← (default)
dnac_version string	Informs the SDK which version of Cisco DNA Center to use. Default: "2.2.3.3"
state string	The state of Catalyst Center after module completion. Choices: "merged" ← (default)
validate_response_schema boolean	Flag for Cisco DNA Center SDK to enable the validation of request bodies against a JSON schema. Choices: false true ← (default)

Notes

Note

• SDK Method used are software_image_management_swim.SoftwareImageManagementSwim.import_software_image_via_url, software_image_management_swim.SoftwareImageManagementSwim.tag_as_golden_image, software_image_management_swim.SoftwareImageManagementSwim.trigger_software_image_distribution, software_image_management_swim.SoftwareImageManagementSwim.trigger_software_image_activation,

• Paths used are post /dna/intent/api/v1/image/importation/source/url, post /dna/intent/api/v1/image/importation/golden, post /dna/intent/api/v1/image/distribution, post /dna/intent/api/v1/image/activation/device,

• Added the parameter ‘dnac_api_task_timeout’, ‘dnac_task_poll_interval’ options in v6.13.2.

• Does not support check_mode

• The plugin runs on the control node and does not use any ansible connection plugins, but instead the embedded connection manager from Cisco DNAC SDK

• The parameters starting with dnac_ are used by the Cisco DNAC Python SDK to establish the connection

Examples

- name: Import an image from a URL, tag it as golden and load it on device
  cisco.dnac.swim_intent:
    dnac_host: "{{dnac_host}}"
    dnac_username: "{{dnac_username}}"
    dnac_password: "{{dnac_password}}"
    dnac_verify: "{{dnac_verify}}"
    dnac_port: "{{dnac_port}}"
    dnac_version: "{{dnac_version}}"
    dnac_debug: "{{dnac_debug}}"
    dnac_log_level: "{{dnac_log_level}}"
    dnac_log: true
    config:
      - import_image_details:
          type: remote
          url_details:
            payload:
              - source_url: "http://10.10.10.10/stda/cat9k_iosxe.17.12.01.SPA.bin"
                is_third_party: false
        tagging_details:
          image_name: cat9k_iosxe.17.12.01.SPA.bin
          device_role: ACCESS
          device_image_family_name: Cisco Catalyst 9300 Switch
          site_name: Global/USA/San Francisco/BGL_18
          tagging: true
        image_distribution_details:
          image_name: cat9k_iosxe.17.12.01.SPA.bin
          device_serial_number: FJC2327U0S2
        image_activation_details:
          image_name: cat9k_iosxe.17.12.01.SPA.bin
          schedule_validate: false
          activate_lower_image_version: false
          distribute_if_needed: true
          device_serial_number: FJC2327U0S2
- name: Import an image from local, tag it as golden.
  cisco.dnac.swim_intent:
    dnac_host: "{{dnac_host}}"
    dnac_username: "{{dnac_username}}"
    dnac_password: "{{dnac_password}}"
    dnac_verify: "{{dnac_verify}}"
    dnac_port: "{{dnac_port}}"
    dnac_version: "{{dnac_version}}"
    dnac_debug: "{{dnac_debug}}"
    dnac_log_level: "{{dnac_log_level}}"
    dnac_log: true
    config:
      - import_image_details:
          type: local
          local_image_details:
            file_path: /Users/Downloads/cat9k_iosxe.17.12.01.SPA.bin
            is_third_party: false
        tagging_details:
          image_name: cat9k_iosxe.17.12.01.SPA.bin
          device_role: ACCESS
          device_image_family_name: Cisco Catalyst 9300 Switch
          site_name: Global/USA/San Francisco/BGL_18
          tagging: true
- name: Tag the given image as golden and load it on device
  cisco.dnac.swim_intent:
    dnac_host: "{{dnac_host}}"
    dnac_username: "{{dnac_username}}"
    dnac_password: "{{dnac_password}}"
    dnac_verify: "{{dnac_verify}}"
    dnac_port: "{{dnac_port}}"
    dnac_version: "{{dnac_version}}"
    dnac_debug: "{{dnac_debug}}"
    dnac_log_level: "{{dnac_log_level}}"
    dnac_log: true
    config:
      - tagging_details:
          image_name: cat9k_iosxe.17.12.01.SPA.bin
          device_role: ACCESS
          device_image_family_name: Cisco Catalyst 9300 Switch
          site_name: Global/USA/San Francisco/BGL_18
          tagging: true
- name: Un-tagged the given image as golden and load it on device
  cisco.dnac.swim_intent:
    dnac_host: "{{dnac_host}}"
    dnac_username: "{{dnac_username}}"
    dnac_password: "{{dnac_password}}"
    dnac_verify: "{{dnac_verify}}"
    dnac_port: "{{dnac_port}}"
    dnac_version: "{{dnac_version}}"
    dnac_debug: "{{dnac_debug}}"
    dnac_log_level: "{{dnac_log_level}}"
    dnac_log: true
    config:
      - tagging_details:
          image_name: cat9k_iosxe.17.12.01.SPA.bin
          device_role: ACCESS
          device_image_family_name: Cisco Catalyst 9300 Switch
          site_name: Global/USA/San Francisco/BGL_18
          tagging: false
- name: Distribute the given image on devices associated to that site with specified
    role.
  cisco.dnac.swim_intent:
    dnac_host: "{{dnac_host}}"
    dnac_username: "{{dnac_username}}"
    dnac_password: "{{dnac_password}}"
    dnac_verify: "{{dnac_verify}}"
    dnac_port: "{{dnac_port}}"
    dnac_version: "{{dnac_version}}"
    dnac_debug: "{{dnac_debug}}"
    dnac_log_level: "{{dnac_log_level}}"
    dnac_log: true
    config:
      - image_distribution_details:
          image_name: cat9k_iosxe.17.12.01.SPA.bin
          site_name: Global/USA/San Francisco/BGL_18
          device_role: ALL
          device_family_name: Switches and Hubs
          device_series_name: Cisco Catalyst 9300 Series Switches
- name: Activate the given image on devices associated to that site with specified
    role.
  cisco.dnac.swim_intent:
    dnac_host: "{{dnac_host}}"
    dnac_username: "{{dnac_username}}"
    dnac_password: "{{dnac_password}}"
    dnac_verify: "{{dnac_verify}}"
    dnac_port: "{{dnac_port}}"
    dnac_version: "{{dnac_version}}"
    dnac_debug: "{{dnac_debug}}"
    dnac_log_level: "{{dnac_log_level}}"
    dnac_log: true
    config:
      - image_activation_details:
          image_name: cat9k_iosxe.17.12.01.SPA.bin
          site_name: Global/USA/San Francisco/BGL_18
          device_role: ALL
          device_family_name: Switches and Hubs
          device_series_name: Cisco Catalyst 9300 Series Switches
          scehdule_validate: false
          activate_lower_image_version: true
          distribute_if_needed: true

Return Values

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

Key

Description

response dictionary

A dictionary with activation details as returned by the Catalyst Center Python SDK Returned: always Sample: "{\n  \"response\": {\n                    \"additionalStatusURL\": String,\n                    \"data\": String,\n                    \"endTime\": 0,\n                    \"id\": String,\n                    \"instanceTenantId\": String,\n                    \"isError\": bool,\n                    \"lastUpdate\": 0,\n                    \"progress\": String,\n                    \"rootId\": String,\n                    \"serviceType\": String,\n                    \"startTime\": 0,\n                    \"version\": 0\n              },\n  \"msg\": String\n}\n"

Authors

• Madhan Sankaranarayanan (@madhansansel) Rishita Chowdhary (@rishitachowdhary) Abhishek Maheshwari (@abmahesh)

Collection links

• Issue Tracker
• Repository (Sources)