cisco.dnac.sda_host_port_onboarding_workflow_manager module – Manage host port onboarding in SD-Access Fabric in Cisco Catalyst Center.

Note

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

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.sda_host_port_onboarding_workflow_manager.

New in cisco.dnac 6.17.0

Synopsis

• Manage host onboarding operations such as adding, updating, and deleting port assignments and port channels of Network Devices in SD-Access Fabric.

• API to create port assignment(s) for Network Devices in SD-Access Fabric roles in Cisco Catalyst Center.

• API to Update port assignment(s) for Network Devices in SD-Access Fabric roles in Cisco Catalyst Center.

• API to delete port assignment(s) for Network Devices in SD-Access Fabric roles in Cisco Catalyst Center.

• API to create port channel(s) for Network Devices in SD-Access Fabric roles in Cisco Catalyst Center.

• API to update port channel(s) for Network Devices in SD-Access Fabric roles in Cisco Catalyst Center.

• API to delete port channel(s) for Network Devices in SD-Access Fabric roles in Cisco Catalyst Center.

Requirements

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

• dnacentersdk >= 2.9.2

• python >= 3.9

Parameters

Parameter	Comments
config list / elements=dictionary / required	A list containing detailed configurations for Adding/Updating/Deleting port assignment(s) or port channel(s) of Network Devices in SD-Access Fabric roles in Cisco Catalyst Center.
hostname string	Hostname of the target device in the SD-Access Fabric on which access device ports need to be configured. Either the hostname or IP address of the network device must be provided for performing port assignment or port channel operations. The specified hostname must be identical to the hostname displayed in the inventory section of Cisco Catalyst Center. For example - “DC-T-9300.cisco.local” Note - If only the “ip_address” or “hostname” is provided in the “deleted” state, all port assignment(s) and port channel(s) configured for the specified fabric device will be deleted.
ip_address string	IP address of the target device in the SD-Access Fabric on which access device ports need to be configured. Either the hostname or IP address of the network device must be provided for performing port assignment or port channel operations. The specified IP address must match the management IP displayed in the inventory section of Cisco Catalyst Center. For example - “204.1.2.2” Note - If only the “ip_address” or “hostname” is provided in the “deleted” state, all port assignment(s) and port channel(s) configured for the specified fabric device will be deleted.
port_assignment_details list / elements=dictionary	A list containing configuration details for adding, updating, or deleting port assignment(s) in Cisco Catalyst Center. The “interface_name” and “connected_device_type” fields are required for add and update port assignment(s) operations. For the update port channel(s) operation, the parameters that can be updated include “data_vlan_name”, “voice_vlan_name”, “authentication_template_name” and “interface_description”. For delete port assignment(s) operation, the valid parameters are “interface_name,” “data_vlan_name,” and “voice_vlan_name”. If all three parameters are provided, only port assignments that match all specified criteria are deleted (i.e., AND filtering is applied).
authentication_template_name string / required	Specifies the authentication template applied to the port during the port assignment operation. The available options are “No Authentication”, “Open Authentication”, “Closed Authentication”, and “Low Impact”. The default “authentication_template_name” for all device types is “No Authentication”. For Connected Device Type “TRUNKING_DEVICE”, the “authentication_template_name” must be set to “No Authentication”. Security/scalable groups are only supported with the “No Authentication” profile. Choices: "No Authentication" "Open Authentication" "Closed Authentication" "Low Impact"
connected_device_type string	Specifies the type of access device that needs to be onboarded on the specified interface. Valid options for Connected Device Types are - “USER_DEVICE”, “ACCESS_POINT”, and “TRUNKING_DEVICE”. TRUNKING_DEVICE - Configures the interface as a trunk port. No additional parameters are required for this Connected Device Type. If the “authentication_template_name” is provided, it must be set to ‘No Authentication’ when configuring a “TRUNKING_DEVICE”. ACCESS_POINT - Configures the port for connecting an access point. The “data_vlan_name” parameter is required when configuring “ACCESS_POINT” devices in port assignments. Optionally, the “authentication_template_name” and “interface_description” can also be specified. USER_DEVICE - Configures the port to connect to a host device, such as an IP phone, computer, or laptop. At least one VLAN (“data_vlan_name” or “voice_vlan_name”) is required when configuring a “USER_DEVICE”. Optional parameters include “security_group_name”, “authentication_template_name”, and “interface_description”. Note - The “connected_device_type” cannot be updated from “TRUNK” to “EXTENDED_NODE” unless the protocol configured is PAGP. Choices: "TRUNKING_DEVICE" "ACCESS_POINT" "USER_DEVICE"
data_vlan_name string	Specifies the Data VLAN name or IP address pool to be assigned to the port. This parameter is required when the connected_device_type is set to ACCESS_POINT. At least one VLAN (“data_vlan_name” or “voice_vlan_name”) is required when configuring a “USER_DEVICE”.
interface_description string	A description of the port assignment interface.
interface_name string	Specifies the name of the port or interface on the fabric device where port assignment operations need to be performed. This parameter is required for adding or updating port assignments. For example - “GigabitEthernet2/1/1”
security_group_name string	Specifies the security or scalable group name for the port assignment. Security/scalable groups are only supported with the “No Authentication” profile.
voice_vlan_name string	Specifies the Voice VLAN name or IP address pool to be assigned to the port. At least one VLAN (“data_vlan_name” or “voice_vlan_name”) is required when configuring a “USER_DEVICE”.
port_channel_details list / elements=dictionary	A list containing configuration details for adding, updating, or deleting port channel(s) between a fabric edge and its remotely connected devices in Cisco Catalyst Center. The “interface_names” and “connected_device_type” fields are required for add and update port channel(s) operations. For the update port channel(s) operation, the parameters that can be updated include “connected_device_type” and “port_channel_description”. For delete port channel(s) operation, the valid parameters are “port_channel_name” and “connected_device_type”. If both parameters are provided, only port channels that match the specified criteria are deleted (i.e., AND filtering is applied).
connected_device_type string	Specifies the type of device connected to the port channel. Valid options are “TRUNK” or “EXTENDED_NODE”. To create a port channel between a fabric edge node and an extended node, or between two extended nodes, select “EXTENDED_NODE”. To create a port channel with a fabric edge node or extended node on one side, and a third-party device or server port on the other side, choose “TRUNK”. Choices: "TRUNK" "EXTENDED_NODE"
interface_names list / elements=string	A list of ports/interfaces of the target device in the SD-Access Fabric on which port channel needs to be configured. A maximum of 8 ports are supported in interface_names for “PAGP” and “ON” protocols. A maximum of 16 ports are supported in interface_names for the “LACP” protocol. Example - [“TwoGigabitEthernet2/0/1”, “TwoGigabitEthernet2/0/2”, “TwoGigabitEthernet2/0/3”]
port_channel_description string	A description of the port channel.
port_channel_name string	Specifies the name of an existing port channel in the SD-Access Fabric that needs to be deleted. This parameter is applicable only for delete port channel operations.
protocol string	Specifies the appropriate protocol for the specific Connected Device Type to be configured on the port channel. Valid options are “ON”, “LACP”, and “PAGP”. By default, the protocol is “ON” for “connected_device_type” - “EXTENDED_NODE”. By default, the protocol is “LACP” for “connected_device_type” - “TRUNK”. Protocol field cannot be updated after the initial configuration. The “connected_device_type” cannot be updated from “TRUNK” to “EXTENDED_NODE” unless the protocol configured is PAGP. Choices: "ON" "LACP" "PAGP"
config_verify boolean	Set to True to verify the Cisco Catalyst Center configuration after applying the playbook configuration. 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	Indicates whether debugging is enabled in the Cisco Catalyst Center SDK. Choices: false ← (default) true
dnac_host string / required	The hostname of the Cisco Catalyst Center.
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 password for authentication at the Cisco Catalyst Center.
dnac_port string	Specifies the port number associated with the Cisco Catalyst Center. 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 username for authentication at the Cisco Catalyst Center. Default: "admin"
dnac_verify boolean	Flag to enable or disable SSL certificate verification. Choices: false true ← (default)
dnac_version string	Specifies the version of the Cisco Catalyst Center that the SDK should use. Default: "2.2.3.3"
state string	The desired state of Cisco Catalyst Center after the module execution. Choices: "merged" ← (default) "deleted"
validate_response_schema boolean	Flag for Cisco Catalyst Center SDK to enable the validation of request bodies against a JSON schema. Choices: false true ← (default)

