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

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:

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:

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:

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:

config_verify

boolean

Set to True to verify the Cisco Catalyst Center configuration after applying the playbook configuration.

Choices:

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`

dnac_debug

boolean

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

Choices:

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:

dnac_log_append

boolean

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

Choices:

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

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`

dnac_username

aliases: user

string

The username for authentication at the Cisco Catalyst Center.

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

dnac_verify

boolean

Flag to enable or disable SSL certificate verification.

Choices:

dnac_version

string

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

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

state

string

The desired state of Cisco Catalyst Center after the module execution.

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

  • 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: :ansible-rv-sample-value:`"{\\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: :ansible-rv-sample-value:`["{\\n \\"response\\": []", "\\n \\"msg\\": String\\n}\\n"]`

Authors

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