Chapter 18: Software Management and Network Health Monitoring

1.1 What Is SWIM?

Software Image Management (SWIM) is Catalyst Center's lifecycle automation framework for network device operating system images. It replaces ad-hoc manual processes with a governed pipeline that enforces approval gates, tracks compliance, and coordinates upgrades at scale.

Think of SWIM as a combination of an enterprise software package manager (like apt or yum) and a change-management workflow engine. SWIM maintains a repository of network OS images and enforces the concept of a golden image — the single approved version for each device family and role.

1.2 The Five-Step SWIM Workflow

The SWIM lifecycle consists of five sequential operations. Distribution and activation are asynchronous — they return a taskId immediately and require polling for completion.

1.3 Core SWIM API Endpoints

All endpoints require the X-Auth-Token header obtained from /dna/system/api/v1/auth/token.

1.4 Golden Image Compliance Enforcement

Once you tag an image golden for a site/family/role combination, Catalyst Center continuously evaluates every device for compliance. Non-compliant devices (running a non-golden OS version) can be queried programmatically and automatically upgraded:

GET /dna/intent/api/v1/image/importation?isTaggedGolden=false&siteId=<uuid>

1.5 Python SDK — Async Task Polling Pattern

The dnacentersdk library wraps all SWIM REST endpoints. The critical pattern every SWIM integration must implement is async task polling:

def poll_task(task_id, timeout=600, interval=10):
    """Poll a Catalyst Center async task until completion or timeout."""
    elapsed = 0
    while elapsed < timeout:
        result = api.task.get_task_by_id(task_id=task_id)
        task_data = result.response
        if task_data.isError:
            raise RuntimeError(f"Task failed: {task_data.failureReason}")
        if task_data.endTime:  # Task completed successfully
            return task_data
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")

1.6 Ansible SWIM: swim_workflow_manager

The cisco.dnac.swim_workflow_manager Ansible module handles the full lifecycle in a single task. The dnac_api_task_timeout and dnac_task_poll_interval parameters control async wait behavior. Setting taggingPriority: true supersedes any previously tagged golden image for the same combination.

1.7 SWIM at Scale: Scheduling Maintenance Windows

The scheduleAt parameter accepts a UTC epoch timestamp in milliseconds. Distribution can happen during business hours (non-disruptive) while activation is deferred to the weekend window — enabling fire-and-forget upgrade campaigns across hundreds of devices.

2.1 The Assurance Architecture

Catalyst Center Assurance continuously collects telemetry from every managed device using SNMP polling, model-driven streaming telemetry (gRPC/gNMI), syslog ingestion, NetFlow records, and 802.11 wireless radio data. Raw telemetry is normalized, correlated, and aggregated into health scores that update every five minutes.

2.2 The Health Scoring Model

Individual Device Health Score uses a weakest-link model:

Device Health Score = MIN(System Health, Data Plane Connectivity, Control Plane Connectivity)

Scores: 8–10 = Healthy, 4–7 = Fair, 1–3 = Poor. A device scoring 9/3/8 gets an overall score of 3.

Overall Network Health Score:

Network Health Score (%) = (Count of Devices with Score 8-10) / (Total Monitored Devices) × 100

Devices in maintenance mode are excluded from this calculation.

2.3 Client Health Score

Client health uses the same 8–10 healthy threshold but is maintained separately for wired and wireless populations. This separation prevents a large healthy wired fleet from masking a spike in wireless issues after an AP firmware upgrade.

2.4 Application Health Score and CVD Thresholds

Thresholds are customizable per traffic class via PUT /dna/intent/api/v1/AssuranceGetHealthScoreDefinitions.

2.5 Historical Health Queries

All three Assurance APIs accept an optional timestamp query parameter (epoch milliseconds) for point-in-time historical retrieval. Catalyst Center retains Assurance data for a configurable period (typically 90 days).

ts_ms = int(calendar.timegm(target_time.timetuple()) * 1000)
historical_health = get_health(token, "network-health", params={"timestamp": ts_ms})

3.1 Meraki API-Based Health Monitoring

Unlike Catalyst Center (on-premises), Meraki monitoring is cloud-native. All telemetry flows to the Meraki cloud dashboard and is accessible via REST API using an API key in the X-Cisco-Meraki-API-Key header at base URL https://api.meraki.com/api/v1/.