Notes

Note

• SDK Methods used are - devices.Devices.get_device_list - sda.SDA.get_device_info - site_design.SiteDesigns.get_sites - sda.SDA.get_fabric_sites - sda.SDA.get_port_assignments - sda.SDA.get_port_channels - sda.SDA.add_port_assignments - sda.SDA.update_port_assignments - sda.SDA.delete_port_assignments - sda.SDA.add_port_channels - sda.SDA.update_port_channels - sda.SDA.update_port_channels

• Paths used are - GET /dna/intent/api/v1/network-device - GET /dna/intent/api/v1/business/sda/device - GET /dna/intent/api/v1/sites - GET /dna/intent/api/v1/sda/fabricSites - GET /dna/intent/api/v1/sda/portAssignments - GET /dna/intent/api/v1/sda/portChannels - POST /dna/intent/api/v1/sda/portAssignments - PUT /dna/intent/api/v1/sda/portAssignments - DELETE /dna/intent/api/v1/sda/portAssignments - POST /dna/intent/api/v1/sda/portChannels - PUT /dna/intent/api/v1/sda/portChannels - DELETE /dna/intent/api/v1/sda/portChannels

• 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

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

Examples

- name: Add port interfaces and port channels for a specific fabric device
  cisco.dnac.sda_host_port_onboarding_workflow_manager:
    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: "{{dnac_log_level}}"
    state: merged
    config:
      - ip_address: "204.1.2.2"
        port_assignment_details:
          - interface_name: "FortyGigabitEthernet1/1/1"
            connected_device_type: "TRUNKING_DEVICE"

          - interface_name: "FortyGigabitEthernet1/1/2"
            connected_device_type: "TRUNKING_DEVICE"
            authentication_template_name: "No Authentication"
            interface_description: "Trunk Port"

          - interface_name: "FortyGigabitEthernet2/1/1"
            connected_device_type: "ACCESS_POINT"
            data_vlan_name: "AG_23"

          - interface_name: "FortyGigabitEthernet2/1/2"
            connected_device_type: "ACCESS_POINT"
            data_vlan_name: "AG_23"
            authentication_template_name: "No Authentication"
            interface_description: "Access Point Port"

          - interface_name: "GigabitEthernet1/1/1"
            connected_device_type: "ACCESS_POINT"
            data_vlan_name: "AG_23"
            authentication_template_name: "Open Authentication"
            interface_description: "Access Point Port"

          - interface_name: "GigabitEthernet1/1/2"
            connected_device_type: "ACCESS_POINT"
            data_vlan_name: "AG_23"
            authentication_template_name: "Closed Authentication"
            interface_description: "Access Point Port"

          - interface_name: "GigabitEthernet1/1/3"
            connected_device_type: "ACCESS_POINT"
            data_vlan_name: "AG_23"
            authentication_template_name: "Low Impact"
            interface_description: "Access Point Port"

          - interface_name: "GigabitEthernet1/1/4"
            connected_device_type: "USER_DEVICE"
            data_vlan_name: "AG_VLAN_23"

          - interface_name: "GigabitEthernet2/1/1"
            connected_device_type: "USER_DEVICE"
            voice_vlan_name: "VOICE_VLAN_23"

          - interface_name: "GigabitEthernet2/1/2"
            connected_device_type: "USER_DEVICE"
            data_vlan_name: "AG_23"
            voice_vlan_name: "VOICE_VLAN_23"

          - interface_name: "GigabitEthernet2/1/3"
            connected_device_type: "USER_DEVICE"
            data_vlan_name: "AG_23"
            voice_vlan_name: "VOICE_VLAN_23"
            security_group_name: "Guests"

          - interface_name: "GigabitEthernet2/1/4"
            connected_device_type: "USER_DEVICE"
            data_vlan_name: "AG_23"
            voice_vlan_name: "VOICE_VLAN_23"
            security_group_name: "Guests"
            authentication_template_name: "No Authentication"

          - interface_name: "GigabitEthernet2/1/4"
            connected_device_type: "USER_DEVICE"
            data_vlan_name: "AG_23"
            security_group_name: "Guests"
            authentication_template_name: "Closed Authentication"

          - interface_name: "GigabitEthernet2/1/4"
            connected_device_type: "USER_DEVICE"
            voice_vlan_name: "VOICE_VLAN_23"
            authentication_template_name: "Low Impact"
            interface_description: "User Device"

        port_channel_details:
          - interface_names: ["TenGigabitEthernet1/0/37", "TenGigabitEthernet1/0/38", "TenGigabitEthernet1/0/39"]
            connected_device_type: "TRUNK"

          - interface_names: ["TenGigabitEthernet1/0/43", "TenGigabitEthernet1/0/44"]
            connected_device_type: "TRUNK"
            protocol: "ON"

          - interface_names: ["TenGigabitEthernet1/0/45", "TenGigabitEthernet1/0/46", "TenGigabitEthernet1/0/47", "TenGigabitEthernet1/0/48"]
            connected_device_type: "TRUNK"
            protocol: "LACP"

          - interface_names: ["TenGigabitEthernet1/1/2", "TenGigabitEthernet1/1/3", "TenGigabitEthernet1/1/4"]
            connected_device_type: "TRUNK"
            protocol: "PAGP"
            port_channel_description: "Trunk port channel"

          - interface_names: ["TenGigabitEthernet1/1/5", "TenGigabitEthernet1/1/6"]
            connected_device_type: "EXTENDED_NODE"

          - interface_names: ["TenGigabitEthernet1/1/7", "TenGigabitEthernet1/1/8"]
            connected_device_type: "EXTENDED_NODE"
            protocol: "PAGP"
            port_channel_description: "extended node port channel"

