cisco.dnac.discovery_workflow_manager module – A resource module for handling device discovery tasks.

Note

This module is part of the cisco.dnac collection (version 6.20.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.discovery_workflow_manager.

New in cisco.dnac 6.6.0

Synopsis

  • Manages device discovery using IP address, address range, CDP, and LLDP, including deletion of discovered devices.

  • API to discover a device or multiple devices

  • API to delete a discovery of a device or multiple devices

Requirements

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

  • dnacentersdk == 2.6.10

  • python >= 3.9

Parameters

Parameter

Comments

config

list / elements=dictionary / required

List of details of device being managed.

cdp_level

integer

Total number of levels that are there in cdp’s method of discovery

Default: 16

delete_all

boolean

Parameter to delete all the discoveries at one go

Choices:

  • false ← (default)

  • true

discovery_name

string / required

Name of the discovery task

discovery_specific_credentials

dictionary

Credentials specifically created by the user for performing device discovery.

cli_credentials_list

list / elements=dictionary

List of CLI credentials to be used during device discovery.

enable_password

string

Enable password for CLI authentication, mandatory when using CLI credential.

password

string

Password for CLI authentication, mandatory when using CLI credential.

username

string

Username for CLI authentication, mandatory when using CLI credentials.

http_read_credential

dictionary

HTTP read credential is used for authentication purposes and specifically utilized to grant read-only access to certain resources from the device.

password

string

Password for HTTP(S) Read authentication, mandatory when using HTTP credentials.

port

integer

Port for HTTP(S) Read authentication, mandatory for using HTTP credentials.

secure

boolean

Flag for HTTP(S) Read authentication, not mandatory when using HTTP credentials.

Choices:

  • false

  • true

username

string

Username for HTTP(S) Read authentication, mandatory when using HTTP credentials.

http_write_credential

dictionary

HTTP write credential is used for authentication purposes and grants Cisco Catalyst Center the ability to alter configurations, update software, or perform other modifications on a network device.

password

string

Password for HTTP(S) Write authentication, mandatory when using HTTP credentials.

port

integer

Port for HTTP(S) Write authentication, mandatory when using HTTP credentials.

secure

boolean

Flag for HTTP(S) Write authentication, not mandatory when using HTTP credentials.

Choices:

  • false

  • true

username

string

Username for HTTP(S) Write authentication, mandatory when using HTTP credentials.

net_conf_port

string

To be used when network contains IOS XE-based wireless controllers.

This is used for discovery and the enabling of wireless services on the controllers.

Requires valid SSH credentials to work.

Avoid standard ports like 22, 80, and 8080.

snmp_v2_read_credential

dictionary

The SNMP v2 credentials to be created and used for contacting a device via SNMP protocol in read mode.

SNMP v2 also delivers data encryptions, but it uses data types.

community

string

SNMP V2 Read community string enables Cisco Catalyst Center to extract read-only data from device.

description

string

Name/Description of the SNMP read credential to be used for creation of snmp_v2_read_credential.

snmp_v2_write_credential

dictionary

The SNMP v2 credentials to be created and used for contacting a device via SNMP protocol in read and write mode.

SNMP v2 also delivers data encryptions, but it uses data types.

community

string

SNMP V2 Write community string is used to extract data and alter device configurations.

description

string

Name/Description of the SNMP write credential to be used for creation of snmp_v2_write_credential.

snmp_v3_credential

dictionary

The SNMP v3 credentials to be created and used for contacting a device via SNMP protocol in read and write mode.

SNMPv3 is the most secure version of SNMP, allowing users to fully encrypt transmissions, keeping us safe from external attackers.

auth_password

string

Authentication Password of the SNMP v3 protocol to be used.

Must be of length greater than 7 characters.

Not required for NOAUTHNOPRIV snmp_mode.

auth_type

string

Authentication type of the SNMP v3 protocol to be used.

SHA uses Secure Hash Algorithm (SHA) as your authentication protocol.

MD5 uses Message Digest 5 (MD5) as your authentication protocol and is not recommended.

Not required for NOAUTHNOPRIV snmp_mode.

Choices:

  • "SHA"

  • "MD5"

privacy_password

string

Privacy password of the SNMP v3 protocol to be used in AUTHPRIV SNMP mode

Not required for AUTHNOPRIV and NOAUTHNOPRIV snmp_mode.

privacy_type

string

Privacy type/protocol of the SNMP v3 protocol to be used in AUTHPRIV SNMP mode

Not required for AUTHNOPRIV and NOAUTHNOPRIV snmp_mode.

Choices:

  • "AES128"

  • "AES192"

  • "AES256"

snmp_mode

string

Mode of SNMP which determines the encryption level of our community string.

AUTHPRIV mode uses both Authentication and Encryption.

AUTHNOPRIV mode uses Authentication but no Encryption.

NOAUTHNOPRIV mode does not use either Authentication or Encryption.

Choices:

  • "AUTHPRIV"

  • "AUTHNOPRIV"

  • "NOAUTHNOPRIV"

username

string

Username of the SNMP v3 protocol to be used.

discovery_type

string / required

Determines the method of device discovery. Here are the available options. - SINGLE discovers a single device using a single IP address. - RANGE discovers multiple devices within a single IP address range. - MULTI RANGE discovers devices across multiple IP address ranges. - CDP uses Cisco Discovery Protocol to discover devices in subsequent layers of the given IP address. - LLDP uses Link Layer Discovery Protocol to discover devices in subsequent layers of the specified IP address. - CIDR discovers devices based on subnet filtering using Classless Inter-Domain Routing.

Choices:

  • "SINGLE"

  • "RANGE"

  • "MULTI RANGE"

  • "CDP"

  • "LLDP"

  • "CIDR"

global_credentials

dictionary

added in cisco.dnac 6.12.0

Set of various credential types, including CLI, SNMP, HTTP, and NETCONF, that a user has pre-configured in the Device Credentials section of the Cisco Catalyst Center.

If user doesn’t pass any global credentials in the playbook, then by default, we will use all the global credentials present in the Cisco Catalyst Center of each type for performing discovery. (Max 5 allowed)

cli_credentials_list

list / elements=dictionary

Accepts a list of global CLI credentials for use in device discovery.

It’s recommended to create device credentials with both a unique username and a clear description.

description

string

Name of the CLI credential, mandatory when using global CLI credentials.

username

string

Username required for CLI authentication and is mandatory when using global CLI credentials.

http_read_credential_list

list / elements=dictionary

List of global HTTP Read credentials that will be used in the process of discovering devices.

It’s recommended to create device credentials with both a unique username and a clear description for easy identification.

description

string

Name of the HTTP Read credential, mandatory when using global HTTP credentials.

username

string

Username for HTTP Read authentication, mandatory when using global HTTP credentials.

http_write_credential_list

list / elements=dictionary

List of global HTTP Write credentials that will be used in the process of discovering devices.

It’s recommended to create device credentials with both a unique username and a clear description for easy identification.

description

string

Name of the HTTP Write credential, mandatory when using global HTTP credentials.

username

string

Username for HTTP Write authentication, mandatory when using global HTTP credentials.

net_conf_port_list

list / elements=dictionary

List of Global Net conf ports to be used during device discovery.

It’s recommended to create device credentials with unique description.

description

string

Name of the Net Conf Port credential, mandatory when using global Net conf port.

snmp_v2_read_credential_list

list / elements=dictionary

List of Global SNMP V2 Read credentials to be used during device discovery.

It’s recommended to create device credentials with a clear description for easy identification.

description

string

Name of the SNMP Read credential, mandatory when using global SNMP credentials.

snmp_v2_write_credential_list

list / elements=dictionary

List of Global SNMP V2 Write credentials to be used during device discovery.

It’s recommended to create device credentials with a clear description for easy identification.

description

string

Name of the SNMP Write credential, mandatory when using global SNMP credentials.

snmp_v3_credential_list

list / elements=dictionary

List of Global SNMP V3 credentials to be used during device discovery, giving read and write mode.

It’s recommended to create device credentials with both a unique username and a clear description for easy identification.

description

string

Name of the SNMP V3 credential, mandatory when using global SNMP credentials.

username

string

Username for SNMP V3 authentication, mandatory when using global SNMP credentials.

ip_address_list

list / elements=string / required

List of IP addresses to be discovered. For CDP/LLDP/SINGLE based discovery, we should pass a list with single element like - 10.197.156.22. For CIDR based discovery, we should pass a list with single element like - 10.197.156.22/22. For RANGE based discovery, we should pass a list with single element and range like - 10.197.156.1-10.197.156.100. For MULTI RANGE based discovery, we should pass a list with multiple elements like - 10.197.156.1-10.197.156.100 and in next line - 10.197.157.1-10.197.157.100. Maximum of 8 IP address ranges are allowed.

ip_filter_list

list / elements=string

List of IP adddrsess that needs to get filtered out from the IP addresses passed.

lldp_level

integer

Total number of levels that are there in lldp’s method of discovery

Default: 16

preferred_mgmt_ip_method

string

Preferred method for the management of the IP (None/UseLoopBack)

Default: "None"

protocol_order

string

Determines the order in which device connections will be attempted. Here are the options - “telnet” Only telnet connections will be tried. - “ssh, telnet” SSH (Secure Shell) will be attempted first, followed by telnet if SSH fails.

Default: "ssh"

records_to_return

integer

Number of records to return for the header in fetching global v2 credentials

Default: 100

retry

integer

Number of times to try establishing connection to device

start_index

integer

Start index for the header in fetching SNMP v2 credentials

Default: 1

timeout

integer

Time to wait for device response in seconds

use_global_credentials

boolean

Determines if device discovery should utilize pre-configured global credentials.

Setting to True employs the predefined global credentials for discovery tasks. This is the default setting.

Setting to False requires manually provided, device-specific credentials for discovery, as global credentials will be bypassed.

Choices:

  • false

  • true ← (default)

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

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 state of Cisco Catalyst Center after module completion.

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 Method used are discovery.Discovery.get_all_global_credentials_v2, discovery.Discovery.start_discovery, task.Task.get_task_by_id, discovery.Discovery.get_discoveries_by_range, discovery.Discovery.get_discovered_network_devices_by_discovery_id’, discovery.Discovery.delete_discovery_by_id discovery.Discovery.delete_all_discovery discovery.Discovery.get_count_of_all_discovery_jobs

  • Paths used are get /dna/intent/api/v2/global-credential post /dna/intent/api/v1/discovery get /dna/intent/api/v1/task/{taskId} get /dna/intent/api/v1/discovery/{startIndex}/{recordsToReturn} get /dna/intent/api/v1/discovery/{id}/network-device delete /dna/intent/api/v1/discovery/{id} delete /dna/intent/api/v1/delete get /dna/intent/api/v1/discovery/count

  • Removed ‘global_cli_len’ option in v6.12.0.

  • 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: Execute discovery of devices with both global credentials and discovery specific credentials
  cisco.dnac.discovery_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_verify: True
    config:
        - discovery_name: Discovery with both global and job specific credentials
          discovery_type: RANGE
          ip_address_list:
            - 201.1.1.1-201.1.1.100
          ip_filter_list:
            - 201.1.1.2
            - 201.1.1.10
          discovery_specific_credentials:
            cli_credentials_list:
                - username: cisco
                  password: Cisco123
                  enable_password: Cisco123
            http_read_credential:
                username: cisco
                password: Cisco123
                port: 443
                secure: true
            http_write_credential:
                username: cisco
                password: Cisco123
                port: 443
                secure: True
            snmp_v2_read_credential:
                description: snmp_v2-new
                community: Cisco123
            snmp_v2_write_credential:
                description: snmp_v2-new
                community: Cisco123
            snmp_v3_credential:
                username: v3Public2
                snmp_mode: AUTHPRIV
                auth_type: SHA
                auth_password: Lablab123
                privacy_type: AES256
                privacy_password: Lablab123
            net_conf_port: 750
          global_credentials:
            cli_credentials_list:
                - description: ISE
                  username: cisco
                - description: CLI1234
                  username: cli
            http_read_credential_list:
                - description: HTTP Read
                  username: HTTP_Read
            http_write_credential_list:
                - description: HTTP Write
                  username: HTTP_Write
            snmp_v3_credential_list:
                - description: snmpV3
                  username: snmpV3
            snmp_v2_read_credential_list:
                - description: snmpV2_read
            snmp_v2_write_credential_list:
                - description: snmpV2_write
            net_conf_port_list:
                - description: Old_one
          start_index: 1
          records_to_return: 100
          protocol_order: ssh
          retry: 5
          timeout: 3

- name: Execute discovery of devices with discovery specific credentials only
  cisco.dnac.discovery_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_verify: True
    config:
        - discovery_name: Single with discovery specific credentials only
          discovery_type: SINGLE
          ip_address_list:
            - 204.1.1.10
          discovery_specific_credentials:
            cli_credentials_list:
                - username: cisco
                  password: Cisco123
                  enable_password: Cisco123
            http_read_credential:
                username: cisco
                password: Cisco123
                port: 443
                secure: true
            http_write_credential:
                username: cisco
                password: Cisco123
                port: 443
                secure: True
            snmp_v2_read_credential:
                description: snmp_v2-new
                community: Cisco123
            snmp_v2_write_credential:
                description: snmp_v2-new
                community: Cisco123
            snmp_v3_credential:
                username: v3Public2
                snmp_mode: AUTHPRIV
                auth_type: SHA
                auth_password: Lablab123
                privacy_type: AES256
                privacy_password: Lablab123
            net_conf_port: 750
          use_global_credentials: False
          start_index: 1
          records_to_return: 100
          protocol_order: ssh
          retry: 5
          timeout: 3

- name: Execute discovery of devices with global credentials only
  cisco.dnac.discovery_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_verify: True
    config:
        - discovery_name: CDP with global credentials only
          discovery_type: CDP
          ip_address_list:
            - 204.1.1.1
          cdp_level: 16
          global_credentials:
            cli_credentials_list:
                - description: ISE
                  username: cisco
                - description: CLI1234
                  username: cli
            http_read_credential_list:
                - description: HTTP Read
                  username: HTTP_Read
            http_write_credential_list:
                - description: HTTP Write
                  username: HTTP_Write
            snmp_v3_credential_list:
                - description: snmpV3
                  username: snmpV3
            snmp_v2_read_credential_list:
                - description: snmpV2_read
            snmp_v2_write_credential_list:
                - description: snmpV2_write
            net_conf_port_list:
                - description: Old_one
          start_index: 1
          records_to_return: 100
          protocol_order: ssh
          retry: 5
          timeout: 3

- name: Execute discovery of devices with all the global credentials (max 5 allowed)
  cisco.dnac.discovery_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_verify: True
    config:
        - discovery_name: CIDR with all global credentials
          discovery_type: CIDR
          ip_address_list:
            - 204.1.2.0/24
          ip_filter_list:
            - 204.1.2.10
          preferred_mgmt_ip_method: None
          start_index: 1
          records_to_return: 100
          protocol_order: telnet
          retry: 10
          timeout: 3
          use_global_credentials: True

- name: Delete disovery by name
  cisco.dnac.discovery_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_verify: True
    config:
          - discovery_name: Single discovery

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 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 list with the response returned by the Cisco Catalyst Center Python SDK

Returned: always

Sample: ["{\n  \"response\": []", "\n  \"msg\": String\n}\n"]

response_3

dictionary

A string with the response returned by the Cisco Catalyst Center Python SDK

Returned: always

Sample: "{\n  \"response\": String,\n  \"msg\": String\n}\n"

Authors

  • Abinash Mishra (@abimishr) Phan Nguyen (@phannguy) Madhan Sankaranarayanan (@madhansansel)