Cisco DNA Poller

The Cisco DNA Poller microservice polls devices, interface data, site data, topology data, and metric data from the Cisco Catalyst Center (formerly Cisco DNA Center). It can also make API calls to create an event webhook, and event subscription to get events.

This microservice supports the discovery and insertion of topology hierarchy provided by Cisco Catalyst Center. The hierarchy reflects the structure defined in Cisco DNA Poller (for example, sites, devices, interfaces and connection between interfaces). For each vertex in the hierarchy, the microservice also captures and stores any associated metadata.

This microservice is part of the Discovery, Event, Metric, and Topology microservice pipelines. See Understanding Microservice Pipelines in Unified Assurance Concepts for conceptual information about microservice pipelines.

You can configure redundancy settings for this microservice when you deploy it. See Configuring Microservice Redundancy for general information.

Cisco DNA Poller Prerequisites

Before deploying the Cisco DNA Poller microservice, confirm that the following prerequisites are met:

  1. A microservice cluster is set up. See Microservice Cluster Setup.

  2. The Pulsar microservice is deployed.

Before discovering or polling devices with this poller, you must also deploy the following microservices:

See the different pipelines in Understanding Microservice Pipelines in Unified Assurance Concepts for more information about how these microservices work together.

Deploying Cisco DNA Poller

To deploy the microservice, run the following commands:

su - assure1
export NAMESPACE=<namespace>
export WEBFQDN=<webFQDN> 
a1helm install <microservice-release-name> assure1/cisco-dna-poller -n $NAMESPACE --set global.imageRegistry=$WEBFQDN

In the commands:

You can also use the Unified Assurance UI to deploy microservices. See Deploying a Microservice by Using the UI for more information.

After deploying the microservice, confirm that the Cisco Catalyst Center webhook and subscription have been created successfully by reviewing the microservice log: 1. From the Configuration menu, select Microservices, then Workloads, and then Deployments.

  1. Expand the namespace where you deployed the microservice and select Logs in the cisco-dna-poller row.

  2. Check for an error message similar to the following: "Webhook destination already set or failed."

  3. If the error appears, manually create the Cisco Catalyst Center webhook and subscription as described in Manually Creating the Cisco Catalyst Center Webhook and Subscription.

Changing Cisco DNA Poller Configuration Parameters

When running installation command, you can optionally change default configuration parameter values by including them in the command with additional --set arguments (or --set-string arguments). You can add as many additional --set arguments as you need.

For example, set a parameter described in Default Cisco DNA Poller Configuration by adding --set configData.<parameter_name>=<parameter_value>. For example, --set configData.LOG_LEVEL=DEBUG.

Default Cisco DNA Poller Configuration

The following table describes the default configuration parameters found in the Helm chart under configData for the Cisco DNA Poller microservice.

Name Default Value Possible Values Notes
LOG_LEVEL INFO FATAL, ERROR, WARN, INFO, DEBUG The logging level used by the microservice.
STREAM_INPUT "" persistent://assure1/discovery/cisco-dna-poller-zoneX The path to the Pulsar topic to get data from. The topic at end of path may be any text value.
STREAM_OUTPUT "" persistent://assure1/discovery/discovery-service-zoneX The path to the Pulsar topic to send data to. The topic at end of path may be any text value.
STREAM_OUTPUT_METRIC persistent://assure1/metric/sink Text, 255 characters The path to the Pulsar topic to send metric data to. The topic at end of path may be any text value.
PROXY_URL "" Text, 255 characters The proxy URL to use.
CONFIG_CHECK_INTERVAL_M 5 Integer The interval, in minutes, after which to refresh the device configuration from the database.
WEBHOOK_USE_SSL false Boolean Whether to use http or https when creating the Cisco Catalyst Center webhook.
WEBHOOK_NAME "ua-webhook" Text, 255 characters The name of the Cisco Catalyst Center webhook to create and subscribe to.
WEBHOOK_DESCRIPTION "Webhook for UA event delivery" Text, 255 characters The description of the Cisco Catalyst Center webhook to create.
WEBHOOK_INGRESS_ENDPOINT "/webhook-service" Text, 255 characters The ingress endpoint for the Unified Assurance Webhook Collector microservice.
WEBHOOK_ENDPOINT "/webhook/cisco-dna" Text, 255 characters The Unified Assurance endpoint, which will be appended to the WEBHOOK_INGRESS_ENDPOINT, where Cisco Catalyst Center should send events.
WEBHOOK_METHOD "POST" Text, 255 characters The method to use when creating the Cisco Catalyst Center webhook.
WEBHOOK_SUBSCRIPTION_NAME "ua-subscription" Text, 255 characters The name of the Cisco Catalyst Center subscription to create.
SEND_LEGACY_METRIC_PAYLOAD "false" Text, 255 characters The type of metric payload send to the Metric Sink microservice. Set this to false to send metrics in the format expected by the Observability Analytics database. Set this to true to send metrics in the format expected by the legacy Metric database.
REDUNDANCY_POLL_PERIOD 5 Integer The number of seconds between status checks from the secondary microservice to the primary microservice.
REDUNDANCY_FAILOVER_THRESHOLD 4 Integer The number of times the primary microservice must fail checks before the secondary microservice becomes active.
REDUNDANCY_FALLBACK_THRESHOLD 1 Integer The number of times the primary microservice must succeed checks before the secondary microservice becomes inactive.

Topology Data Created by the Microservice

The Cisco DNA Poller creates the vertex data described in the following table.