3.2 SD-WAN (vManage) Health Monitoring

vManage REST API uses session cookie auth from POST /j_security_check. Key endpoints include GET /dataservice/device for inventory/status, GET /dataservice/device/counters for OMP/BFD counters, and GET /dataservice/alarms for active fabric alarms.

3.3 Cross-Platform Health Aggregation

Large enterprises span multiple controllers: Catalyst Center (campus), vManage (SD-WAN), and Meraki (branches). A normalization layer translates controller-specific schemas into a common format:

# Catalyst Center device → common schema
{"source": "Catalyst Center", "health_score": device.overallHealth,
 "status": "healthy" if health >= 8 else "degraded"}

# Meraki device → common schema
{"source": "Meraki", "health_score": 10 if status=="online" else 1}

# SD-WAN device → common schema
{"source": "SD-WAN", "health_score": 10 if reachability=="reachable" else 1}

3.4 Alert Aggregation and Deduplication

Alert storms occur when a single upstream failure (a WAN circuit going down) generates dozens of downstream alerts across multiple controllers simultaneously. An effective aggregation layer must:

1. Correlate by time window — group alerts arriving within a 60-second window affecting the same network segment
2. De-duplicate by root cause — create one "WAN circuit failure" alert rather than 30 individual device alerts
3. Enrich with topology context — understand parent-child relationships (WAN router → downstream switches → clients)
4. Suppress during maintenance — suppress alerts for devices in scheduled maintenance windows

4.1 The Self-Healing Maturity Model

Cisco IT's production automation handles 99.998% of all network alerts without human intervention, processing millions of daily events.

4.2 Catalyst Center Event Notifications and Webhooks

Instead of polling health APIs every five minutes, subscribe to specific events — Catalyst Center pushes notifications via HTTPS POST the moment conditions change. Event domains include Assurance (health degradation, AI anomalies), SWIM (distribution/activation completion), and Network (reachability changes, interface transitions).

Two-step setup:

1. Register a webhook destination via POST /dna/intent/api/v1/event/webhook
2. Subscribe to specific event IDs via POST /dna/intent/api/v1/event/subscription

Common Assurance event IDs: NETWORK-DEVICES-3-250 (device unreachable), NETWORK-DEVICES-3-251 (high CPU), NETWORK-DEVICES-3-252 (memory threshold), NETWORK-CLIENTS-3-502 (client onboarding failure).

4.3 Issue Enrichment API

Before executing remediation, enrich the raw event. The Issue Enrichment API returns root cause analysis, recommended actions, affected hosts, and historical occurrence count. Pass the issue ID in both the URL path and the entity_value header:

headers = {
    "X-Auth-Token": token,
    "entity_type": "issue_id",   # Required header
    "entity_value": issue_id
}

4.4 Flask Webhook Receiver and REMEDIATION_MAP Pattern

The central orchestration pattern is a REMEDIATION_MAP dict mapping event IDs to handler functions. Each handler receives enriched context and decides whether to auto-fix, escalate, or log:

REMEDIATION_MAP = {
    "NETWORK-DEVICES-3-250": handle_device_unreachable,
    "NETWORK-DEVICES-3-251": handle_high_cpu,
    "NETWORK-CLIENTS-3-502": handle_client_onboarding_failure,
}

The webhook endpoint must always return HTTP 200 — Catalyst Center expects acknowledgement regardless of internal processing outcome.

4.5 NSO for Multi-Device Remediation

NSO's MAAPI Python API provides atomic multi-device transactions with rollback. Changes to two devices either both commit together or neither does — preventing partial failure states that leave the network worse than before:

with ncs.maapi.single_write_trans("admin", "python") as t:
    try:
        primary.config.ios__interface.GigabitEthernet[iface].shutdown = True
        backup.config.ios__interface.GigabitEthernet["0/1"].shutdown = False
        t.apply()   # Atomic: both commit or neither does
    except Exception as e:
        t.revert()  # Roll back both devices
        raise

4.6 Notification Integrations

Webex: POST to https://webexapis.com/v1/messages with Authorization: Bearer {token} and {"roomId": ..., "text": ...}.

Slack: POST to an incoming webhook URL with an attachments payload. Color-code by severity: green (info), orange (warning), red (critical).

PagerDuty: POST to https://events.pagerduty.com/v2/enqueue with routing key and severity.