- name: Update port interfaces and port channels for a specific fabric device
  cisco.dnac.sda_host_port_onboarding_workflow_manager:
    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: "{{dnac_log_level}}"
    state: merged
    config:
      - hostname: "DC-T-9300.cisco.local"
        port_assignment_details:
          - interface_name: "FortyGigabitEthernet1/1/1"
            connected_device_type: "TRUNKING_DEVICE"
            interface_description: "Trunking device on port 111"

          - interface_name: "GigabitEthernet2/1/4"
            connected_device_type: "USER_DEVICE"
            data_vlan_name: "AG_VLAN_23"
            security_group_name: "Guests"
            authentication_template_name: "Closed Authentication"

          - interface_name: "GigabitEthernet2/1/4"
            connected_device_type: "USER_DEVICE"
            data_vlan_name: "AG_23"
            security_group_name: "Guests"
            authentication_template_name: "Closed Authentication"
            interface_description: "User device at port 214"

        port_channel_details:
          - interface_names: ["TenGigabitEthernet1/1/2", "TenGigabitEthernet1/1/3", "TenGigabitEthernet1/1/4"]
            connected_device_type: "EXTENDED_NODE"
            protocol: 'PAGP'
            port_channel_description: "Trunk port channel"

- name: Delete ALL port assignments and port channels for the fabric device using hostname
  cisco.dnac.sda_host_port_onboarding_workflow_manager:
    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: "{{dnac_log_level}}"
    state: deleted
    config:
      - hostname: "DC-T-9300.cisco.local"

- name: Delete ALL port assignments and port channels for the fabric device using ip_address
  cisco.dnac.sda_host_port_onboarding_workflow_manager:
    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: "{{dnac_log_level}}"
    state: deleted
    config:
      - ip_address: "204.1.2.2"

- name: Delete specific interfaces and port channels using interface names and port channel name
  cisco.dnac.sda_host_port_onboarding_workflow_manager:
    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: "{{dnac_log_level}}"
    state: deleted
    config:
      - ip_address: "204.1.2.2"
        port_assignment_details:
          - interface_name: "FortyGigabitEthernet2/1/2"
            data_vlan_name: "AG_23"

          - interface_name: "GigabitEthernet2/1/3"
            voice_vlan_name: "VOICE_VLAN_23"

        port_channel_details:
          - port_channel_name: "Port-channel2"
            connected_device_type: "TRUNK"

          - port_channel_name: "Port-channel6"
            connected_device_type: "EXTENDED_NODE"

- name: Delete specific interfaces and port channels using interface names and port channel name
  cisco.dnac.sda_host_port_onboarding_workflow_manager:
    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: "{{dnac_log_level}}"
    state: deleted
    config:
      - ip_address: "204.1.2.2"
        port_assignment_details:
          - interface_name: "FortyGigabitEthernet1/1/1"
          - interface_name: "FortyGigabitEthernet1/1/2"
          - interface_name: "GigabitEthernet2/1/1"
          - interface_name: "TenGigabitEthernet1/0/37"
          - interface_name: "TenGigabitEthernet1/0/38"
          - interface_name: "TenGigabitEthernet1/0/39"
        port_channel_details:
          - port_channel_name: "Port-channel2"
          - port_channel_name: "Port-channel5"
          - port_channel_name: "Port-channel6"

- name: Delete interfaces that have specified data vlan assigned
  cisco.dnac.sda_host_port_onboarding_workflow_manager:
    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: "{{dnac_log_level}}"
    state: deleted
    config:
      - hostname: "DC-T-9300.cisco.local"
        port_assignment_details:
          - data_vlan_name: "AG_23"
          - voice_vlan_name: "VOICE_VLAN_23"

- name: Delete all port channels that have Connected Device Type EXTENDED_NODE
  cisco.dnac.sda_host_port_onboarding_workflow_manager:
    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: "{{dnac_log_level}}"
    state: deleted
    config:
      - ip_address: "204.1.2.2"
        port_channel_details:
          - connected_device_type: "EXTENDED_NODE"

Return Values

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

Key	Description
response_1 dictionary	A dictionary with with the response returned by the Cisco Catalyst Center Python SDK Returned: always Sample: "{\n  \"response\":\n    {\n      \"response\": String,\n      \"version\": String\n    },\n  \"msg\": String\n}\n"
response_2 list / elements=string	A string with the response returned by the Cisco Catalyst Center Python SDK Returned: always Sample: ["{\n  \"response\": []", "\n  \"msg\": String\n}\n"]

Authors

• Rugvedi Kapse (@rukapse) Madhan Sankaranarayanan (@madhansansel)

Collection links

• Issue Tracker
• Repository (Sources)