cisco.dnac.sda_host_port_onboarding_playbook_config_generator module -- Generate YAML configurations playbook for 'sda_host_port_onboarding_workflow_manager' module.
Note
This module is part of the cisco.dnac collection (version 6.49.0).
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.sda_host_port_onboarding_playbook_config_generator.
New in cisco.dnac 6.44.0
Synopsis
Automates brownfield YAML playbook generation for SDA host port onboarding configurations deployed in Cisco Catalyst Center infrastructure.
Extracts port assignments, port channels, and wireless SSID configurations via REST APIs for fabric sites managed in SDA environments.
Generates YAML files compatible with sda_host_port_onboarding_workflow_manager module for configuration documentation, port onboarding auditing, disaster recovery, and multi-fabric deployment standardization.
Supports auto-discovery mode for complete fabric infrastructure extraction or component-based filtering for targeted extraction (port assignments, port channels, wireless SSIDs).
Transforms camelCase API responses to snake_case YAML format with comprehensive header comments and metadata.
Requirements
The below requirements are needed on the host that executes this module.
dnacentersdk >= 2.3.7.9
python >= 3.9
PyYAML >= 5.1
Parameters
Parameter |
Comments |
|---|---|
A dictionary of filters for generating YAML playbook compatible with the `sda_host_port_onboarding_workflow_manager` module. Filters specify which components to include in the YAML configuration file. If "components_list" is specified, only those components are included, regardless of the filters. If config is not provided or is empty, all configurations for all port assignments, port channels and wireless SSIDs will be generated. This is useful for complete brownfield infrastructure discovery and documentation. |
|
Filters to specify which components to include in the YAML configuration file. If "components_list" is specified, only those components are included, regardless of other filters. If filters for specific components (e.g., port_assignments, port_channels, or wireless_ssids) are provided without explicitly including them in components_list, those components will be automatically added to components_list. At least one of components_list or component filters must be provided. |
|
List of SDA host port onboarding components to include in YAML configuration. Valid values are 'port_assignments' for interface port assignments, 'port_channels' for port channel configurations, and 'wireless_ssids' for wireless SSID mappings to VLANs within fabric sites. If specified, only the listed components will be included in the generated YAML file. If not specified but component filters (port_assignments, port_channels, or wireless_ssids) are provided, those components are automatically added to this list. If neither components_list nor any component filters are provided, an error will be raised. Choices: |
|
Filters for port channel configuration extraction. Each list entry targets one fabric site with optional device-level filtering by management IP address, serial number, or hostname. Extracts only port assignments for specified fabric site hierarchies and optionally only for devices matching the specified device_ips, serial_numbers, or hostnames within those sites. When multiple device filters (device_ips, serial_numbers, hostnames) are specified in the same list entry, they are combined using AND logic. A device must match ALL specified filters to be included. Each filter type is optional and independent. Omitting a filter type means no restriction on that attribute. Fabric site names must be full hierarchical paths (case-sensitive). If not specified when component included in components_list, extracts all port assignments across all fabric sites and all devices. |
|
List of device management IP addresses to filter extraction within this fabric site. Each IP is matched against the managementIpAddress field resolved from Catalyst Center for each device in the fabric site. Devices whose management IP does not match any IP in this list are skipped. Combined with serial_numbers and hostnames using AND logic when multiple filter types are specified in the same list entry. A device must satisfy all specified filters to be included. Scoped per list entry. Each fabric site entry can specify its own set of device IPs independently. If omitted, no IP-based filtering is applied and all devices in the fabric site are candidates (subject to other filters). For example, ["1.1.1.1", "1.1.1.2"] |
|
Fabric site hierarchical paths to extract port assignments. Site names must match exact hierarchical paths in Catalyst Center (case-sensitive). Extracts port assignments for all devices within specified fabric sites. For example, "Global/USA/San Jose/Building1" |
|
List of device hostnames to filter extraction within this fabric site. Each hostname is matched against the hostname field resolved from Catalyst Center for each device in the fabric site. Devices whose hostname does not match any value in this list are skipped. Combined with device_ips and serial_numbers using AND logic when multiple filter types are specified in the same list entry. A device must satisfy all specified filters to be included. Scoped per list entry. Each fabric site entry can specify its own set of hostnames independently. If omitted, no hostname-based filtering is applied and all devices in the fabric site are candidates (subject to other filters). For example, ["switch1", "switch2"] |
|
List of device serial numbers to filter extraction within this fabric site. Each serial number is matched against the serialNumber field resolved from Catalyst Center for each device in the fabric site. Devices whose serial number does not match any value in this list are skipped. Combined with device_ips and hostnames using AND logic when multiple filter types are specified in the same list entry. A device must satisfy all specified filters to be included. Scoped per list entry. Each fabric site entry can specify its own set of serial numbers independently. If omitted, no serial number-based filtering is applied and all devices in the fabric site are candidates (subject to other filters). For example, ["FJC2327U0S2", "FJC2327U0S3"] |
|
Filters for port channel configuration extraction. Each list entry targets one fabric site with optional device-level filtering by management IP address, serial number, or hostname. Extracts only port channels for specified fabric site hierarchies and optionally only for devices matching the specified device_ips, serial_numbers, or hostnames within those sites. When multiple device filters (device_ips, serial_numbers, hostnames) are specified in the same list entry, they are combined using AND logic. A device must match ALL specified filters to be included. Each filter type is optional and independent. Omitting a filter type means no restriction on that attribute. Fabric site names must be full hierarchical paths (case-sensitive). If not specified when component included in components_list, extracts all port channels across all fabric sites and all devices. |
|
List of device management IP addresses to filter extraction within this fabric site. Each IP is matched against the managementIpAddress field resolved from Catalyst Center for each device in the fabric site. Devices whose management IP does not match any IP in this list are skipped. Combined with serial_numbers and hostnames using AND logic when multiple filter types are specified in the same list entry. A device must satisfy all specified filters to be included. Scoped per list entry. Each fabric site entry can specify its own set of device IPs independently. If omitted, no IP-based filtering is applied and all devices in the fabric site are candidates (subject to other filters). For example, ["1.1.1.1", "1.1.1.2"] |
|
Fabric site hierarchical paths to extract port channels. Site names must match exact hierarchical paths in Catalyst Center (case-sensitive). Extracts port channel configurations for all devices within specified fabric sites. For example, "Global/USA/San Jose/Building1" |
|
List of device hostnames to filter extraction within this fabric site. Each hostname is matched against the hostname field resolved from Catalyst Center for each device in the fabric site. Devices whose hostname does not match any value in this list are skipped. Combined with device_ips and serial_numbers using AND logic when multiple filter types are specified in the same list entry. A device must satisfy all specified filters to be included. Scoped per list entry. Each fabric site entry can specify its own set of hostnames independently. If omitted, no hostname-based filtering is applied and all devices in the fabric site are candidates (subject to other filters). For example, ["switch1", "switch2"] |
|
List of device serial numbers to filter extraction within this fabric site. Each serial number is matched against the serialNumber field resolved from Catalyst Center for each device in the fabric site. Devices whose serial number does not match any value in this list are skipped. Combined with device_ips and hostnames using AND logic when multiple filter types are specified in the same list entry. A device must satisfy all specified filters to be included. Scoped per list entry. Each fabric site entry can specify its own set of serial numbers independently. If omitted, no serial number-based filtering is applied and all devices in the fabric site are candidates (subject to other filters). For example, ["FJC2327U0S2", "FJC2327U0S3"] |
|
Filters for wireless SSID configuration extraction. Extracts only wireless SSID to VLAN mappings for specified fabric site hierarchies. Fabric site names must be full hierarchical paths (case-sensitive). If not specified when component included in components_list, extracts all wireless SSID mappings across all fabric sites. |
|
List of fabric site hierarchical paths to extract wireless SSID mappings. Site names must match exact hierarchical paths in Catalyst Center (case-sensitive). Extracts VLAN to SSID mappings for specified fabric sites. For example, ["Global/USA/San Jose/Building1", "Global/USA/RTP/Building2"] |
|
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` |
|
Indicates whether debugging is enabled in the Cisco Catalyst Center SDK. Choices: |
|
The hostname of the Cisco Catalyst Center. |
|
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: |
|
Determines the mode of the file. Set to True for 'append' mode. Set to False for 'write' mode. Choices: |
|
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: :ansible-option-default:`"dnac.log"` |
|
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"` |
|
The password for authentication at the Cisco Catalyst Center. |
|
Specifies the port number associated with the Cisco Catalyst Center. Default: :ansible-option-default:`"443"` |
|
Specifies the interval in seconds between successive calls to the API to retrieve task details. Default: :ansible-option-default:`2` |
|
The username for authentication at the Cisco Catalyst Center. Default: :ansible-option-default:`"admin"` |
|
Flag to enable or disable SSL certificate verification. Choices: |
|
Specifies the version of the Cisco Catalyst Center that the SDK should use. Default: :ansible-option-default:`"2.2.3.3"` |
|
Controls how config is written to the YAML file.
Choices: |
|
Absolute or relative path for YAML configuration file output. If not provided, generates default filename in current working directory with pattern 'sda_host_port_onboarding_playbook_config_<YYYY-MM-DD_HH-MM-SS>.yml' Example default filename 'sda_host_port_onboarding_playbook_config_2026-02-27_14-31-46.yml' Directory created automatically if path does not exist. Supports YAML file extension (.yml or .yaml). |
|
Desired state for YAML playbook generation workflow. Only 'gathered' state supported for brownfield SDA host port onboarding extraction. Choices: |
|
Flag for Cisco Catalyst Center SDK to enable the validation of request bodies against a JSON schema. Choices: |
Notes
Note
SDK methods utilized - sda.get_port_assignments, sda.get_port_channels, fabric_wireless.retrieve_the_vlans_and_ssids_mapped_to_the_vlan_within_a_fabric_site, devices.get_device_by_id, sda.get_fabric_sites
API paths utilized - GET /dna/intent/api/v1/sda/portAssignments, GET /dna/intent/api/v1/sda/portChannels, GET /dna/intent/api/v1/sda/fabrics/{fabricId}/vlanToSsids GET /dna/intent/api/v1/network-device/{id} GET /dna/intent/api/v1/sda/fabricSites
Module is idempotent; multiple runs generate identical YAML content except timestamp in header comments.
Check mode supported; validates parameters without file generation.
Device management IP addresses are resolved from device IDs for all port configurations enabling device-specific port onboarding playbooks.
Generated YAML uses OrderedDumper for consistent key ordering enabling version control.
Fabric site hierarchical paths must match exact Catalyst Center fabric site structure.
Auto-population of components_list: If component-specific filters (such as port_assignments, port_channels, or wireless_ssids) are provided without explicitly including them in components_list, those components will be automatically added to components_list. This simplifies configuration by eliminating the need to redundantly specify components in both places.
Example of auto-population behavior: If you provide filters for port_assignments without including port_assignments in components_list, the module will automatically add port_assignments to components_list before processing. This allows you to write more concise playbooks.
Validation requirements: If component_specific_filters is provided, at least one of the following must be true - (1) components_list contains at least one component, OR (2) Component-specific filters (e.g., port_assignments, port_channels, wireless_ssids) are provided. If neither condition is met, the module will fail with a validation error.
Does not support
check_modeThe plugin runs on the control node and does not use any ansible connection plugins instead embedded connection manager from Cisco Catalyst Center SDK
The parameters starting with dnac_ are used by the Cisco Catalyst Center Python SDK to establish the connection
See Also
See also
- cisco.dnac.sda_host_port_onboarding_workflow_manager
Module for managing SDA host port onboarding workflows in Cisco Catalyst Center.
Examples
- name: Generate YAML playbook for host port onboarding workflow manager
which includes all fabric sites's host port onboarding details
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_mode: "overwrite"
- name: Generate YAML Configuration with File Path specified
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
- name: Generate YAML with multiple fabric sites and per-site device IP filtering
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list: ["port_assignments", "port_channels"]
port_assignments:
- fabric_site_name_hierarchy: "Global/Site_India/Karnataka/Bangalore"
device_ips:
- 1.1.1.1
- fabric_site_name_hierarchy: "Global/USA/RTP/Building2"
port_channels:
- fabric_site_name_hierarchy: "Global/Site_India/Karnataka/Bangalore"
device_ips:
- 1.1.1.1
- name: Generate YAML Configuration with specific component port assignments filters
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list: ["port_assignments"]
port_assignments:
- fabric_site_name_hierarchy: "Global/Site_India/Karnataka/Bangalore"
device_ips:
- 1.1.1.1
- 1.1.1.2
- name: Generate YAML Configuration with specific component port assignments filters
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list: ["port_assignments"]
port_assignments:
- fabric_site_name_hierarchy: "Global/Site_India/Karnataka/Bangalore"
serial_numbers:
- FJC27251Z8B
- FJC27251Z8C
- name: Generate YAML Configuration with specific component port assignments filters
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list: ["port_assignments"]
port_assignments:
- fabric_site_name_hierarchy: "Global/Site_India/Karnataka/Bangalore"
hostnames:
- switch1
- switch2
- name: Generate YAML Configuration with specific component port channels filters
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list: ["port_channels"]
port_channels:
- fabric_site_name_hierarchy: "Global/Site_India/Karnataka/Bangalore"
device_ips:
- 1.1.1.1
- 1.1.1.2
- name: Generate YAML Configuration with specific component port channels filters
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list: ["port_channels"]
port_channels:
- fabric_site_name_hierarchy: "Global/Site_India/Karnataka/Bangalore"
serial_numbers:
- FJC27251Z8B
- FJC27251Z8C
- name: Generate YAML Configuration with specific component port channels filters
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list: ["port_channels"]
port_channels:
- fabric_site_name_hierarchy: "Global/Site_India/Karnataka/Bangalore"
hostnames:
- switch1
- switch2
- name: Generate YAML with AND-combined device filters per site
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list:
- "port_assignments"
- "port_channels"
port_assignments:
# Site 1: AND filter — device must match IP AND hostname
- fabric_site_name_hierarchy: "Global/USA/San Jose/Building1"
device_ips:
- 1.1.1.1
hostnames:
- switch1
# Site 2: single filter — only serial number filtering
- fabric_site_name_hierarchy: "Global/USA/RTP/Building2"
serial_numbers:
- FJC2327U0S2
- FJC2327U0S3
# Site 3: no device filter — extracts all devices
- fabric_site_name_hierarchy: "Global/India/Bangalore/Building3"
port_channels:
- fabric_site_name_hierarchy: "Global/USA/San Jose/Building1"
device_ips:
- 1.1.1.1
- name: Generate YAML Configuration with specific component wireless ssids filters
cisco.dnac.sda_host_port_onboarding_playbook_config_generator:
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: true
dnac_log_level: DEBUG
state: gathered
file_path: "host_onboarding_playbook.yml"
file_mode: "overwrite"
config:
component_specific_filters:
components_list: ["wireless_ssids"]
wireless_ssids:
fabric_site_name_hierarchy:
- "Global/Site_India/Karnataka/Bangalore"
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
A dictionary with with the response returned by the Cisco Catalyst Center Python SDK Returned: always |
|
A string with the response returned by the Cisco Catalyst Center Python SDK Returned: always |