cisco.catalystcenter.sda_host_port_migration_playbook_config_generator module -- Generate SDA host port migration YAML configurations.

Note

This module is part of the cisco.catalystcenter collection (version 2.13.0).

To install it, use: ansible-galaxy collection install cisco.catalystcenter.

To use it in a playbook, specify: cisco.catalystcenter.sda_host_port_migration_playbook_config_generator.

New in cisco.catalystcenter 6.44.0

Synopsis

  • Generates YAML configuration compatible with sda_host_port_onboarding_workflow_manager by reading port assignments and port channels from a source device and targeting a destination device.

  • Supports 1:1 interface migration by default.

  • Supports partial interface remap with interface_mappings. Source interfaces listed in mappings are remapped only when they exist in the source device's extracted port assignments or port channel member interfaces. Unmapped interfaces keep the same interface name unless only_mapped_interfaces is enabled.

Parameters

Parameter

Comments

catalystcenter_api_task_timeout

aliases: 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: :ansible-option-default:`1200`

catalystcenter_debug

aliases: dnac_debug

boolean

Indicates whether debugging is enabled in the Cisco Catalyst Center SDK.

Choices:

catalystcenter_host

aliases: dnac_host

string / required

The hostname of the Cisco Catalyst Center.

catalystcenter_log

aliases: dnac_log

boolean

Flag to enable/disable playbook execution logging.

When true and catalystcenter_log_file_path is provided, - Create the log file at the execution location with the specified name.

When true and catalystcenter_log_file_path is not provided, - Create the log file at the execution location with the name 'catalystcenter.log'.

When false, - Logging is disabled.

If the log file doesn't exist, - It is created in append or write mode based on the "catalystcenter_log_append" flag.

If the log file exists, - It is overwritten or appended based on the "catalystcenter_log_append" flag.

Choices:

catalystcenter_log_append

aliases: dnac_log_append

boolean

Determines the mode of the file. Set to True for 'append' mode. Set to False for 'write' mode.

Choices:

catalystcenter_log_file_path

aliases: dnac_log_file_path

string

Governs logging. Logs are recorded if catalystcenter_log is True.

If path is not specified, - When 'catalystcenter_log_append' is True, 'catalystcenter.log' is generated in the current Ansible directory; logs are appended. - When 'catalystcenter_log_append' is False, 'catalystcenter.log' is generated; logs are overwritten.

If path is specified, - When 'catalystcenter_log_append' is True, the file opens in append mode. - When 'catalystcenter_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: :ansible-option-default:`"catalystcenter.log"`

catalystcenter_log_level

aliases: 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: :ansible-option-default:`"WARNING"`

catalystcenter_password

aliases: dnac_password

string

The password for authentication at the Cisco Catalyst Center.

catalystcenter_port

aliases: dnac_port, catalystcenter_api_port

string

Specifies the port number associated with the Cisco Catalyst Center.

Default: :ansible-option-default:`"443"`

catalystcenter_task_poll_interval

aliases: dnac_task_poll_interval

integer

Specifies the interval in seconds between successive calls to the API to retrieve task details.

Default: :ansible-option-default:`2`

catalystcenter_username

aliases: dnac_username, user

string

The username for authentication at the Cisco Catalyst Center.

Default: :ansible-option-default:`"admin"`

catalystcenter_verify

aliases: dnac_verify

boolean

Flag to enable or disable SSL certificate verification.

Choices:

catalystcenter_version

aliases: dnac_version

string

Specifies the version of the Cisco Catalyst Center that the SDK should use.

Default: :ansible-option-default:`"2.3.7.6"`

config

dictionary / required

Dictionary of component filters for generating migration YAML.

Supports port_assignments, port_channels, or both through component_specific_filters.

component_specific_filters

dictionary / required

Component-specific migration filters.

Provide port_assignments, port_channels, or both.

Requested components are inferred from the component keys present in this dictionary.

port_assignments

list / elements=dictionary

Source-to-destination migration filters for SDA host port assignments.

Provide this key to generate port assignment migration payloads.

Each entry selects a source fabric site and source device, then generates destination port assignment payload for destination_device_ip.

destination_device_ip

string / required

Destination device management IP address to use as ip_address in the generated onboarding payload.

fabric_site_name_hierarchy

string / required

Fabric site hierarchy that contains the source device port assignments.

Must match the full Catalyst Center fabric site hierarchy.

interface_mappings

list / elements=dictionary

Optional source-to-destination interface remap list.

Source interfaces listed here are remapped only when they exist in the source device port assignment payload.

Source interface matching is case-insensitive.

The module fails when a mapped source interface is not present in the source device port assignment payload.

Destination interface spelling is preserved in the generated payload.

When only_mapped_interfaces is false, source interfaces not listed here keep their original interface name for 1:1 migration.

destination_interface_name

string / required

Interface name to use in the destination device port assignment payload.

source_interface_name

string / required

Interface name in the source device port assignment payload.

only_mapped_interfaces

boolean

Controls whether generated port assignments are limited to source interfaces listed in interface_mappings.

When true, only mapped interfaces are included.

When false, unmapped source interfaces retain their original interface name for 1:1 migration.

Choices:

source_device_ip

string / required

Source device management IP address to read port assignments from.

port_channels

list / elements=dictionary

Source-to-destination migration filters for SDA host port channels.

Provide this key to generate port channel migration payloads.

Each entry selects a source fabric site and source device, then generates destination port channel payload for destination_device_ip.

destination_device_ip

string / required

Destination device management IP address to use as ip_address in the generated onboarding payload.

fabric_site_name_hierarchy

string / required

Fabric site hierarchy that contains the source device port channels.

Must match the full Catalyst Center fabric site hierarchy.

interface_mappings

list / elements=dictionary

Optional source-to-destination member interface remap list.

Source interfaces listed here are remapped only when they exist in the source device port channel member interface list.

Source interface matching is case-insensitive.

The module fails when a mapped source interface is not present in the source device port channel member interface list.

Destination interface spelling is preserved in the generated payload.

When only_mapped_interfaces is false, source member interfaces not listed here keep their original interface name for 1:1 migration.

destination_interface_name

string / required

Member interface name to use in the destination device port channel payload.

source_interface_name

string / required

Member interface name in the source device port channel payload.

only_mapped_interfaces

boolean

Controls whether generated port channel member interfaces are limited to source interfaces listed in interface_mappings.

When true, only mapped member interfaces are included.

When false, unmapped source member interfaces retain their original interface name for 1:1 migration.

Choices:

source_device_ip

string / required

Source device management IP address to read port channels from.

file_mode

string

Controls how config is written to the YAML file.

overwrite replaces existing file content.

append appends generated YAML content to the existing file.

Choices:

file_path

string

Path for YAML configuration file output.

If omitted, a timestamped default filename is generated.

state

string

Desired state for YAML playbook generation workflow.

Only gathered is supported.

Choices:

validate_response_schema

boolean

Flag for Cisco Catalyst Center SDK to enable the validation of request bodies against a JSON schema.

Choices:

Notes

Note

  • Does not support check_mode

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

  • Requires Python >= 3.10, matching the controller Python versions supported by the collection's minimum ansible-core version (see the collection README for the current ansible-core / Python compatibility range)

Examples

- name: Generate host port assignment and port channel migration configuration
  cisco.catalystcenter.sda_host_port_migration_playbook_config_generator:
    catalystcenter_host: "{{ catalystcenter_host }}"
    catalystcenter_username: "{{ catalystcenter_username }}"
    catalystcenter_password: "{{ catalystcenter_password }}"
    catalystcenter_verify: "{{ catalystcenter_verify }}"
    catalystcenter_port: "{{ catalystcenter_port }}"
    catalystcenter_version: "{{ catalystcenter_version }}"
    state: gathered
    file_path: "host_port_migration_playbook.yml"
    file_mode: overwrite
    config:
      component_specific_filters:
        port_assignments:
          - fabric_site_name_hierarchy: "Global/California/23"
            source_device_ip: "10.0.0.1"
            destination_device_ip: "10.0.0.2"
            interface_mappings:
              - source_interface_name: "GigabitEthernet1/0/1"
                destination_interface_name: "GigabitEthernet1/0/25"
            only_mapped_interfaces: true
        port_channels:
          - fabric_site_name_hierarchy: "Global/California/23"
            source_device_ip: "10.0.0.1"
            destination_device_ip: "10.0.0.2"
            interface_mappings:
              - source_interface_name: "GigabitEthernet1/0/2"
                destination_interface_name: "GigabitEthernet1/0/26"

Return Values

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

Key

Description

response

dictionary

Result of YAML generation.

Returned: always

Sample: :ansible-rv-sample-value:`{"changed": true, "msg": {"components\_processed": 1, "components\_skipped": 0, "configurations\_count": 1, "file\_path": "host\_port\_migration\_playbook.yml", "message": "YAML configuration file generated successfully"}, "status": "success"}`

Authors

  • Vivek Raj (@vivekraj2000)

  • Madhan Sankaranarayanan (@madhansansel)