Vertex Type Description Properties
Network Vertex The root vertex with the same name as the Cisco Catalyst Center server. N/A
Site Vertex Site data collected from the Cisco Catalyst Center server.
  • TimestampModified
  • SiteID
  • _source
  • Address
  • Country
  • Latitude
  • Longitude
  • Type
Device Vertex Device data for each site.
  • IP
  • MAC
  • CustomName
  • SerialNo
  • Family
  • CiscoDnaID
  • DeviceID
  • _source
  • TimestampModified
Interface Vertex Interface data for each device.
  • IfIndex
  • IfName
  • IfSpeed
  • IfDescr
  • IfAlias
  • IfPhysAddress
  • IfOperStatus
  • IfAdminStatus
  • TypeName
  • CiscoDnaID
  • CiscoDnaDeviceID
  • RootDeviceID
  • TimestampModified
  • _source

The Cisco DNA Poller creates the following edge data:

Metrics Collected by the Microservice

This microservice collects the metrics described in the following table for Cisco Catalyst Center devices, in either the Observability Analytics database format or the legacy Metric database format, depending on the value of SEND_LEGACY_METRIC_PAYLOAD.

Metric Name Type
CPU Utilization Percentage
Memory Utilization Percentage

Configuring Cisco DNA Poller Event Collection

When you deploy the Cisco DNA Poller, it automatically creates an event webhook in Cisco Catalyst Center and subscribes to it, and then publishes events received from this subscription to the Unified Assurance Webhook Collector microservice.

After deployment, if the microservice log returns an error indicating that it could not connect to Cisco Catalyst Center, you can create the webhook and subscription manually. See Manually Creating the Cisco Catalyst Center Webhook and Subscription.

The Cisco DNA Poller uses the following details when configuring event collection:

You can deploy the microservice using the default values for these configuration parameters, or specify them with custom values.

When you deploy the microservice without specifying the webhook configuration values, the default values create the following Unified Assurance webhook endpoint:

http://<host_of_cluster_master_node>:9080/webhook-service/webhook/cisco-dna

If you add --set configData.WEBHOOK_USE_SSL=true when deploying the microservice, the remaining default values create the following Unified Assurance webhook endpoint:

https://<host_of_cluster_master_node>:9443/webhook-service/webhook/cisco-dna

Manually Creating the Cisco Catalyst Center Webhook and Subscription

If the microservice cannot automatically create the Cisco Catalyst Center webhook and subscription, you can create them manually by using API commands. The following examples use cURL.

  1. Get the Cisco Catalyst Center username and password for a user whose role allows them to create webhooks.

  2. Generate the token to use for Cisco Catalyst Center API requests, replacing the placeholders with their actual values:

    export DNA_SERVER= <Cisco Catalyst Center server URL>
export DNA_USERNAME= <Cisco Catalyst Center username>
export DNA_PASSWORD= <Cisco Catalyst Center password>
curl -u "${DNA_USERNAME}:${DNA_PASSWORD}" -sk -X POST \
    --url "${DNA_SERVER}/dna/system/api/v1/auth/token" \
    --data '{}' > cisco-dna.token

  3. Create the webhook:

    Note:

    If your system does not have the jq command, set DNA_TOKEN to the value of the Token key in the cisco-dna.token file.

    export DNA_TOKEN=$(cat cisco-dna.token | jq -r .Token)
export WEBHOOK_URL= <UA_Webhook_Collector_URL>
cat << EOF >> cisco-dna.webhook.request
{
    "name": "ua-webhook", 
    "description": "Webhook for UA event delivery", 
    "url": "${WEBHOOK_URL}",
    "method": "POST",
    "trustCert": true,
    "isProxyRoute": true
}
EOF
curl -sk --header 'Content-Type: application/json' \
    --header "X-Auth-Token: ${DNA_TOKEN}" -X POST \
    --url "${DNA_SERVER}/dna/intent/api/v1/event/webhook" \
    --data @cisco-dna.webhook.request

    where <UA_Webhook_Collector_URL> is the Unified Assurance Webhook Collector endpoint URL generated when you deployed the microservice. For example:

    http://<host_of_cluster_master_node>:9080/webhook-service/webhook/cisco-dna

  4. Get the information for the newly-created webhook:

    curl -sk --header 'Content-Type: application/json' \
    --header "X-Auth-Token: ${DNA_TOKEN}" \
    --url "${DNA_SERVER}/dna/intent/api/v1/event/webhook" > cisco-dna.webhook.infos

  5. Create the webhook subscription:

    Note:

    If your system does not have the jq command, set WEBHOOK_ID to the value of the webhookId key in the cisco-dna.webhook.infos file, where name is ua-webhook.

    export WEBHOOK_ID=$(cat cisco-dna.webhook.infos | jq '.statusMessage.[] | select(.name == "ua-webhook") | .webhookId')
cat << EOF >> cisco-dna.webhook-subscription.request
[{
    "name": "ua-subscription",
    "subscriptionEndpoints": [{
        "instanceId": "${WEBHOOK_ID}",
        "subscriptionDetails": { "connectorType": "REST" }
    }],
    "filter": {
        "severities": ["0","1","2","3","4","5"]
    }
}]
EOF
curl -sk --header 'Content-Type: application/json' \
    --header "X-Auth-Token: ${DNA_TOKEN}" -X POST \
    --url "${DNA_SERVER}/dna/intent/api/v1/event/subscription/rest" \
    --data @cisco-dna.webhook-subscription.request

Problems you might encounter: